{"openapi":"3.1.0","info":{"title":"MeshTube API","version":"1.0.0","description":"Read the MeshTube catalog and media, and act on your own channel, social graph and wallet.\n\nCreate a key in MeshTube under Preferences \u2192 Developer API keys (registered accounts), and send it as `X-API-Key: mtk_...` or `Authorization: Bearer mtk_...`. A key acts as you, limited to the scopes you gave it, and is rate-limited (default 120 requests/minute; 429 with Retry-After when exceeded). Keys cannot manage keys, change your account, or administer the node.\n\nScopes:\n- `read`: Read the catalog, channels, media and your own account data (all GET routes).\n- `content`: Upload, edit and delete your videos, images, albums, series, movies and live streams; run transcodes.\n- `social`: Comment, like, subscribe, join circles and record scrobbles as you.\n- `payments`: Spend and move your credits and Cashu: transfers, PPV unlocks, top-ups, gifts, ad settlements.\n\nPublic routes need no key. A request with an invalid or revoked key is refused (401) even on a public route."},"servers":[{"url":"https://pocketpeer.io"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"mtk_<key_id>_<secret>"}}},"paths":{"/api/vod":{"get":{"tags":["Catalog"],"summary":"List the public video catalog (and your vault when authenticated).","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"owner_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only videos from this channel"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/vod/{vod_id}/share":{"get":{"tags":["Catalog"],"summary":"Share package for a video: canonical URLs, Bao tree root, federation announcements.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"vod_id","in":"path","required":true,"schema":{"type":"string"},"description":"Video id"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/channel/{channel_id}":{"get":{"tags":["Catalog"],"summary":"A channel: profile, videos, subscriber counts.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identity id or handle"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/series":{"get":{"tags":["Catalog"],"summary":"TV series with ordered episodes (with your progress when authenticated).","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/movies/calendar":{"get":{"tags":["Catalog"],"summary":"Upcoming movie and series releases.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/comments":{"get":{"tags":["Catalog"],"summary":"Comments on a video or stream.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"target_id","in":"query","required":true,"schema":{"type":"string"},"description":"vod:<vod_id> or live:<stream_id>"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/did/{identity_id}":{"get":{"tags":["Catalog"],"summary":"DID document (did:nostr) for an identity.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"identity_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identity id"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/state":{"get":{"tags":["Catalog"],"summary":"One snapshot of everything the web app shows: streams, catalog, node status.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"stream_id","in":"query","required":false,"schema":{"type":"string"},"description":"Selected live stream"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/video/vod/{vod_id}.mp4":{"get":{"tags":["Media"],"summary":"Stream a video. Supports Range (206); X-Bao-Tree-Root lets you verify bytes. Paid videos answer 402 with a Cashu payment request.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"vod_id","in":"path","required":true,"schema":{"type":"string"},"description":"Video id"},{"name":"Range","in":"header","schema":{"type":"string"},"description":"bytes=start-end"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/video/live/{stream_id}/index.m3u8":{"get":{"tags":["Media"],"summary":"Live CMAF playlist for a stream.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"stream_id","in":"path","required":true,"schema":{"type":"string"},"description":"Stream id"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/media/mesh/{image_id}":{"get":{"tags":["Media"],"summary":"An image (thumbnail, avatar, gallery image).","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"image_id","in":"path","required":true,"schema":{"type":"string"},"description":"Image id"}],"security":[{},{"ApiKey":[]},{"Bearer":[]}],"x-meshtube-scope":"public"}},"/api/credits":{"get":{"tags":["Account"],"summary":"Your credits wallet, Circle wallets, recent ledger and payment events.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["read"]},{"Bearer":["read"]}],"x-meshtube-scope":"read"}},"/api/gifts":{"get":{"tags":["Account"],"summary":"Gifts and recommendations sent to you.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["read"]},{"Bearer":["read"]}],"x-meshtube-scope":"read"}},"/api/circles":{"get":{"tags":["Account"],"summary":"Circles you can see.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["read"]},{"Bearer":["read"]}],"x-meshtube-scope":"read"}},"/api/images":{"get":{"tags":["Account"],"summary":"Your image vault and collections.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"owner_id","in":"query","required":false,"schema":{"type":"string"},"description":"Another channel (public images only)"}],"security":[{"ApiKey":["read"]},{"Bearer":["read"]}],"x-meshtube-scope":"read"}},"/api/identities":{"get":{"tags":["Account"],"summary":"Your identity and the identities visible to you.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["read"]},{"Bearer":["read"]}],"x-meshtube-scope":"read"}},"/api/vod/upload":{"post":{"tags":["Content"],"summary":"Upload a video as the key owner. Send JSON with data_b64, multipart/form-data, or raw bytes with fields as query parameters. X-Expected-Bao-Root rejects a corrupted upload.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data_b64"],"properties":{"data_b64":{"type":"string","description":"The file, base64"},"title":{"type":"string","description":"Title"},"description":{"type":"string","description":"Description"},"content_type":{"type":"string","description":"clip | movie | series | music | vibe | ad"},"visibility":{"type":"string","description":"public | vault_only"},"price_msat_per_mb":{"type":"integer","description":"0 for free"},"hashtags":{"type":"string","description":"Space-separated #tags"},"expected_bao_root":{"type":"string","description":"Bao root the upload must match"}}}}}},"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/vod/{vod_id}/update":{"post":{"tags":["Content"],"summary":"Edit your video: title, description, chapters, music, age rating, price.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"vod_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your video"}],"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/vod/{vod_id}/delete":{"post":{"tags":["Content"],"summary":"Delete your video.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"vod_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your video"}],"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/transcode/job":{"post":{"tags":["Content"],"summary":"Re-encode your video into a rendition ladder on mesh compute (owner only).","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vod_id"],"properties":{"vod_id":{"type":"string","description":"Your video"},"profiles":{"type":"array","items":{"type":"string"},"description":"e.g. 1080p, 720p, 480p"}}}}}},"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/streams":{"post":{"tags":["Content"],"summary":"Create a live stream you broadcast.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"stream_id":{"type":"string","description":"Optional id"},"title":{"type":"string","description":"Title"},"price_msat_per_mb":{"type":"integer","description":"0 for free"}}}}}},"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/streams/{stream_id}/ingest":{"post":{"tags":["Content"],"summary":"Push a CMAF segment into your stream (owner only).","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"parameters":[{"name":"stream_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your stream"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data_b64"],"properties":{"data_b64":{"type":"string","description":"Segment bytes, base64"},"is_keyframe":{"type":"boolean"}}}}}},"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/images/upload":{"post":{"tags":["Content"],"summary":"Upload an image to your vault.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/series/progress":{"post":{"tags":["Content"],"summary":"Save your watch progress in a series.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["series_id","episode_id"],"properties":{"series_id":{"type":"string","description":"Series"},"episode_id":{"type":"string","description":"Episode"},"position_sec":{"type":"number"}}}}}},"security":[{"ApiKey":["content"]},{"Bearer":["content"]}],"x-meshtube-scope":"content"}},"/api/social/comment":{"post":{"tags":["Social"],"summary":"Comment on a video or stream.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_id","body"],"properties":{"target_id":{"type":"string","description":"vod:<id> or live:<id>"},"body":{"type":"string","description":"Comment text"}}}}}},"security":[{"ApiKey":["social"]},{"Bearer":["social"]}],"x-meshtube-scope":"social"}},"/api/social/like":{"post":{"tags":["Social"],"summary":"Like a video or stream.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_id"],"properties":{"target_id":{"type":"string","description":"vod:<id> or live:<id>"}}}}}},"security":[{"ApiKey":["social"]},{"Bearer":["social"]}],"x-meshtube-scope":"social"}},"/api/social/subscribe":{"post":{"tags":["Social"],"summary":"Subscribe to (or unsubscribe from) a channel.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel_id"],"properties":{"channel_id":{"type":"string","description":"Channel"}}}}}},"security":[{"ApiKey":["social"]},{"Bearer":["social"]}],"x-meshtube-scope":"social"}},"/api/scrobble/record":{"post":{"tags":["Social"],"summary":"Record a play to your scrobble history.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["social"]},{"Bearer":["social"]}],"x-meshtube-scope":"social"}},"/api/credits/transfer":{"post":{"tags":["Payments"],"summary":"Send credits or Cashu from your wallet (or a Circle you founded).","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to_id","amount_credits"],"properties":{"to_kind":{"type":"string","description":"user | circle"},"to_id":{"type":"string","description":"Recipient"},"amount_credits":{"type":"integer","description":"1..1,000,000"},"payment_rail":{"type":"string","description":"credits | cashu"},"memo":{"type":"string","description":"Note"},"idempotency_key":{"type":"string","description":"Retry-safe key"}}}}}},"security":[{"ApiKey":["payments"]},{"Bearer":["payments"]}],"x-meshtube-scope":"payments"}},"/api/credits/unlock-ppv":{"post":{"tags":["Payments"],"summary":"Unlock a paid video or stream with credits or a Cashu token.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["payments"]},{"Bearer":["payments"]}],"x-meshtube-scope":"payments"}},"/api/credits/topup":{"post":{"tags":["Payments"],"summary":"Open a Stripe Checkout Session; nothing is credited until it is paid.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_credits"],"properties":{"amount_credits":{"type":"integer","description":"Credits to buy"}}}}}},"security":[{"ApiKey":["payments"]},{"Bearer":["payments"]}],"x-meshtube-scope":"payments"}},"/api/credits/topup/confirm":{"post":{"tags":["Payments"],"summary":"Credit a paid Checkout Session (once per session).","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stripe_session_id"],"properties":{"stripe_session_id":{"type":"string","description":"cs_live_... or cs_test_..."}}}}}},"security":[{"ApiKey":["payments"]},{"Bearer":["payments"]}],"x-meshtube-scope":"payments"}},"/api/gifts/send":{"post":{"tags":["Payments"],"summary":"Gift or recommend a video, optionally with credits attached.","responses":{"200":{"description":"OK"},"401":{"description":"No or invalid credentials"},"403":{"description":"Key lacks the scope, or you do not own the target"},"429":{"description":"Rate limited; see Retry-After"}},"security":[{"ApiKey":["payments"]},{"Bearer":["payments"]}],"x-meshtube-scope":"payments"}}}}