developerAPIintegration

API Spec: Streaming Live-Session Metadata into Torrent Magnet Feeds

bbidtorrent

2026-02-08

11 min read

Developer API spec to stream live-session metadata into magnet feeds for synchronized discovery and low-cost delivery.

Cut bandwidth costs and make live streams discoverable: broadcast live-session metadata into magnet feeds

If you run, integrate with, or build livestream platforms, you know the pain: huge egress bills, brittle CDNs when audience spikes, and poor discoverability for archived sessions. At the same time, users want synchronized, low-latency playback and reliable ways to jump to a timestamped moment in a long stream. This spec defines a developer-facing API that livestream platforms can use to broadcast live session metadata into torrent magnet feeds so peers, indexers, and clients can discover and synchronize to live and near-live sessions with confidence.

Quick summary — what you get

A concise REST API for publishing, updating, and revoking live-session metadata tied to torrent magnet links
A JSON metadata schema that maps timestamps to torrent piece ranges and segments
Real-time distribution patterns: webhooks, SSE, and DHT/Tracker hints for fast discovery
Security and verification best practices: signatures, content hashes, and auditable revocation
Integration recipes: how to embed metadata pointers into magnet URIs and feeds

Why this matters in 2026

In late 2025 and early 2026 we saw two relevant trends accelerate: social platforms and niche networks are adding live badges and integrations that favor discoverability of live events, and P2P delivery is maturing as a cost-effective complement to traditional CDNs. For example, smaller social networks and decentralized platforms have rolled out features that make live signals first-class metadata. That creates an opening: livestream platforms can expose rich session metadata directly into the torrent discovery plane so clients and indexers can subscribe to and synchronize with sessions without incurring heavy egress costs. For practical reductions in latency and playback performance, see our guide on live stream conversion and latency.

Put another way: magnet feeds are a natural, low-friction channel for discovery. By publishing authoritative session metadata alongside magnet links, you enable low-cost distribution and timestamp-accurate seeking for large files and long live archives. For indexing and discovery best practices in an edge era, see indexing manuals for the edge era.

High-level design and actors

The API and workflow are designed around these actors:

Livestream platform: Producer of live sessions and authoritative metadata (session id, timestamps, segments, pricing).
Metadata broadcaster: API endpoint owned by the platform that signs and publishes metadata to magnet feeds, trackers, webhooks, and DHT pointers.
Indexer / Discovery service: Crawls magnet feeds and subscribes to webhooks to make sessions searchable and to push notifications to clients and social networks.
Clients and players: Torrent-enabled viewers that read metadata, convert timestamp to piece index, and request pieces from peers / webseed. If you build or test players, reviews of portable streaming rigs can be informative for prototyping capture and playback setups.

Core principles

Authoritative metadata: a single signed source of truth for session timelines and piece mappings
Incremental updates: session metadata must support small delta updates without republishing entire manifests
Interoperability: use magnet params and existing tracker features where possible, and provide optional extensions for richer discovery
Security and provenance: sign metadata and provide mechanisms for verification and revocation. See security takeaways and auditing discussions in our operations security notes (security takeaways).

API spec overview

The API is intentionally small so it can be implemented by platforms quickly. All endpoints are authenticated and return JSON. Timestamps use ISO 8601 and are UTC.

Authentication

Use API keys or OAuth 2.0 client credentials. All webhooks must be signed with a private key, and the signature delivered in header x-bt-signature. The public key is published at the platform's metadata discovery endpoint.

Endpoints

POST /v1/sessions

Create a new session metadata manifest

Request body: session manifest (see schema below)
Response: 201 Created, with body containing the session id and magnet manifest pointer

PATCH /v1/sessions/{session_id}

Patch existing manifest with delta updates (segments added, timestamp corrections)

Idempotency: clients must support idempotency keys via header x-idempotency-key

GET /v1/sessions/{session_id}

Retrieve authoritative manifest

POST /v1/sessions/{session_id}/terminate

Mark a session as ended and publish final piece mapping and archive pointers

POST /v1/subscriptions

Supported events: session.started, session.updated, session.segment.available, session.terminated

Metadata schema

Below is the recommended minimal manifest. Implementations may extend it, but keep the core fields unchanged.


  {
    'version': '1.0',
    'session_id': 'string',
    'title': 'string',
    'creator': {
      'id': 'string',
      'display_name': 'string',
      'public_key_url': 'https://host/public_key.pem'
    },
    'status': 'live|paused|ended',
    'start_time': '2026-01-17T12:00:00Z',
    'last_update': '2026-01-17T12:05:03Z',
    'segments': [ ... ],
    'trackers': ['https://tracker.example/announce'],
    'signatures': { ... },
    'policy': { ... }
  }

Key fields explained

segments: Each segment maps a contiguous time range to a byte range and piece index range. This mapping is how clients convert a playback timestamp to the torrent piece to request.
magnet: Canonical magnet for the segment or the session archive. We recommend including an xs param that points to the authoritative manifest URL.
signatures: Manifest and per-segment signatures to enable provenance verification.

How to embed metadata into magnet URIs

Magnets already support freeform key value pairs. Two practical approaches make metadata discoverable while staying compatible with existing clients.

1) Use the existing xs param to point to JSON manifest

xs is for exact source, so put the manifest URL there. Example magnet:

magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567&dn=Show+Title&tr=https://tracker.example/announce&xs=https://meta.example/sessions/SESSION_ID/manifest.json

Indexers and clients that obey xs can fetch the JSON manifest and read timestamp mappings. For formal indexing guidance and feed conventions, consult indexing manuals for the edge era.

2) Use a lightweight xm param for short metadata pointers

For ecosystems you control, define an xm magnet parameter convention where xm points to a compact binary manifest or content-addressed block. Example:

magnet:?xt=urn:btih:...&xm=urn:btmh:sha256:BASE32MANIFESTID

This pattern lets specialized clients discover rich metadata without fetching a larger HTTP manifest first.

Synchronization: timestamp to piece mapping

Synchronized seeking requires converting a playback timestamp to a byte offset and then to the torrent piece index. Use this algorithm pattern:

Find the segment where timestamp t is within start_ts and start_ts+duration_s.
Compute time offset into segment: offset_s = t - start_ts.
Compute byte offset: byte_offset = floor((offset_s / duration_s) * segment_byte_length)
Map byte_offset to piece index using piece_length. Request the piece index and a small window of neighbors to ensure smooth playback.

For variable bitrate content or chunked containers, you should include a per-segment index table that maps intra-segment timestamps to piece indices to avoid drift. Provide this index as an optional 'seek_index' array in the segment manifest. For performance-sensitive systems, caching and optimized piece fetch strategies (including review of caching tools) are covered in our cacheops review.

Real-time discovery patterns

Broadcasting metadata into magnet feeds is only useful if indexers and clients receive updates quickly. Use a combination of the following:

Webhooks for push to indexers and social networks. Deliver events session.started, session.segment.available, session.terminated. For guidance on integrating third‑party feeds like BBC and YouTube, see our developer starter guide to automating downloads from feeds.
SSE or WebSocket channels for low-latency client updates when available.
DHT announcements or tracker announces including a metadata hint parameter. Trackers may add a metaurl parameter that points to the manifest.
Magnet feed: Generate an Atom/RSS style feed where each entry includes the magnet URI and a manifest pointer. Indexers poll the feed for new sessions as a fallback; this pattern works well with discovery and local loyalty systems that surface moments to communities (local discovery playbooks).

Security, trust, and compliance

Shipping live metadata to a distributed discovery plane increases the attack surface. Build verification and moderation into the pipeline.

Sign all manifests: Publishers sign the manifest with the platform private key. Public keys are discoverable at the creator.public_key_url field.
Verify piece-level integrity: Clients verify content blocks against the torrent infohash and per-segment sha256 where provided.
Revocation: Support manifest revocation by issuing a short-lived revocation record signed by the platform. Include a revocation pointer in the magnet xs value if the session is taken down.
Malware and policy checks: Integrate automated scanning before publishing metadata. Indexers should respect platform takedown flags in manifests.
Legal metadata: Include license and takedown contact in policy to make compliance actions machine-readable.

Best practice: treat the manifest as an auditable source of truth. Every indexer and client that consumes magnet metadata should validate signatures before displaying or seeding content.

Webhook contract and verification

Webhook payloads carry the same session manifest structure and an event type. Webhooks must include:

Header x-bt-signature: base64 signature of the payload
Header x-bt-key-id: identifier for the public key used
Header x-bt-event: session.started|session.updated|segment.available|session.terminated

Verification steps for consumers:

Fetch public key at creator.public_key_url or platform publisher key store keyed by x-bt-key-id.
Verify signature over the raw JSON payload using Ed25519 or RSA depending on publisher.
If valid, process event; otherwise discard and alert.

Example integration recipes

1) Livestream platform publishes a session (curl example)

curl -X POST 'https://api.example.com/v1/sessions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{\n    'session_id': 'session-abc-123',\n    'title': 'Evening Dev Stream',\n    'creator': { 'id': 'user-42', 'display_name': 'DevAlice', 'public_key_url': 'https://meta.example/user-42.pub' },\n    'status': 'live',\n    'start_time': '2026-01-17T19:00:00Z',\n    'segments': []\n  }'

2) Adding a segment as it becomes available

PATCH /v1/sessions/session-abc-123
  Body:
  {
    'segments': [ ... ]
  }

3) Simple NodeJS webhook verifier snippet

const crypto = require('crypto')
  function verify(payloadRaw, signatureB64, pubKeyPem) {
    const sig = Buffer.from(signatureB64, 'base64')
    const verify = crypto.createVerify('SHA256')
    verify.update(payloadRaw)
    verify.end()
    return verify.verify(pubKeyPem, sig)
  }

Monetization, micropayments, and access control

The manifest supports optional payment and access pointers. In 2026 we see more platforms combining paywalls with P2P distribution for archive content.

Include payment_pointer or price fields in policy for per-session payments.
For gated live segments, include a gating token URL and ephemeral key exchange over HTTPS before revealing a webseed URL.
Consider blockchain pointers or signed receipts if you need pay-per-view receipts and transparent royalty splits. For playbook ideas around monetization and notification strategies, see notification monetization playbooks.

Operational guidance

Rate limits: impose reasonable rate limits on session creation and segment updates. Offer batch endpoints for high-frequency streams.
Backpressure: if downstream indexers are slow, queue events and provide a replay API for missed updates.
Monitoring: publish metrics about manifest publishes, signatures, webhook deliveries, and magnet feed hits. Tie these into observability and SLO tooling — see observability guidance.
Testing: provide a sandbox magnet feed that indexers and clients can poll for integration tests.

Migration patterns and compatibility

You can adopt this system incrementally:

Start by publishing archived session manifests, adding xs pointers to existing magnet URIs.
Expose an event webhook for new session announcements so indexers can pick them up.
Gradually add real-time segment updates and seek_index tables for low-latency clients.

Future roadmap and 2026 predictions

Over the next 24 months we expect:

Wider adoption of metadata pointers in magnets and tracker extensions for real-time discovery
Hybrid CDN + P2P playback becoming the default for large archives and popular live sessions
Indexers and social platforms surfacing timestamped moments via signed manifests, improving trust and moderation. These timestamped moments are already driving new formats in video coverage of events (hybrid music/video formats).
More standardized BEPs or a successor spec that formalizes metadata extensions and real-time events

Actionable checklist for implementers

Publish a signed manifest at an HTTPS URL and include that URL in the magnet xs param
Implement POST /v1/sessions and PATCH updates with idempotency keys
Provide webhooks with strong signatures and publish public keys for verification
Include per-segment map entries so clients can translate timestamps to piece indexes
Expose a revocation mechanism and policy fields for takedowns and access control

Example end-to-end flow

Livestream starts; platform creates session manifest and returns a magnet with xs pointing to the manifest.
Platform pushes session.started webhook to indexers. Indexers publish discovery records and post social updates.
As segments finalize, the platform PATCHes segment entries and issues segment.available webhooks.
Clients fetch the manifest via the xs URL, compute piece indexes from timestamp, and request pieces from peers and webseeds.
When session ends, platform publishes final archive magnet and marks session.terminated with revocation pointer set if necessary.

Closing thoughts

Embedding authoritative livestream metadata into magnet feeds unlocks two powerful outcomes for developers and operators in 2026: lower delivery costs through P2P collaboration, and better timestamp-accurate discovery that drives engagement. This spec is a practical, incremental path to integrating your livestreaming system with the torrent discovery ecosystem while keeping trust, provenance, and compliance front and center. For resilience and architecture patterns that support this model, see building resilient architectures and developer cost signals in developer productivity and cost signals.

If you want a concrete next step, implement the minimal manifest and the POST /v1/sessions endpoint in your dev environment, generate magnets with an xs pointer to the manifest, and run a test indexer that consumes the webhook and populates a search index. Youll be surprised how fast discoverability improves. For hands-on testing workflows and sandbox ideas, our caching and test harness notes are a good companion.

Call to action

Ready to prototype? Sign up for the BidTorrent developer sandbox, get API keys, and try our magnet metadata simulator. Join the developer mailing list to get the reference OpenAPI spec, sample code, and a compatibility checklist for trackers and clients.

bidtorrent

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.