{ "openapi": "3.1.0", "info": { "title": "ViewStream API", "description": "The ViewStream API lets your CMS, newsroom tools and backends do everything ViewStream Studio does: register and\npublish video, run live channels and their programme guide, cut clips, add subtitles, read audience statistics,\nprotect playback and receive events.\n\n> **Try it out calls the production API.** Requests you send from this page are real: they create, change and\n> delete data of the tenant your API key belongs to. Use a key with read-only scopes while exploring. Your key is\n> kept only in this browser tab's memory — it is never stored or sent anywhere except in the `Authorization`\n> header of the requests you make.\n\n## Base URL\n\n`https://api.viewstream.co.il` — every path below starts with `/v1`. The API is JSON over HTTPS (TLS 1.2+).\nTimestamps are RFC 3339 in UTC (`2026-09-30T08:15:00Z`); ids are UUIDs.\n\n## Authentication\n\nSend an API key as a bearer token:\n\n```\nAuthorization: Bearer vs_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nCreate keys in **Studio → Integrations → API keys** (or with `POST /v1/api-keys`). The full key is shown **once**;\nViewStream stores only a hash. A key belongs to one tenant and carries a fixed set of scopes. Revoke a key at any\ntime; revoked keys answer `401`. Keep keys on your servers — never ship one in a web page or an app.\n\n## Scopes\n\nEvery operation lists the scope it needs as **Required scope** (and `x-required-scope` in the spec). A key\nwithout it gets `403 insufficient_scope`. A few operations check an extra scope only for one field (for example\n`publish` on an asset needs `assets:publish`); their descriptions say so. Studio users get scopes from their\nrole; the last column shows the lowest role that has each scope.\n\n| Scope | Allows | Lowest Studio role that has it |\n|---|---|---|\n| `assets:read` | List and read assets, jobs, trash, library sections, posters, subtitle tracks and library imports; the tenant branding and defaults. | viewer |\n| `assets:write` | Register, edit, re-encode and delete assets; uploads of posters; library sections; library imports; retry jobs; edit subtitle cues. | editor |\n| `assets:publish` | Publish an asset (`publish` on create or patch). | publisher |\n| `assets:purge` | Delete trashed assets permanently, empty the trash, set its retention. | admin |\n| `clips:read` | List and read clips. | viewer |\n| `clips:write` | Cut and delete clips. | editor |\n| `clips:publish` | Publish a clip (`publish: true`). | publisher |\n| `channels:read` | Read channels, programmes (EPG), recordings, catch-up lists, boundaries and blackouts. | viewer |\n| `channels:write` | Create and change channels, their EPG sources and programmes; also edits and publishes the guide. | engineer |\n| `channels:operate` | Start/stop channels, see ingest secrets, rotate the SRT passphrase. | engineer |\n| `uploads` | Browser/API multipart uploads (`/v1/uploads`). | editor |\n| `prewarm` | Pre-warm the edges. | engineer |\n| `delivery:write` | Purge, CDN distributions, playback policies and attach points, player configurations, blackouts. | engineer |\n| `webhooks:manage` | Outbound webhooks, inbound CMS hooks and event-export destinations. | engineer |\n| `storage:manage` | Storage keys of the tenant. | engineer |\n| `keys:manage` | API keys and playback signing keys. | engineer |\n| `stats:read` | Statistics, traffic, sessions (without viewer ids), distributions and policies (read), leaks and revocations (read). | viewer |\n| `stats:pii` | Viewer ids in session search and hashed IPs in event export. | admin |\n| `events:read` | The server-sent event stream and the Studio inbox. | viewer |\n| `team:manage` | Members, roles and invitations. | admin |\n| `notifications:manage` | Notification rules, monitors and alert destinations (e-mail, Telegram); acknowledging alerts. | admin |\n| `billing:read` | Usage figures of the tenant (`GET /v1/billing/usage`). | owner |\n| `tenant:settings` | Tenant-wide settings — branding, defaults, subtitles, packaging, image upscaling, lip-sync, catch-up exclusions. | owner |\n| `sites:read` | Read ViewStream Sites objects (sites, pages, shows, people, menus, theme). | viewer |\n| `sites:write` | Edit sites, pages, shows and people (drafts). | editor |\n| `sites:publish` | Publish pages, menus and themes. | publisher |\n| `sites:admin` | Create/delete sites, domains, routes, theme CSS. | engineer |\n| `playback:sign` | Issue tokenised playback URLs for your backend. | engineer |\n| `security:manage` | Dismiss leaks, revoke playback sessions, leak settings, A/B watermark settings, variants and traces of leaked recordings. | engineer |\n| `epg:write` | Edit the programme guide (staged as a draft in review mode). | editor |\n| `epg:publish` | Publish the guide and manage its publishing destinations. | publisher |\n| `support:read` | Read the tenant's support requests and their conversation. | viewer |\n| `support:write` | Open support requests, reply to them and close them. | viewer |\n| `ai:read` | Read AI artefacts (article drafts and published articles) and the review queue. | viewer |\n| `ai:write` | Edit AI artefacts before they are published, and reject them. | editor |\n| `ai:publish` | Approve and publish AI artefacts (the site shows them; artifact.published fires). | publisher |\n\n## Errors\n\nErrors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details with\n`Content-Type: application/problem+json`:\n\n```json\n{\n \"type\": \"https://viewstream.co.il/problems/insufficient_scope\",\n \"title\": \"The API key lacks the scope this route needs\",\n \"status\": 403,\n \"detail\": \"this route requires scope assets:write\",\n \"request_id\": \"019286a2-3b22-7c4b-9a1b-3c5d7e9f1a2d\"\n}\n```\n\n| `type` suffix | Status | Meaning |\n|---|---|---|\n| `invalid_credentials` | 401 | Missing, malformed, unknown or revoked API key |\n| `insufficient_scope` | 403 | The key lacks the scope in `detail` |\n| `forbidden` | 403 | Not allowed for this tenant or object |\n| `feature_disabled` | 403 / 503 | Not available to this tenant (e.g. CDN-only tenants have no assets, channels, clips or players) or not enabled on this deployment |\n| `not_found` | 404 | No such object in your tenant |\n| `conflict` | 409 | The change conflicts with the current state (duplicate `external_id`, stale `If-Match`, …) |\n| `validation_error` | 422 | The body or query is invalid; `errors[]` lists `{field, detail}` |\n| `lock_window` | 409 | The guide change reaches into the channel's locked hours |\n| `rate_limited` | 429 | Too many requests; wait `Retry-After` seconds |\n| `internal_error` | 500 | Our fault — quote the `request_id` to support |\n| `not_ready` | 503 | A dependency is unavailable; retry with backoff |\n\nEvery response carries `X-Request-Id`; include it when you contact support.\n\n## Pagination\n\nLong lists are cursor-paginated, newest first: pass `limit` (the maximum is documented per operation) and read\n`next_cursor` from the response. Send it back as `?cursor=` for the next page; `next_cursor: null` means the end.\nCursors are opaque — do not build or parse them. Lists without `cursor` return everything (or the newest N, as\ntheir description says).\n\n```\nGET /v1/assets?limit=50\n→ {\"items\": [...50 assets...], \"next_cursor\": \"MDE5Mjg2YTI...\"}\nGET /v1/assets?limit=50&cursor=MDE5Mjg2YTI...\n→ {\"items\": [...], \"next_cursor\": null}\n```\n\n## Rate limits\n\nEach API key may send **20 requests per second** with bursts of up to **100**. Over the limit the API answers\n`429 rate_limited` with `Retry-After` (seconds). Some operations have their own limits, stated in their\ndescriptions (edge pre-warm: 6 per minute per tenant; the playback checker: 12 runs per minute per tenant).\nBack off exponentially on `429` and `503`.\n\n## Idempotency and caching\n\n`GET`, `PUT` and `DELETE` are idempotent. `POST /v1/assets` with an `external_id` is safe to retry: a duplicate\nanswers `409` instead of creating a second asset. API responses are `Cache-Control: no-store`.\n\n## Events\n\nSubscribe to webhooks (`/v1/webhooks`) for `asset.ready`, `clip.ready` and the other events. Deliveries are signed:\n`X-VS-Signature: sha256=`; reject timestamps older\nthan 5 minutes. For analytics pipelines use event export (`/v1/event-destinations`) to S3, Kafka, HTTPS or GA4.\n\n## Sites Delivery API\n\nThe public, cacheable read API behind ViewStream Sites (`/s/v1`) has its own document — pick\n**Sites Delivery API** at the top of this page.\n", "contact": { "name": "ViewStream by Interhost Networks", "url": "https://www.viewstream.co.il" }, "license": { "name": "Proprietary — for ViewStream customers", "url": "https://www.viewstream.co.il" }, "version": "0.2.0" }, "servers": [ { "url": "https://api.viewstream.co.il", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "assets", "description": "Video on demand. Register a source (an S3 key under your ingest prefix, a URL, or an upload), and ViewStream\nprobes, transcodes and packages it; the asset moves `registered → probing → queued → encoding → packaging →\nready`. Publish it to make it playable, patch its metadata, re-encode, or delete it (it goes to the trash and\ncan be restored until it is purged). Posters, people and subtitle tracks hang off assets.\n\nTypical flow: `POST /v1/assets` → wait for the `asset.ready` webhook (or poll `GET /v1/assets/{id}`) →\n`PATCH /v1/assets/{id}` with `{\"publish\": true}` (needs `assets:publish`).\n" }, { "name": "uploads", "description": "Multipart uploads straight to ViewStream storage (parts of up to 64 MiB); complete the upload and register the asset." }, { "name": "library", "description": "Library sections (collections) that group assets, one level of nesting; items can be added, removed and moved in bulk." }, { "name": "library-imports", "description": "Import an existing video library from your website's sitemap: create an import, review the discovered items,\nstart it; ViewStream creates the assets and fetches the media in the background (idempotent — already imported\nitems are skipped).\n" }, { "name": "jobs", "description": "The processing jobs of your tenant (probe, transcode, package, subtitles, …), their events and failures; retry failed jobs one by one or by group." }, { "name": "channels", "description": "Live channels: create a channel, feed it (SRT or RTMP), start and stop it. Each channel is recorded continuously,\nwhich powers start-over, catch-up by programme, live-to-VOD publishing and clipping. Programme boundaries\n(air delay, openers) are detected automatically and can be corrected.\n" }, { "name": "live", "description": "Ingest secrets of a live channel (SRT passphrase)." }, { "name": "clips", "description": "Cut clips from a channel's recording by time range — playable immediately at segment precision, frame-accurate after finalising." }, { "name": "epg", "description": "The electronic programme guide. Import from XMLTV or JSON, edit programmes, and (in `review` mode) stage edits\nin a draft that a publisher publishes as a version; roll back, copy days, shift overruns, recurring templates.\nPublish the guide to partners (pull feeds, HTTPS/SFTP/S3 pushes, DVB EIT). The public XMLTV/JSON exports are\nunder `/epg/…` and need no key.\n" }, { "name": "subtitles", "description": "Automatic Hebrew subtitles (speech recognition) for catch-up and VOD, translations into other languages, a\nglossary, and a cue editor that saves new versions. Subtitles are added to the HLS playlists automatically.\n" }, { "name": "posters", "description": "Poster images of assets, series and programmes — automatic stills or your own upload." }, { "name": "images", "description": "AI image upscaling of small artwork (settings and per-image upscale/revert)." }, { "name": "packaging", "description": "Output packaging per tenant and channel (fMP4, MPEG-TS or both)." }, { "name": "lipsync", "description": "Lip-sync (audio/video offset) monitoring settings and results per channel." }, { "name": "input-monitor", "description": "Continuous monitoring of a channel's input legs (primary a, backup b): availability, bitrate, format, TS and HLS\ncontinuity, black / frozen / silent pictures and sound, loudness (EBU R128) and A/V drift — off by default.\n" }, { "name": "fast", "description": "FAST channels: linear channels assembled from your library and approved AI clips, without an encoder. Weekly\nschedules from rules (dayparts, rotation, repeat limits, fillers, break pattern), a playlist checker that blocks\npublishing on errors and alerts you, a \"best of\" channel programmed from approved clips, XMLTV/JSON guide\nentries, SSAI at the break markers and live break-ins — off by default.\n" }, { "name": "settings", "description": "Tenant settings: branding (display name, logos for light and dark backgrounds, brand colours checked for WCAG AA\ncontrast, favicon, e-mail sender name) and the tenant-wide defaults in one view, with how many channels and\nvideos choose differently. Branding is the starting point of new player configurations and new Sites themes.\n" }, { "name": "billing", "description": "Read-only monthly usage: storage, delivered traffic, transcoding and GPU minutes, live channel-days, Sites page\nviews and exported events, each with the source it is read from; also as CSV. Invoices are not available yet.\n" }, { "name": "players", "description": "Player configurations (presets) and where they apply — tenant default, section, channel or asset." }, { "name": "delivery", "description": "CDN operations — pre-warm and purge the edges, your own CDN distributions (hostnames, token auth, signing), their DNS/TLS status and the playback checker." }, { "name": "protection", "description": "Playback protection: playback policies (referrer and embed-domain lists, geo, ASN and datacenter blocking,\nplayback tokens) attached to the tenant, channels, assets or distributions; signed playback URLs for your backend\n(`POST /v1/playback/tokens`, scope `playback:sign`); signing-key rotation; geo blackouts; leak detection and\nsession revocation.\n" }, { "name": "insight", "description": "Audience and delivery statistics: realtime viewers, period overviews with comparison, timeseries, breakdowns,\ntop content, edge traffic and 95th percentile, returning viewers, programme ratings, ads, protection denials and\nsession search. Time ranges take `from`/`to` as RFC 3339 or epoch ms.\n" }, { "name": "events", "description": "A server-sent event stream (`text/event-stream`) of your tenant's events — the same events webhooks carry, plus realtime statistics." }, { "name": "webhooks", "description": "Outbound webhooks: register HTTPS endpoints for event types; deliveries are signed (see *Events* above) and\nretried for up to ~15 hours. Inspect deliveries and redeliver. Inbound hooks let your CMS call ViewStream with\na signed request and no API key.\n" }, { "name": "event-export", "description": "Stream statistics and platform events to your own systems — S3 (gzip NDJSON), Kafka, HTTPS (HMAC-signed\nbatches) or Google Analytics 4 — with a delivery log, a dead-letter queue and replay. A built-in test receiver\nlets you try it without an endpoint.\n" }, { "name": "sites", "description": "ViewStream Sites management: shows (series), people, sites, pages with drafts, versions and scheduling,\ntheme, menus, routes, redirects and custom domains. The rendered site reads the Sites Delivery API.\n" }, { "name": "storage", "description": "Storage usage of the tenant and its S3-compatible keys." }, { "name": "keys", "description": "API keys of the tenant (scope `keys:manage`). The secret is returned once, on creation." }, { "name": "team", "description": "Members of the tenant, their roles, and invitations." }, { "name": "invitations", "description": "Invite people to the tenant." }, { "name": "notifications", "description": "Notification rules (email, Telegram) and the in-app inbox." }, { "name": "monitoring", "description": "Monitors and alerts for your own channels, videos and sites: live stream checks (feed down / slate, no new\nsegments, encoder below real time, recorder gaps, live playlist errors at the edge, black video, lip-sync\ndrift), quality of experience (startup p95, rebuffering, playback errors, plays dropping during a programme)\nand delivery (subtitles failures, waiting translations). Each check has a threshold, a duration and a\nseverity; monitors have quiet hours and snooze. Alerts go to the Studio bell, to e-mail (double opt-in for\naddresses outside your team) and Telegram (your own chat, linked through the ViewStream bot), and to your\nwebhooks as `alert.firing` / `alert.resolved`.\n" }, { "name": "support", "description": "Contact ViewStream support (Interhost): open a request (question, bug, outage, billing, feature request),\nfollow the conversation, reply and close it. Scopes `support:read` / `support:write`; at most 10 new requests\nper tenant per hour.\n" }, { "name": "mcp", "description": "The remote MCP server at `https://api.viewstream.co.il/mcp`: AI assistants (Claude, ChatGPT, Cursor, …) use\nViewStream with an API key — search catch-up and the library, read EPG, subtitles and summaries, statistics,\nalerts and the manual; cut clips and open support requests when the key allows it. Model Context Protocol over\nStreamable HTTP; see the API guide, \"MCP server\".\n" }, { "name": "auth", "description": "Who the key belongs to." }, { "name": "tenants", "description": "The tenant the key belongs to." }, { "name": "health", "description": "Liveness of the API." }, { "name": "meta", "description": "This documentation and the machine-readable OpenAPI documents." }, { "name": "ai", "description": "AI newsroom — article drafts of programmes and the editorial review queue (every AI artefact is a draft until an editor publishes it)" } ], "paths": { "/docs": { "get": { "tags": [ "meta" ], "summary": "Interactive API documentation (Swagger UI); redirects to /docs/", "description": "Answers `301` with `Location: /docs/`. The page and its assets are served under `/docs/` (self-hosted Swagger UI\nfrom this origin only, strict Content-Security-Policy, `X-Frame-Options: DENY`, cached 5 minutes; the vendored\nfiles under `/docs/vendor/` are immutable for a year). No authentication. Try it out uses the key typed into\nAuthorize and calls this API from the browser; nothing is stored server-side. Unknown files under `/docs/` answer 404.", "operationId": "getDocs", "responses": { "301": { "description": "Redirect to /docs/", "headers": { "Location": { "description": "Always `/docs/`", "schema": { "type": "string" } } } } }, "security": [] } }, "/openapi.yaml": { "get": { "tags": [ "meta" ], "summary": "This API as an OpenAPI 3.1 document (YAML)", "description": "The public document of the ViewStream API, generated at build time from the source specification: internal,\noperator, edge-only and Studio-session-only routes are removed, the only security scheme is the API key and every\noperation names its required scope (`x-required-scope`). No authentication; `Access-Control-Allow-Origin: *` so\ncode generators and API tools can fetch it cross-origin; `Cache-Control: public, max-age=300`. The Sites Delivery\nAPI (`/s/v1`) has its own document at `/openapi/sites-delivery.yaml`.", "operationId": "getOpenAPIYAML", "responses": { "200": { "description": "The document (`application/yaml; charset=utf-8`)", "content": { "application/yaml": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream API", "version": "0.2.0" }, "paths": {} } } } } }, "security": [] } }, "/mcp": { "post": { "tags": [ "mcp" ], "summary": "Remote MCP server (Model Context Protocol, Streamable HTTP) for AI assistants — Claude, ChatGPT, Cursor", "description": "**Required scope:** none — any valid API key of the tenant.\n\nOne JSON-RPC 2.0 message per POST (MCP revision 2025-06-18; 2025-11-25 and 2025-03-26 are negotiated in\n`initialize`, and 2025-03-26 batches of at most 20 messages are accepted). A request gets one\n`application/json` response; notifications (`notifications/initialized`, …) get `202` with no body. Methods:\n`initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`,\n`resources/templates/list`, `prompts/list`, `prompts/get`. Stateless: no `Mcp-Session-Id` is issued.\n`MCP-Protocol-Version` is checked when sent (400 for an unsupported revision).\n\nAuthentication is a tenant API key (`Authorization: Bearer `, same rules and rate limit as `/v1`; a\nStudio session cookie is not accepted). `tools/list` shows only the tools the key's scopes allow; each tool\nnames its scope (read tools: `channels:read`, `assets:read`, `stats:read`; write tools: `clips:write`,\n`support:write`, `assets:write`). Tools call the `/v1` API in-process as the key, so tenant isolation,\nvalidation and audit are the API's own; every `tools/call` is also audited as `mcp.tool_call`. A failed\ntool answers a result with `isError: true` and the API's problem detail; protocol errors are JSON-RPC\nerrors. Tool results are capped at about 60 KB (lists are shortened and marked `_truncated`).\n\nResources: `viewstream://docs/{lang}/{topic}` (the Studio manual and the API guide, en | he),\n`viewstream://openapi` (every operation with its scope) and `viewstream://openapi/{operationId}`.\nBrowser requests whose `Origin` is not on the allow-list are refused (403, DNS-rebinding protection); MCP\nclients send no `Origin`. Guide: docs/guide/api/mcp.md.", "operationId": "postMCP", "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "description": "The negotiated revision (sent by clients after initialize)", "schema": { "type": "string", "enum": [ "2025-11-25", "2025-06-18", "2025-03-26" ] } }, { "name": "Accept", "in": "header", "description": "application/json, text/event-stream (the response is always application/json)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A JSON-RPC 2.0 request or notification (or, for 2025-03-26 clients, an array of them)", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string" }, "params": { "type": "object" } } }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_catchup", "arguments": { "q": "אליפות אירופה", "limit": 5 } } } } } }, "responses": { "200": { "description": "The JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": [ "string", "integer", "null" ] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } } } }, "example": { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\"q\":\"אליפות אירופה\",\"items\":[…]}" } ], "structuredContent": { "q": "אליפות אירופה", "items": [], "truncated": false, "channels_searched": 1 } } } } } }, "202": { "description": "Notification or response accepted (no body)" }, "400": { "description": "Unsupported MCP-Protocol-Version", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No, malformed, unknown or revoked API key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Browser Origin not on the allow-list, or a key without a tenant", "content": { "application/json": { "schema": { "type": "object" } } } }, "406": { "description": "Accept excludes application/json", "content": { "application/json": { "schema": { "type": "object" } } } }, "413": { "description": "Body over 1 MiB", "content": { "application/json": { "schema": { "type": "object" } } } }, "415": { "description": "Content-Type is not application/json", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "mcp" ], "summary": "Server-initiated SSE stream — not offered (405)", "description": "The MCP Streamable HTTP transport lets a client open an SSE stream with GET; this server sends no\nserver-initiated messages and answers `405 Method Not Allowed` (`Allow: POST`). Not authenticated.", "operationId": "getMCP", "responses": { "405": { "description": "Always", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [] } }, "/openapi.json": { "get": { "tags": [ "meta" ], "summary": "This API as an OpenAPI 3.1 document (JSON)", "description": "The same public document as `/openapi.yaml`, as JSON (`application/json; charset=utf-8`). No authentication;\n`Access-Control-Allow-Origin: *`; `Cache-Control: public, max-age=300`.", "operationId": "getOpenAPIJSON", "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream API", "version": "0.2.0" }, "paths": {} } } } } }, "security": [] } }, "/openapi/sites-delivery.yaml": { "get": { "tags": [ "meta" ], "summary": "The Sites Delivery API as an OpenAPI 3.1 document (YAML)", "description": "The public document of the Sites Delivery API (`/s/v1/…`, the cacheable read API behind ViewStream Sites),\ngenerated from the same source as `/openapi.yaml`. No authentication; `Access-Control-Allow-Origin: *`;\n`Cache-Control: public, max-age=300`.", "operationId": "getSitesDeliveryOpenAPIYAML", "responses": { "200": { "description": "The document (`application/yaml; charset=utf-8`)", "content": { "application/yaml": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream Sites Delivery API" }, "paths": {} } } } } }, "security": [] } }, "/openapi/sites-delivery.json": { "get": { "tags": [ "meta" ], "summary": "The Sites Delivery API as an OpenAPI 3.1 document (JSON)", "description": "The same document as `/openapi/sites-delivery.yaml`, as JSON. No authentication; `Access-Control-Allow-Origin: *`;\n`Cache-Control: public, max-age=300`.", "operationId": "getSitesDeliveryOpenAPIJSON", "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream Sites Delivery API" }, "paths": {} } } } } }, "security": [] } }, "/openapi.he.yaml": { "get": { "tags": [ "meta" ], "summary": "This API as an OpenAPI 3.1 document with Hebrew summaries (YAML)", "description": "The document at `/openapi.yaml` with Hebrew tag descriptions and operation summaries (from `api/i18n/he.yaml`, English\nwhere a text is not translated) and a Hebrew note before the introduction; `info.x-language` is `he`. Paths,\nparameters, schemas, responses and examples are the same as in `/openapi.yaml`. The docs page loads it when its\nlanguage switch is set to עברית. No authentication; `Access-Control-Allow-Origin: *`;\n`Cache-Control: public, max-age=300`.", "operationId": "getOpenAPIHebrewYAML", "responses": { "200": { "description": "The document (`application/yaml; charset=utf-8`)", "content": { "application/yaml": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream API", "x-language": "he" }, "paths": {} } } } } }, "security": [] } }, "/openapi.he.json": { "get": { "tags": [ "meta" ], "summary": "This API as an OpenAPI 3.1 document with Hebrew summaries (JSON)", "description": "The document at `/openapi.json` with Hebrew tag descriptions and operation summaries (from `api/i18n/he.yaml`, English\nwhere a text is not translated) and a Hebrew note before the introduction; `info.x-language` is `he`. Paths,\nparameters, schemas, responses and examples are the same as in `/openapi.json`. The docs page loads it when its\nlanguage switch is set to עברית. No authentication; `Access-Control-Allow-Origin: *`;\n`Cache-Control: public, max-age=300`.", "operationId": "getOpenAPIHebrewJSON", "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream API", "x-language": "he" }, "paths": {} } } } } }, "security": [] } }, "/openapi/sites-delivery.he.yaml": { "get": { "tags": [ "meta" ], "summary": "The Sites Delivery API as an OpenAPI 3.1 document with Hebrew summaries (YAML)", "description": "The document at `/openapi/sites-delivery.yaml` with Hebrew tag descriptions and operation summaries (from `api/i18n/he.yaml`, English\nwhere a text is not translated) and a Hebrew note before the introduction; `info.x-language` is `he`. Paths,\nparameters, schemas, responses and examples are the same as in `/openapi/sites-delivery.yaml`. The docs page loads it when its\nlanguage switch is set to עברית. No authentication; `Access-Control-Allow-Origin: *`;\n`Cache-Control: public, max-age=300`.", "operationId": "getSitesDeliveryOpenAPIHebrewYAML", "responses": { "200": { "description": "The document (`application/yaml; charset=utf-8`)", "content": { "application/yaml": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream Sites Delivery API", "x-language": "he" }, "paths": {} } } } } }, "security": [] } }, "/openapi/sites-delivery.he.json": { "get": { "tags": [ "meta" ], "summary": "The Sites Delivery API as an OpenAPI 3.1 document with Hebrew summaries (JSON)", "description": "The document at `/openapi/sites-delivery.json` with Hebrew tag descriptions and operation summaries (from `api/i18n/he.yaml`, English\nwhere a text is not translated) and a Hebrew note before the introduction; `info.x-language` is `he`. Paths,\nparameters, schemas, responses and examples are the same as in `/openapi/sites-delivery.json`. The docs page loads it when its\nlanguage switch is set to עברית. No authentication; `Access-Control-Allow-Origin: *`;\n`Cache-Control: public, max-age=300`.", "operationId": "getSitesDeliveryOpenAPIHebrewJSON", "responses": { "200": { "description": "The document", "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "ViewStream Sites Delivery API", "x-language": "he" }, "paths": {} } } } } }, "security": [] } }, "/healthz": { "get": { "tags": [ "health" ], "summary": "Liveness", "description": "Answers `200 {\"status\":\"ok\"}` whenever the API process serves requests. It checks no dependency (use it for\nliveness probes and uptime checks); `Cache-Control: no-store`. No authentication.", "operationId": "healthz", "responses": { "200": { "description": "Process is up", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } } }, "example": { "status": "ok" } } } } }, "security": [] } }, "/v1/me": { "get": { "tags": [ "auth" ], "summary": "The caller — user, tenants, current tenant and effective scopes", "description": "**Required scope:** none — any valid API key of the tenant.\n\nWho is calling. With an API key: `auth: api_key`, `user: null`, the key's tenant as both `tenants[0]` and\n`current_tenant` (role `api_key`) and the key's scopes. With a Studio session: `auth: session`, the user, every\ntenant of an active membership with the role there, the session's current tenant (null until one is chosen)\nand the scopes of that role. Any valid credential may call it (no scope needed). Use it to check which tenant\nand scopes a key carries before calling other routes.", "operationId": "me", "responses": { "200": { "description": "Caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "auth": "session", "user": { "id": "019286a2-4c33-7c4b-9a1b-3c5d7e9f1a2e", "email": "dana@example.co.il", "name": "Dana Levi", "locale": "he", "tz": "Asia/Jerusalem", "status": "active", "created_at": "2026-09-27T09:00:00Z", "last_login_at": "2026-10-06T07:45:12Z" }, "tenants": [ { "id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "slug": "now14poc", "name": "Channel 14 PoC", "mode": "platform", "cdn_hostname": "cdn.now14-poc.vustream.net", "role": "editor" } ], "current_tenant": { "id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "slug": "now14poc", "name": "Channel 14 PoC", "mode": "platform", "cdn_hostname": "cdn.now14-poc.vustream.net", "role": "editor" }, "scopes": [ "assets:read", "channels:read", "clips:read", "stats:read", "events:read", "sites:read", "assets:write", "clips:write", "uploads", "sites:write", "epg:write" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/tenants": { "get": { "tags": [ "tenants" ], "summary": "Tenants the caller belongs to (the key's tenant, or the session's memberships)", "description": "**Required scope:** none — any valid API key of the tenant.\n\nWith an API key: exactly one item, the key's tenant, with role `api_key`. With a Studio session: one item per\nactive membership with the role there (oldest membership first); Interhost operators get every tenant. No scope\nneeded; any valid credential may call it.", "operationId": "listTenants", "responses": { "200": { "description": "Tenants", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenantSummary" } } } }, "example": { "items": [ { "id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "slug": "now14poc", "name": "Channel 14 PoC", "mode": "platform", "cdn_hostname": "cdn.now14-poc.vustream.net", "role": "api_key" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/assets": { "get": { "tags": [ "assets" ], "summary": "List assets (cursor pagination, newest first)", "description": "**Required scope:** `assets:read`\n\nThe tenant's assets, newest first (`created_at`, then `id`), as summaries without renditions or jobs — call\n`GET /v1/assets/{id}` for the full object. Trashed assets (`deleted`) are hidden unless you ask for\n`status=deleted`. Filters combine: `status`, `collection` (+ `children`) and the text search `q`. Pass\n`next_cursor` back as `cursor` until it is null. Scope `assets:read`; not available to CDN-only tenants\n(403 `feature_disabled`).", "operationId": "listAssets", "parameters": [ { "name": "status", "in": "query", "description": "Only assets in this state. Without it, every state except `deleted` (the trash) is listed.", "schema": { "type": "string", "enum": [ "registered", "probing", "queued", "encoding", "packaging", "ready", "failed", "deleted" ] } }, { "name": "collection", "in": "query", "description": "Only assets in this library section of the tenant; an unknown or foreign section is a 422.", "schema": { "type": "string", "format": "uuid" } }, { "name": "children", "in": "query", "description": "With `collection`, also assets in its direct sub-sections (`true`; anything else = false)", "schema": { "type": "boolean", "default": false } }, { "name": "q", "in": "query", "description": "Search (Studio Library): only assets whose title, external id, id, description or content summary (summary text, presenters, topics) contains this text, case-insensitively; 2–100 characters after trimming. Each item then carries `match`. Combines with the other filters and the cursor. 503 `not_ready` when the store has no search support.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "cursor", "in": "query", "description": "`next_cursor` of the previous page (`|`); an unparsable cursor is ignored (first page)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "A page of assets; `next_cursor` is null on the last page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetPage" }, "example": { "items": [ { "id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "external_id": "cms-48211", "title": "Evening news", "status": "ready", "ladder": "news-720p", "duration_ms": 1785600, "published_at": "2026-09-30T18:22:00Z", "ready_at": "2026-09-30T18:21:40Z", "created_at": "2026-09-30T18:05:27Z", "updated_at": "2026-09-30T18:22:00Z", "deleted_at": null } ], "next_cursor": "2026-09-30T18:05:27.420478Z|0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Invalid query: `limit` outside 1–200, unknown `status`, unknown `collection`, or `q` too short/long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://viewstream.co.il/problems/validation_error", "title": "Validation failed", "status": 422, "detail": "invalid query", "request_id": "019286a2-3b22-7c4b-9a1b-3c5d7e9f1a2d", "errors": [ { "field": "limit", "detail": "must be an integer between 1 and 200" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "`q` was given but text search is not available (`not_ready`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-required-scope": "assets:read" }, "post": { "tags": [ "assets" ], "summary": "Register an asset (S3 key under the tenant's ingest prefix, or a URL) and start its probe job", "description": "**Required scope:** `assets:write`\n\nRegisters a source that is already in object storage (`source.kind: s3`, a key under `/in/` of the\ningest bucket) or that the worker fetches (`url`, http(s) on port 80/443/8443 without credentials; hosts that\nresolve to private, loopback or other non-public addresses are refused — SSRF guard). For browser/file uploads use `POST /v1/uploads` instead. The asset is created with a\n`probe` job and answered as `probing`; it then moves through `queued` → `encoding` → `packaging` → `ready` (or\n`failed`) — follow it with `GET /v1/assets/{id}`, the SSE stream or webhooks (`asset.status`, `asset.ready`).\n`publish: manual` keeps a ready asset unpublished until `PATCH {publish: true}`. Body max 64 KB. Scope\n`assets:write`; not for CDN-only tenants. Audited as `asset.create`; emits `asset.status`.", "operationId": "createAsset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreate" }, "example": { "external_id": "cms-48211", "title": "Evening news 27.9", "source": { "kind": "s3", "key": "now14poc/in/evening-2026-09-27.mov" }, "ladder": "news-1080p", "publish": "auto", "metadata": { "description": "Main evening edition", "ads": { "cues": [ 600, 1200 ] } } } } } }, "responses": { "201": { "description": "Asset registered (status `probing`) with its probe job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" }, "example": { "id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "customer_id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "external_id": "cms-48211", "title": "Evening news 27.9", "status": "probing", "source": { "kind": "s3", "bucket": "ingest", "key": "now14poc/in/evening-2026-09-27.mov" }, "master_key": null, "ladder": "news-1080p", "probe": null, "duration_ms": null, "error": null, "metadata": { "description": "Main evening edition", "ads": { "cues": [ 600, 1200 ] } }, "published_at": null, "ready_at": null, "created_at": "2026-09-27T19:02:11Z", "updated_at": "2026-09-27T19:02:11Z", "published": false, "renditions": [], "playback": null, "jobs": [ { "id": "0192c8a0-5000-7000-8000-000000000001", "type": "probe", "status": "queued", "attempts": 0, "created_at": "2026-09-27T19:02:11Z" } ] } } } }, "400": { "description": "Malformed JSON, an unknown field or a body over 64 KB (`validation_error`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "An asset with that external_id exists for this tenant", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed: `source.kind`/`source.key`/`source.url` (incl. the SSRF guard), `external_id`, `title`, `metadata` (incl. `metadata.ads`), `publish` or an unknown `ladder`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://viewstream.co.il/problems/validation_error", "title": "Validation failed", "status": 422, "detail": "invalid asset", "request_id": "019286a2-3b22-7c4b-9a1b-3c5d7e9f1a2d", "errors": [ { "field": "source.key", "detail": "must be under ingest/now14poc/in/ and contain no traversal" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:write" } }, "/v1/assets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "assets" ], "summary": "Asset with renditions, playback URLs and job summary", "description": "**Required scope:** `assets:read`\n\nThe full asset: the stored row, `published`, its renditions, the last 50 jobs (newest first; job errors are\nredacted) and — only while `ready` — the playback URLs on the tenant's CDN hostname (a chosen smart poster\nreplaces the generated one). Trashed (`deleted`) assets and other tenants' assets answer 404; see\n`GET /v1/trash`. Scope `assets:read`; not for CDN-only tenants.", "operationId": "getAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" }, "example": { "id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "customer_id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "external_id": "cms-48211", "title": "Evening news", "status": "ready", "source": { "kind": "upload", "bucket": "ingest", "key": "tv10poc/in/0192c8a0-6000-7000-8000-000000000002/evening.mp4" }, "master_key": "tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/evening.mp4", "ladder": "news-540p", "probe": { "width": 960, "height": 540, "fps": 25, "duration_ms": 178560, "video_codec": "h264", "audio_codec": "aac", "interlaced": false }, "duration_ms": 178560, "error": null, "metadata": { "description": "Main evening edition" }, "published_at": "2026-09-30T18:22:00Z", "ready_at": "2026-09-30T18:21:40Z", "created_at": "2026-09-30T18:05:27Z", "updated_at": "2026-09-30T18:22:00Z", "published": true, "playback": { "hls": "https://cdn.tv10-poc.vustream.net/vod/tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/master.m3u8", "poster": "https://cdn.tv10-poc.vustream.net/vod/tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/poster.jpg", "sprite": "https://cdn.tv10-poc.vustream.net/vod/tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/sprite.jpg", "thumbs_vtt": "https://cdn.tv10-poc.vustream.net/vod/tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/thumbs.vtt", "download": "https://cdn.tv10-poc.vustream.net/vod/tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/download.mp4" }, "renditions": [ { "id": "0192c8a0-5100-7000-8000-000000000011", "asset_id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "kind": "video", "label": "540p", "width": 960, "height": 540, "bitrate_kbps": 1053, "codec": "avc1", "s3_key": "tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/540p.m3u8", "size_bytes": 23519955, "created_at": "2026-09-30T18:21:40Z" }, { "id": "0192c8a0-5100-7000-8000-000000000012", "asset_id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "kind": "audio", "label": "aac-128", "bitrate_kbps": 132, "codec": "mp4a.40.2", "s3_key": "tv10poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/aac-128.m3u8", "size_bytes": 2969509, "created_at": "2026-09-30T18:21:40Z" } ], "jobs": [ { "id": "0192c8a0-5000-7000-8000-000000000001", "type": "probe", "status": "succeeded", "attempts": 1, "created_at": "2026-09-30T18:05:27Z", "finished_at": "2026-09-30T18:05:31Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No such asset in this tenant, or it is in the trash", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:read" }, "patch": { "tags": [ "assets" ], "summary": "Update title, external_id, metadata; publish/unpublish (needs assets:publish)", "description": "**Required scope:** `assets:write`\n\nPartial update: only the fields present change. `metadata` replaces the whole object (no merge).\n`external_id: \"\"` clears it. `publish` needs scope `assets:publish` (403 otherwise); `true` needs a `ready`\nasset and keeps the first `published_at`, `false` clears it. `policy_id` attaches a playback policy to the\nasset (or `null` = inherit the tenant's) and needs scope `delivery:write`; a policy change can queue\nre-encodes of the tenant's assets when the encryption mode changes. Body max 64 KB. Scope `assets:write`; not\nfor CDN-only tenants; trashed assets are 404. Audited as `asset.update`; the first publish emits\n`asset.published`.", "operationId": "patchAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 500 }, "external_id": { "type": "string", "pattern": "^$|^[A-Za-z0-9._:/-]{1,200}$", "description": "Empty string clears it; unique per tenant (409)" }, "metadata": { "type": "object", "description": "Replaces the whole metadata object; max 16 KB; `metadata.ads` is validated as on create; keys starting with _ are reserved" }, "publish": { "type": "boolean", "description": "true sets published_at (asset must be ready), false clears it; needs scope assets:publish" }, "policy_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Attach a playback policy of the tenant to this asset; null detaches (inherit). Needs scope delivery:write" } } }, "example": { "title": "Evening news 27.9 (full)", "metadata": { "description": "Main evening edition", "ads": { "cues": [ 600 ] } }, "publish": true } } } }, "responses": { "200": { "description": "The updated asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" }, "example": { "id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "customer_id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "external_id": "cms-48211", "title": "Evening news 27.9 (full)", "status": "ready", "ladder": "news-1080p", "duration_ms": 1785600, "metadata": { "description": "Main evening edition", "ads": { "cues": [ 600 ] } }, "published_at": "2026-09-30T18:22:00Z", "ready_at": "2026-09-30T18:21:40Z", "created_at": "2026-09-30T18:05:27Z", "updated_at": "2026-09-30T18:22:00Z", "published": true, "playback": { "hls": "https://cdn.now14-poc.vustream.net/vod/now14poc/0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f/master.m3u8" }, "renditions": [], "jobs": [] } } } }, "400": { "description": "Malformed JSON, an unknown field or a body over 64 KB (`validation_error`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Missing scope (`assets:write`; `assets:publish` for `publish`; `delivery:write` for `policy_id`), CDN-only tenant, or suspended tenant", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such asset (or it is in the trash), or `policy_id` names no policy of this tenant", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Publish requested on an asset that is not ready, or external_id in use", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:write" }, "delete": { "tags": [ "assets" ], "summary": "Delete an asset (marks `deleted` = moves it to the trash, purges vod/; masters kept unless ?masters=true)", "description": "**Required scope:** `assets:write`\n\nDelete an asset (marks `deleted` = moves it to the trash, purges vod/; masters kept unless ?masters=true). With ?permanent=true a trashed asset is deleted for good (scope assets:purge)\n\nWithout `permanent`: moves a live asset to the trash — status `deleted`, unpublished, and a `purge` job (bulk\npriority) that removes its renditions under vod/ and the edge copies; the master stays unless `masters=true`\n(without a master the asset cannot be restored). Answers 204. Audited as `asset.delete`; emits `asset.status`.\nRestore with `POST /v1/assets/{id}/restore` until the trash retention purges it.\n\nWith `permanent=true` (scope `assets:purge`, checked in the handler): the asset must already be in the trash\n(409 otherwise). Queues a permanent purge job — masters, ingest source, renditions, edge copies and the row —\nand answers 202 with it; a second call returns the job already pending (idempotent). Audited as\n`asset.purge_requested`. Scope `assets:write`; not for CDN-only tenants.", "operationId": "deleteAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset id", "schema": { "type": "string", "format": "uuid" } }, { "name": "masters", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Move to the trash: `true` also deletes the master (the asset then cannot be restored). Ignored with `permanent`" }, { "name": "permanent", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "`true`: delete a trashed asset permanently: masters, ingest source, renditions, edge copies and the row (scope assets:purge; 202 + job)" } ], "responses": { "202": { "description": "`permanent=true`: permanent delete queued (or the pending one returned)", "content": { "application/json": { "schema": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/Job" } } }, "example": { "job": { "id": "0192c8a0-5000-7000-8000-00000000000a", "customer_id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "type": "purge", "priority": 3, "status": "queued", "attempts": 0, "max_attempts": 3, "asset_id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "created_at": "2026-10-06T09:12:00Z" } } } } }, "204": { "description": "Moved to the trash; a purge job for its renditions was created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Missing scope (`assets:write`; `assets:purge` with `permanent=true`), CDN-only tenant, or suspended tenant", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such asset in this tenant (without `permanent`, a trashed asset is also 404)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already deleted (a concurrent delete), or with `permanent=true` the asset is not in the trash", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:write" } }, "/v1/assets/{id}/restore": { "post": { "tags": [ "assets" ], "summary": "Restore a trashed asset", "description": "**Required scope:** `assets:write`\n\nRestore a trashed asset — rebuilt from its master with its ladder; it waits in `registered` and comes back `ready`, unpublished\n\nTakes an asset out of the trash by re-encoding its master with its own ladder (a `reencode` job at fast\npriority 1, encrypted as its playback policy asks). The asset moves to `registered` at once and becomes\n`ready` — unpublished — when the job finishes; publish it again with `PATCH {publish: true}`. Needs the master\nin storage (`restorable` in `GET /v1/trash`) and no pending permanent delete. Async: 202 with the job. Scope\n`assets:write`; not for CDN-only tenants. Audited as `asset.restore`; emits `asset.status`.", "operationId": "restoreAsset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the trashed asset", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Restore (reencode) job created; the asset is `registered`", "content": { "application/json": { "schema": { "type": "object", "required": [ "job", "status" ], "properties": { "job": { "$ref": "#/components/schemas/Job" }, "status": { "type": "string", "enum": [ "registered" ] } } }, "example": { "job": { "id": "0192c8a0-5000-7000-8000-00000000000b", "customer_id": "019286a2-1f3e-7c4b-9a1b-3c5d7e9f1a2b", "type": "reencode", "priority": 1, "status": "queued", "attempts": 0, "max_attempts": 3, "asset_id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "created_at": "2026-10-06T09:15:00Z" }, "status": "registered" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not in the trash, master gone, ladder profile gone, a permanent delete is pending, encryption keys unavailable, or it left the trash meanwhile", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:write" } }, "/v1/trash": { "get": { "tags": [ "assets" ], "summary": "The tenant's trash — deleted assets with the bytes they still hold, whether they can be restored and when…", "description": "**Required scope:** `assets:read`\n\nThe tenant's trash — deleted assets with the bytes they still hold, whether they can be restored and when they are purged automatically\n\nTrashed assets newest first (at most 1000 are walked; `truncated` says more exist), each with the bytes it still\nholds in storage (renditions left under vod/, the master, the ingest source), `restorable` (the master exists\nand no permanent delete is pending) and `purge_at` = `deleted_at` + `retention_days`. Also lists the channels\nin the trash, which Empty trash does not touch. Sizes are read live from object storage,\nso this call can be slow with a large trash. Scope `assets:read`; not for CDN-only tenants.", "operationId": "getTrash", "responses": { "200": { "description": "Trash summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trash" }, "example": { "count": 1, "bytes": 182544311, "retention_days": 30, "truncated": false, "items": [ { "id": "0192c8a0-4f1e-7a2b-9c3d-1a2b3c4d5e6f", "title": "Evening news 27.9", "deleted_at": "2026-10-01T08:00:00Z", "purge_at": "2026-10-31T08:00:00Z", "bytes": 182544311, "restorable": true, "purge_pending": false } ], "channels": [ { "id": "019a0000-0000-7000-8000-0000000000c2", "slug": "test-feed", "title": "Test feed", "deleted_at": "2026-10-02T10:00:00Z", "purge_at": "2026-11-01T10:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:read" } }, "/v1/trash/empty": { "post": { "tags": [ "assets" ], "summary": "Empty the trash — a permanent purge job per trashed asset (idempotent; returns counts and bytes)", "description": "**Required scope:** `assets:purge`\n\nQueues a permanent purge job (masters, ingest source, renditions, edge copies and the row) for every trashed\nasset (up to 1000 per call; `truncated` = call again). Assets that already have a pending permanent delete are\ncounted in `already_pending` and not queued twice, so repeating the call is safe. `bytes` is what the newly\nqueued assets hold. Channels in the trash are not touched (they are purged at their `purge_at`). No body.\nScope `assets:purge`; not for CDN-only tenants. Audited as `trash.empty`.", "operationId": "emptyTrash", "responses": { "202": { "description": "Purges queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "queued", "already_pending", "bytes", "truncated" ], "properties": { "queued": { "type": "integer", "description": "Permanent purge jobs created by this call" }, "already_pending": { "type": "integer", "description": "Trashed assets whose permanent purge was already queued" }, "bytes": { "type": "integer", "format": "int64", "description": "Storage the newly queued assets hold" }, "truncated": { "type": "boolean", "description": "The trash holds more than 1000 assets; call again" } } }, "example": { "queued": 3, "already_pending": 1, "bytes": 1204318822, "truncated": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:purge" } }, "/v1/trash/settings": { "patch": { "tags": [ "assets" ], "summary": "Set how many days a trashed asset is kept before it is purged automatically (1–365, default 30)", "description": "**Required scope:** `assets:purge`\n\nStores `retention_days` in the tenant settings (`trash_retention_days`); the automatic purge and `purge_at`\nin `GET /v1/trash` use it from now on. Body max 1 KB. Scope `assets:purge`; not for CDN-only tenants. Audited\nas `trash.settings`.", "operationId": "patchTrashSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "retention_days" ], "additionalProperties": false, "properties": { "retention_days": { "type": "integer", "minimum": 1, "maximum": 365 } } }, "example": { "retention_days": 14 } } } }, "responses": { "200": { "description": "Saved; the retention now in effect", "content": { "application/json": { "schema": { "type": "object", "required": [ "retention_days" ], "properties": { "retention_days": { "type": "integer" } } }, "example": { "retention_days": 14 } } } }, "400": { "description": "Malformed JSON or an unknown field (`validation_error`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`retention_days` missing or outside 1–365", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "assets:purge" } }, "/v1/library/imports": { "get": { "tags": [ "library-imports" ], "summary": "Library imports from a sitemap, newest first (50)", "description": "**Required scope:** `assets:read`\n\nThe tenant's 50 newest library imports (no pagination), each with its discovery statistics and item counts.\nNot available to CDN-only tenants (403 `feature_disabled`). Scope `assets:read`.", "operationId": "listLibraryImports", "responses": { "200": { "description": "The newest imports, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/LibraryImport" } } } }, "example": { "items": [ { "id": "0199b9e2-3c41-7f05-9a6e-2d8c4b1f7e30", "sitemap_url": "https://www.example.co.il/video-sitemap.xml", "status": "discovered", "options": { "extract_pages": false, "max_items": 1000 }, "import_options": null, "resync": false, "next_sync_at": null, "last_sync_at": null, "error": null, "created_by": "key:k7Qm2xPa", "created_at": "2026-10-05T09:14:02Z", "updated_at": "2026-10-05T09:16:40Z", "finished_at": "2026-10-05T09:16:40Z", "stats": { "sitemaps": 3, "pages": 0, "requests": 4, "robots_blocked": 0, "truncated": false, "errors": [] }, "counts": { "total": 412, "mp4": 377, "hls": 21, "unsupported": 14, "duplicates": 6, "discovered": 412, "queued": 0, "fetching": 0, "processing": 0, "imported": 0, "failed": 0, "skipped": 0, "cancelled": 0 } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Library import is not available on this deployment (`feature_disabled`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-required-scope": "assets:read" }, "post": { "tags": [ "library-imports" ], "summary": "Discover the videos of a sitemap (index, plain, Google video sitemap, gzip; optionally the video of each page)", "description": "**Required scope:** `assets:write`\n\nDiscover the videos of a sitemap (index, plain, Google video sitemap, gzip; optionally the video of each page). Runs in the background (2 requests/s per host, robots.txt respected); poll the import, then read its items. The URL must be public http(s): private, loopback, link-local and metadata addresses are refused, also after redirects.\n\nCreates an import in status `discovering` and answers 202 at once; the crawler (orchestrator leader) reads the\nsitemap, sitemap index (up to 3 levels, 200 files), `.xml.gz` or robots.txt `Sitemap:` lines in the background,\nthen the import becomes `discovered` (or `failed`). Poll `GET /v1/library/imports/{id}` and preview the items\nwith `GET …/items`; nothing is imported until `POST …/start`. At most 3 imports of a tenant may be discovering at\nonce (429, `Retry-After: 60`). The URL is checked against the SSRF policy before anything is fetched (422 with\nthe reason). Unknown body fields are rejected (400). Audited as `library_import.create`. Not available to CDN-only tenants (403 `feature_disabled`). Scope\n`assets:write`.", "operationId": "createLibraryImport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sitemap_url" ], "additionalProperties": false, "properties": { "sitemap_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Absolute http(s) URL of a sitemap, sitemap index,.xml.gz or robots.txt; trimmed" }, "extract_pages": { "type": "boolean", "default": false, "description": "Open each page URL that is not itself a video and look for og:video, JSON-LD VideoObject,