plycdn Content Search — HTTP API guide

Audience: developers integrating without our SDKs, or extending an SDK integration with calls the packaged components do not make.

You do not need this guide to use plycdn Content Search. The Angular and ASP.NET Core packages cover the whole path — upload, indexing, search, playback — and the Integration guide is the shorter road. Use this one when you are building your own client, integrating from a language we do not ship a package for, or automating configuration.

Everything here is called from your backend. The API key authenticates your server to plycdn and must never reach a browser.

1Before starting

Item Where it comes from
API key Created in the dashboard under Developers → API keys; see Getting and rotating API keys
Organization UUIDs Your account's id and each sub-organization's, shown in the dashboard under Developers → API keys and Account & security → Sub-organizations, or read with GET /api/sub-organizations
Your storage Yours — files stay in your own account

Base address: https://api.plycdn.com/api/content/v1

2Authentication

Every request carries the key, and usually the organization it is for:

Authorization: ApiKey YOUR_KEY
X-Organization-Id: 00000000-0000-0000-0000-000000000000

A whole-account key identifies your account, and X-Organization-Id selects which of your organizations the request applies to — your own, or one of its sub-organizations. A key made for one organization identifies that organization, and the header, if sent, must name it. Content is isolated per organization: a search in one never returns content from another, and an asset registered under one is invisible to the rest. A key made for one organization needs no X-Organization-Id header (see Reach below).

A request without a key in the Authorization header returns 401 api_key_required; a key that is not valid (unknown, revoked or expired) returns 401 invalid_api_key. A missing or malformed X-Organization-Id returns 400 organization_required. An organization your key does not cover returns 403 organization_forbidden. A key is not a password for a user; authorize your own users yourself before calling on their behalf.

Reach. When you create a key in the dashboard you choose how far it reaches:

  • Only {organization} (the default): the key is bound to the organization selected in the dashboard's organization switcher — your main organization or one sub-organization. It needs no X-Organization-Id header, and cannot be used for any other organization. If you do send the header, it must name that organization. A key bound to one organization never manages sub-organizations or reads the account audit, even an admin key, and a key bound to your main organization sees only the main organization's own data, usage and analytics, never its sub-organizations'. Nor does it change what sub-organizations inherit from the main organization (its settings, video settings and watch page brand): see Configure your sources first.
  • The whole account: reaches your main organization and every one of its active sub-organizations, and X-Organization-Id chooses. This is offered only when the main organization is selected. Every key made before the choice existed reaches the whole account and works as before.

With a whole-account key the header is required on /api/content/v1 (400 organization_required without it). With a key bound to one organization, naming another organization of your account is refused with 403 organization_out_of_key_reach, and an organization that is not yours with 403 organization_forbidden. The list under Developers → API keys shows each key's Reach and can be filtered by it. A sub-organization that has been deactivated is no longer covered: content calls that name it are refused with 403 organization_forbidden until it is reactivated (GET /api/sub-organizations still lists it).

The Authorization: ApiKey header is the only place a key is read. A key anywhere else is never read, checked or accepted:

  • In the query string (?apiKey=, in any letter case or escaping): the request is answered 401 api_key_required on every route, before anything else is looked at, even with a valid header beside it.
  • In a JSON request body (a top-level apiKey field, including the older form that sent it with organizationId): the request is answered 401 api_key_required once its body is read, unless an earlier check answers first (a missing or invalid header key, organization_forbidden, admin_key_required and the like). Remove the field and send the header.

An address ends up in proxy and browser logs, and a body may be logged or passed on, which is why a key is accepted only in the header. (?apiKey= was deprecated in 1.7.0 and has since been removed, including from the dashboard's content routes.)

An AI assistant sends the same header to the plycdn MCP server (https://mcp.plycdn.com/mcp) and sees only what the key can see. Give it a key of its own: Connect your AI assistant.

Signing in an assistant

An assistant can also connect by signing in instead of using a key: the person approves it on plycdn.com/app/connect, choosing the organization and Standard or Admin access, and the assistant then does what a key of that level can do for that one organization (it cannot manage keys, people or the organization profile, manage sub-organizations or read the account audit, or create query keys). Most assistants find everything themselves from the server address. For one that needs the addresses, they are all on https://mcp.plycdn.com:

Address What it is
/.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp Says that sign-in is needed and where to do it
/.well-known/oauth-authorization-server Lists the addresses below and what is supported
/oauth/register An assistant introduces itself and receives its client identifier
/oauth/authorize Sends the person to plycdn to approve (authorization code with PKCE, method S256)
/oauth/token Exchanges the approval for an access token (valid 1 hour) and a refresh token; each refresh issues a new refresh token
/oauth/revoke Ends a connection from the assistant's side

The scopes are mcp:standard and mcp:admin. Send the access token as Authorization: Bearer <token> to https://mcp.plycdn.com/mcp. Without a credential the docs tools still work; an account tool answers 401 sign_in_required with a WWW-Authenticate header that tells the assistant how to sign in. A connection ends when the person disconnects it (Developers → AI assistants), the assistant signs out, the person leaves the organization or deletes their account, they choose Sign out everywhere or reset their password, or it goes 90 days unused; the next request then answers 401 invalid_token or connection_ended. Connect your AI assistant

3What your key reaches

One call tells you what a key acts as and what it may reach: the organization, every organization it can name, the key by its prefix and scope, the regions you can create buckets in with their S3 and Azure endpoints, and the products your plan includes. Use it to check a key works before you build on it. Any key, standard or admin.

GET /api/content/v1/account
Authorization: ApiKey YOUR_KEY
X-Organization-Id: 00000000-0000-0000-0000-000000000000
{
  "organization": { "id": "00000000-0000-0000-0000-000000000000", "name": "Acme", "kind": "account" },
  "reach": "account",
  "organizations": [
    { "id": "00000000-0000-0000-0000-000000000000", "name": "Acme" },
    { "id": "11111111-1111-1111-1111-111111111111", "name": "Acme India" }
  ],
  "key": { "prefix": "plyk_a1B2", "scope": "standard" },
  "regions": [
    { "code": "mumbai", "label": "Mumbai, India", "s3Endpoint": "https://s3.mumbai.plycdn.net",
      "azureEndpoint": "https://{account}.blob.mumbai.plycdn.net" }
  ],
  "products": ["content_search", "storage", "video"]
}
  • organization is the organization this request acted as: kind is account for your main organization and sub_organization for one of its sub-organizations.
  • reach is account for a whole-account key, which may name the main organization and every active sub-organization, all listed in organizations; and organization for a key made for one organization, which lists only that one.
  • key names the key by its first characters and its scope (standard or admin, the key's Access under Developers → API keys). The key itself is never returned.
  • regions are the regions a bucket can be created in. In azureEndpoint, {account} is your storage account name.
  • products is drawn from content_search (on every plan), storage, video, live and observability. For the features and limits of each, read What your plan includes.

A key made for one organization needs no X-Organization-Id header; a whole-account key names any organization it reaches (400 organization_required without one). Naming an organization the key cannot reach is refused as on every other call (403 organization_out_of_key_reach or 403 organization_forbidden). In the dashboard, Developers → API keys shows each key's prefix, access and reach; the regions are the ones you choose from when you create a bucket (Storage → Storage buckets), and the plan is under Billing & usage → Usage. Step by step: Check what a key reaches.

4Getting and rotating API keys

Keys are created in the dashboard under Developers → API keys. A key is shown once, when it is created: copy it into your server's secret store then. It cannot be read again, by you or by us.

Scope What it can do Where it belongs
standard Everything under /api/content/v1: registering, searching, settings, usage, and storage files, uploads, signed links, cache purges, delivery analytics, videos, storage usage, the storage audit and the storage request log. The default. The service that handles your users' requests
admin All of that; managing sub-organizations and reading the account audit from code (next section); and the storage operations that create, change or remove a bucket, a video library, a custom domain, a webhook endpoint or the storage account, or rotate a signing key or webhook secret, everything about live inputs except reading one and asking for its playback links (below), and every observability call (querying, exporting, tailing, volumes, slow queries, the archive status, settings, ingest keys and query keys) Only the automation that sets accounts and buckets up. Created only in the dashboard

Storage operations that need an admin key. A standard key is refused with admin_key_required (403) on these, and only these; everything else in storage, including GET /bucket-names, works with either key:

POST   /api/content/v1/buckets                            # create a bucket
PATCH  /api/content/v1/buckets/{id}                       # change its settings
DELETE /api/content/v1/buckets/{id}                       # delete it
DELETE /api/content/v1/buckets/{id}/search                # remove its files from search
POST   /api/content/v1/buckets/{id}/restore               # restore it
POST   /api/content/v1/buckets/{id}/retry                 # retry a failed creation
POST   /api/content/v1/buckets/{id}/signing-key/rotate    # replace its signing key
POST   /api/content/v1/domains                            # add a custom domain to a bucket
DELETE /api/content/v1/domains/{id}                       # remove a custom domain
PUT    /api/content/v1/domains/{id}/routes                # save which buckets a custom domain serves, by path
POST   /api/content/v1/domains/{id}/routes/restore        # make an earlier route table current again
PUT    /api/content/v1/buckets/{id}/migration             # set up moving a bucket's files from another cloud
PATCH  /api/content/v1/buckets/{id}/migration             # change that move's key, old-link or copy settings (not its source or state)
POST   /api/content/v1/buckets/{id}/migration/check       # try the source (and start serving from it)
POST   /api/content/v1/buckets/{id}/migration/pause       # pause the background copy (files are still served)
POST   /api/content/v1/buckets/{id}/migration/resume      # resume it
POST   /api/content/v1/buckets/{id}/migration/switch-off-old-links  # refuse links signed by the old cloud
POST   /api/content/v1/buckets/{id}/migration/close       # close the move and forget the source credential
PUT    /api/content/v1/buckets/{id}/replication           # keep a disaster-recovery copy of a bucket in another location
DELETE /api/content/v1/buckets/{id}/replication           # turn that copy off
POST   /api/content/v1/libraries                          # create a video library
PATCH  /api/content/v1/libraries/{id}                     # change its settings
DELETE /api/content/v1/libraries/{id}                     # delete it
POST   /api/content/v1/videos/{id}/reencode               # encode a ready video again
POST   /api/content/v1/webhooks                           # create a webhook endpoint
PATCH  /api/content/v1/webhooks/{id}                      # change it
DELETE /api/content/v1/webhooks/{id}                      # delete it
POST   /api/content/v1/webhooks/{id}/secret/rotate        # replace its signing secret
POST   /api/content/v1/libraries/{id}/live-inputs         # create a live input
GET    /api/content/v1/libraries/{id}/live-inputs         # list a library's live inputs
PATCH  /api/content/v1/live-inputs/{id}                   # change one
DELETE /api/content/v1/live-inputs/{id}                   # delete one
POST   /api/content/v1/live-inputs/{id}/stream-key        # replace its stream key
GET    /api/content/v1/live-inputs/{id}/stream-key        # show its stream key (audited)
POST   /api/content/v1/live-inputs/{id}/publish-tokens    # a token for a browser to go live
POST   /api/content/v1/live-inputs/{id}/disable           # stop it taking streams
POST   /api/content/v1/live-inputs/{id}/enable            # allow it again
POST   /api/content/v1/live-inputs/{id}/end               # end its running stream
GET    /api/content/v1/live-inputs/{id}/streams           # list its streams
GET    /api/content/v1/streams/{id}                       # read one stream
GET    /api/content/v1/streams/{id}/viewers               # who watched it, minute by minute
GET    /api/content/v1/streams/{id}/health                # its health, minute by minute
POST   /api/content/v1/live-inputs/{id}/destinations      # restream it to another platform
GET    /api/content/v1/live-inputs/{id}/destinations      # list a live input's restream destinations
PATCH  /api/content/v1/destinations/{id}                  # change a destination
DELETE /api/content/v1/destinations/{id}                  # delete one
POST   /api/content/v1/destinations/{id}/test             # check that its platform answers
POST   /api/content/v1/live-inputs/{id}/breaks            # mark an ad break on its running stream
GET    /api/content/v1/live-inputs/{id}/breaks            # its ad breaks, scheduled and recent
DELETE /api/content/v1/live-inputs/{id}/breaks/{id}       # cancel a scheduled ad break
GET    /api/content/v1/live/protection-setups             # the protection setups your live inputs may use
GET    /api/content/v1/live-inputs/{id}/share-links       # a live input's share links
POST   /api/content/v1/live-inputs/{id}/share-links       # create a share link
PATCH  /api/content/v1/live-inputs/{id}/share-links/{id}  # change, or turn off, a share link
DELETE /api/content/v1/live-inputs/{id}/share-links/{id}  # delete a share link
GET    /api/content/v1/watch-brand                        # the watch page's look
PUT    /api/content/v1/watch-brand                        # change it
PUT    /api/content/v1/watch-brand/logo                   # upload its logo
DELETE /api/content/v1/watch-brand/logo                   # remove its logo
GET    /api/content/v1/watch-domains                      # your own domains for watch pages
POST   /api/content/v1/watch-domains                      # add one
GET    /api/content/v1/watch-domains/{id}                 # one, with its DNS records and status
POST   /api/content/v1/watch-domains/{id}/check           # check its DNS records now
DELETE /api/content/v1/watch-domains/{id}                 # remove one
POST   /api/content/v1/storage-credentials                # storage credentials: made in the dashboard only
POST   /api/content/v1/storage-credentials/{id}/rotate    #   (a standard key is refused with admin_key_required,
DELETE /api/content/v1/storage-credentials/{id}           #   an admin key with dashboard_session_required)
POST   /api/content/v1/storage-account                    # create the storage account
PATCH  /api/content/v1/storage-account                    # change its home region
POST   /api/content/v1/observability/query                # run a read-only SQL statement (or KQL query) over your logs, metrics and traces
POST   /api/content/v1/observability/export               # download a statement's rows as JSON lines or Parquet
POST   /api/content/v1/observability/validate             # check a statement without running it for rows
GET    /api/content/v1/observability/reference            # the KQL operators, functions and aggregations, the tables, the errors and the limits
GET    /api/content/v1/observability/logs/tail            # follow your logs as they arrive
GET    /api/content/v1/observability/traces/{id}          # every span of one trace
GET    /api/content/v1/observability/volumes              # data received, kept and read, per day
GET    /api/content/v1/observability/slow-queries         # your own slowest recent queries, newest first
GET    /api/content/v1/observability/archives             # what the nightly archive did, per day and signal, with its manifest
GET    /api/content/v1/observability/settings             # region, retention, archive bucket and where to send data
PATCH  /api/content/v1/observability/settings             # turn it on, change the retention or the archive
GET    /api/content/v1/observability/ingest-keys          # list the keys data is sent with
POST   /api/content/v1/observability/ingest-keys          # create one (shown once)
DELETE /api/content/v1/observability/ingest-keys/{id}     # revoke one
GET    /api/content/v1/integrations/logthread             # how the organization is connected to Logthread
PUT    /api/content/v1/integrations/logthread             # connect it with an ingest key, or change the signals sent
DELETE /api/content/v1/integrations/logthread             # disconnect it and forget the key

Connect to Logthread is a one-click alternative to pasting an ingest key: in the dashboard (Developers → Integrations) you choose a Logthread workspace on logthread.com and come back connected, with every signal on. Its two routes, GET /api/content/v1/integrations/logthread/connect (start: where to send the browser) and POST /api/content/v1/integrations/logthread/connect/complete (finish, with what Logthread sent back), are the dashboard's own: every API key is refused there with dashboard_session_required. With an API key, connect with an ingest key (PUT above). Disconnecting a workspace connected this way also ends the connection on the Logthread side.

In the dashboard every member of your organization can make these changes.

A person's passkeys (signing in to the dashboard with a fingerprint, face or security key) are the dashboard's own, like keys: no API key or SDK can add, use or remove them, and every API key is refused there with dashboard_session_required. How a person uses them: Sign in with a passkey. Passkey changes and sign-in times appear in the account audit, which admin keys can read.

A dashboard sign-in lasts at most 12 hours, however much the person works in it, and ends sooner when they choose Sign out everywhere (Account & security → Sign-in & security) or reset their password; the dashboard then answers session_ended and asks them to sign in again. API keys are not affected.

Keys are credentials, so they are managed by people, in the dashboard only: creating, rotating, deactivating and reactivating keys has no API. The key routes refuse every API key, admin keys included, with dashboard_session_required.

At most two keys are active at once for each organization, and two for the whole account, so a key can be replaced without downtime:

  1. Choose Rotate on the key in use in the dashboard. A new key of the same scope is created and shown once. The old key keeps working.
  2. Deploy the new key to your backend.
  3. When the old key's Last used stops moving, deactivate it in the dashboard.

A third active key for the same reach is refused with api_key_limit_reached: deactivate one first. An expired key stops working at its expiry and no longer counts towards the two. More than 10 keys created or rotated by your account in an hour is refused with rate_limited.

5Managing sub-organizations from code

These routes sit beside the content API, at https://api.plycdn.com/api, and need an admin key. X-Organization-Id must be your account's own id: sub-organizations belong to the account, not to one of its sub-organizations. A standard key is refused with admin_key_required; any other organization id with organization_forbidden. The key must reach the whole account: a key bound to one organization, even an admin key, is refused with organization_out_of_key_reach.

GET    /api/sub-organizations                 # every sub-organization, active or not
POST   /api/sub-organizations                 # { "name", "contact_email", "description",
                                              #   "metadata" }
GET    /api/sub-organizations/{id}
PUT    /api/sub-organizations/{id}            # only the fields you send change;
                                              #   "is_active": true reactivates
DELETE /api/sub-organizations/{id}            # deactivate; nothing is deleted

GET    /api/account-audit?limit=50&before=41  # who changed which key or sub-organization

More than 60 sub-organizations created by your account in an hour is refused with rate_limited.

Sub-organizations as separate tenants. If you serve customers of your own, give each one a sub-organization. Each has its own library: files, collections, permissions and search results are never shared between them, and a call made with a sub-organization's id in X-Organization-Id can only find that sub-organization's content. Each can hold its own storage hosts and limits, and the usage call reports each sub-organization's own quantities (Account and sub-organization scope). Plan quotas apply to the account as a whole, and your account can cap each sub-organization itself (Limits for each sub-organization). The dashboard's Sub-organizations page lists them.

From your server. The sub-organization and account audit calls are also in the plycdn storage and video packages (from 1.16.0) as well as the Content Search packages, with the same names: .NET, Node.js and Python.

GET /api/sub-organizations answers a bare JSON array. The other routes answer one object with id, parent_organization_id, name, contact_email, description, is_active, metadata, created_at and updated_at. POST answers 201; DELETE answers {"success": true, "message": "…"}, and deleting one that is already deactivated changes nothing. A PUT that sends none of the editable fields is 422 validation_error. An unknown id, or one that belongs to another account, is 404 sub_organization_not_found; an id that is not a UUID is 422 validation_error, fields [["path","id"]].

A sub-organization's metadata is your own labels for it: an object of at most 50 keys, each 1 to 128 characters, whose values are strings of up to 512 characters, numbers or booleans, and at most 16 KiB as JSON. Send null to remove it. It is returned as you wrote it. The other fields: name is 1 to 255 characters, contact_email an e-mail address or null, and description up to 2,000 characters or null. Anything else is refused with 422 validation_error, whose fields names the first field at fault as a location path, for example [["body","metadata"]]. The older field (that field's name) is still sent so integrations written against earlier releases keep working: read fields.

Every change to a key (in the dashboard) or a sub-organization (in the dashboard or from code) is recorded in the account audit, naming the person (by e-mail) or the key (by its name):

{ "items": [ { "id": "…", "at": "2026-09-26T10:00:00Z",
               "actor": { "kind": "api_key", "id": "…", "label": "provisioner", "prefix": "…" },
               "action": "sub_organization.updated",
               "resourceKind": "sub_organization", "resourceId": "…",
               "detail": { "fields": ["metadata"] } } ],
  "next": "41" }

Pass next as before for the next page. limit is 1 to 100 and 50 when omitted (a larger value is lowered to 100, not refused); before must be the next of the previous page, digits only, otherwise 422 validation_error, fields [["query","before"]]. An actor of kind api_key also carries the key's prefix, so a key can be told apart from another with the same name. detail names what changed — the fields an edit touched, a new sub-organization's name, or a key's name, prefix, scope and expiry — and never holds a key or what a field was changed to. Actions: api_key.created, api_key.rotated, api_key.deactivated, api_key.reactivated, sub_organization.created, sub_organization.updated, sub_organization.deactivated, sub_organization.reactivated, sub_organization.quotas_updated (its detail.fields names the limits changed, searches, answers or indexGigabytes, never their values), and dashboard.search_as.

dashboard.search_as is a person in the dashboard searching as someone else — sending principals, to check what a restricted reader would see. Its resourceKind is organization, resourceId the organization searched, and detail { "route": "search", "principals": 2 }: the route (search or answer) and how many principals, never who they were and never the query. If the row cannot be written, the search is not run and the dashboard answers 503 audit_unavailable.

People, invitations and your organization's profile are managed in the dashboard only: every API key is refused there with dashboard_session_required.

Limits for each sub-organization

Your account can cap, for each sub-organization, the searches and written answers it makes a month and the content it keeps searchable (GB). These are your own limits, set from code or on the dashboard's Sub-organizations page; your plan's quotas still apply to the account as a whole.

GET /api/content/v1/usage/quotas/organizations/{subOrganizationId}
PUT /api/content/v1/usage/quotas/organizations/{subOrganizationId}
    { "searches": 10000, "answers": 2000, "indexGigabytes": 5 }
{ "organizationId": "…", "month": "2026-10",
  "metrics": [ { "metric": "searches", "label": "Searches", "unit": "searches",
                 "quota": 10000, "used": 4120, "remaining": 5880, "percent": 41.2 },
               { "metric": "answers", "label": "Written answers", "unit": "answers",
                 "quota": null, "used": 12, "remaining": null, "percent": null },
               { "metric": "index_gigabyte_months", "label": "Content kept searchable", "unit": "GB",
                 "quota": 5, "used": 3.2, "remaining": 1.8, "percent": 64 } ] }
  • Send X-Organization-Id with your account's own id and an admin key (a standard key is refused with admin_key_required). A call made as a sub-organization is refused with organization_forbidden, so a sub-organization can never change or remove its own limits. An id that is not one of your active sub-organizations (or your account's own id) is 404 sub_organization_not_found.
  • PUT changes only the fields you send: a number sets that limit, null removes it (no limit), and a field you leave out keeps its limit. searches and answers are whole numbers from 0 to 1,000,000,000 and indexGigabytes a number from 0 to 1,000,000; 0 allows none at all. Anything else is 422 validation_error. It answers as GET does.
  • Searches made on the dashboard for that sub-organization count, as in the account's quota. Over a limit, new work of that kind for that sub-organization is refused with 429 quota_exceeded, not retryable, whose detail names the limit, for example Searches: 10000 of 10000 used this month by this sub-organization; resets 2026-11-01. Your account and its other sub-organizations are not affected, and work already under way finishes.
  • Content kept searchable is checked when new content is added (registering, importing, syncing, indexing again) against the figure we count once a day, so it can be up to a day old. What is already indexed is never removed or hidden. A file that was accepted and then reaches processing after a limit has been crossed finishes with quota_exceeded instead of being indexed, and is not charged; add it again once the limit is raised or you have removed other content.
  • Pay-as-you-go lets your account go past its plan's quotas; it never lifts these limits, which are your own.
  • A change takes effect within 30 seconds and is recorded in the account audit as sub_organization.quotas_updated. Limits are not billed, and every plan has them.
  • To tell which limit stopped work, read GET /usage/quotas: read as your account, your plan's quotas are in metrics; called as a sub-organization, the limits your account set for it are in organizationQuotas on Your quotas, and the refusal's detail says "by this sub-organization" for those.

6What can be indexed

Kind Formats Indexed as
video .mp4 .mov .mkv .webm .avi Transcribed audio, with timestamps
audio .mp3 .wav .flac .m4a .ogg .aac Transcribed, with timestamps
document .pdf Page by page; a long page is split into passages of about 200 words, and a passage never crosses a page
document .docx One block per paragraph or table cell, with the nearest heading
document .pptx One block per slide, with its title, its tables and its speaker notes
document .xlsx One block per row, with sheet name and row number
document .csv One block per record
document .txt .md One block per line
document .html .htm .xhtml One block per paragraph or heading
document .zip A SCORM package — its pages, slides, lessons and the documents inside it

Document layout. Documents are read as they are laid out. A PDF, a PowerPoint deck or a Word document is read the way a person reads it, in every language, with nothing to switch on: in reading order across columns, with page headers and footers left out, and with scanned pages read too. Passages then follow the document's own structure, by the kind of document it is, which plycdn recognises on its own (there is nothing to set):

Kind of document A passage is
Policy, contract or other numbered clauses One clause with its sub-clauses; definitions stay together
Paper or report One section, split at paragraph boundaries when long; references apart, ranked after other passages
Questions and answers One question with its answer
Slides One slide
Anything else One section from heading to heading, split at paragraph boundaries when long

Tables are kept as tables in every kind, in PDFs, PowerPoint decks and Word documents: each row is also its own passage, written as Header: value; Header: value, so a search for a value finds its row, and a result can point at the row and at the cell that matched (see Table rows and cells below). A table that could not be read reliably is indexed as its text instead, never as a wrong grid. Each passage carries the headings it sits under (headingPath). A Word file has no pages, so its passages carry block and heading rather than a page. A document whose layout cannot be read in time is indexed page by page, about 200 words a passage, so it never fails for that reason; a passage never crosses a page. Documents indexed before this was available keep their passages until they are indexed again: re-index a file, or ask us to read a library or a list of documents again.

Scanned pages. Pages that are pictures of text are read as well: they are searchable like any other page, and a result cites the page. A page is listed in the asset's warnings as ocr_required:page:N (N is the page number) only if it could not be read either, and a PDF fails with ocr_required only if no page could be read. Images on their own are not an accepted format.

Plain text, Markdown and CSV files must be UTF-8; one in another encoding fails with text_encoding_must_be_utf8 (save it again as UTF-8). Legacy binary Office formats (.doc, .xls, .ppt) are not supported. Spreadsheet formulas index their computed value, not the formula text.

Read GET /capabilities rather than hard-coding this table — it is what your plycdn service actually accepts, and it grows without an SDK release.

SCORM packages (1.2 and 2004, any edition) are read through their imsmanifest.xml, so a result names the page or module the author titled rather than sco_04.html. Every common shape is read:

  • one page per item, in the author's order;
  • one launch page that navigates between lesson pages - the pages it links to and the files the manifest lists are read in the order the launch page names them, and its own Previous / Next / Exit controls are not indexed;
  • a slide player whose course is in a data file (JSON, or JSON assigned in a script) - each slide's text, narration script, alternative explanations and quiz questions, located by slide;
  • an Articulate Rise export - lesson by lesson, located by the lesson's title;
  • PDF and Word documents shipped inside the package, located by resource and page;
  • a package zipped inside its folder, or using xml:base paths.

When the manifest leads nowhere readable, every page in the package is read in path order. Media inside a package is not transcribed: registering a zip should never silently incur an hour of transcription. A package with no readable text fails with document_empty; a .zip that is not a SCORM package is refused with not_a_scorm_package.

Slides and on-screen text. Where on-screen reading is enabled for your account, video is also read visually: text on a slide becomes searchable alongside what was said, with the timestamp it appeared. Those results carry "location": { "source": "slide", … } so you can label them — half of what a lecture conveys is on the slide and never spoken aloud, and a reader deserves to know which they are looking at.

7Configure your sources first

Nothing indexes until your organization declares where its files live. This is also available in the dashboard under Content search → Indexing settings.

PUT /api/content/v1/settings
Authorization: ApiKey YOUR_KEY
X-Organization-Id: <uuid>
Content-Type: application/json

{
  "sourceHosts": ["yourcompany.blob.core.windows.net"],
  "callbackUrl": "https://YOUR_BACKEND/your/callback/path",
  "callbackSecret": "<32+ random characters>",
  "dailyBudgetUsd": 50,
  "dailyAudioHours": 10
}

PUT replaces the whole row. Send the complete set every time: any field you omit reverts to inherited, so a request meaning to change one host will quietly clear your callback and limits too. Read the current values first and send them back with your edit, or change only what you mean to with PATCH:

PATCH /api/content/v1/settings
Authorization: ApiKey YOUR_KEY
X-Organization-Id: <uuid>
Content-Type: application/json

{ "sourceHosts": ["yourcompany.blob.core.windows.net", "archive.yourcompany.com"],
  "callbackUrl": null }

A field you send is set, a field sent as null is cleared and inherited again, and a field you leave out is unchanged. "callbackSecret": null removes the stored secret. The response is the same document as GET /settings.

dailyBudgetUsd is deprecated since 1.7.0: it is accepted here and ignored — never stored, never enforced — and GET /settings always returns it as 0. Send it or not, it makes no difference. What you can start is controlled by your plan's quotas; see What you have used and /usage/quotas. dailyAudioHours is unaffected and still caps how many hours of audio/video an organization can start indexing in a day (below).

Limits: callbackSecret is 32 to 512 characters, dailyAudioHours 0 to 100,000 and searchLogDays 0 to 3,650; at most 200 sourceHosts, each a bare hostname (a leading *. is allowed). requireAcl needs the permissions feature in your plan (not_included_in_plan otherwise).

callbackSecret is the one exception on PUT — omit it and the stored secret is kept, because it cannot be read back. "sourceHosts": [] means inherit, not allow nothing; use DELETE /api/content/v1/settings to return an organization to its parent's settings.

Keys for one organization. A key for the main organization only can read these settings but not change them, because sub-organizations inherit them. Change them in the dashboard or with a key that reaches the whole account. PUT, PATCH and DELETE /settings with such a key, including videoDefaults, answer 403 organization_out_of_key_reach. A key made for a sub-organization changes that sub-organization's own settings as usual.

Hosts are checked for shape, not reachability. A typo is accepted here and surfaces later as source_host_not_allowed on registration, or a failed fetch — so read the response back and confirm it says what you intended.

GET /api/content/v1/settings returns the effective values: sourceHosts, callbackUrl, callbackSecretSet (whether a secret is stored; the secret itself is never returned), dailyBudgetUsd (always 0), dailyAudioHours, requireAcl, extractContentFromVideoFrames, searchLogDays (90 where none is set), allowedHostCeiling, configured (true once the organization has settings of its own) and updatedAt. An origins map, keyed by setting in snake case (source_hosts, callback_url, …), shows where each value came from: the organization itself (its UUID), owner (your account) or deployment (the plycdn default).

Video settings

videoDefaults sets how videos are encoded for this organization's libraries, unless a library has settings of its own. Its fields are ladder (any of 240, 360, 480, 720, 1080, 1440, 2160, each once), keepOriginal, download and thumbnails, each optional; null means not set here. A sub-organization uses its parent's value unless it sets its own, higher or lower: a parent's setting is a default, not a limit. Where it applies, a library with its own processing wins, then the library's organization, then its parent, then plycdn's defaults, all worked out when a video is encoded. Changing them affects videos encoded afterwards; see Encoding a video again.

PATCH /api/content/v1/settings
X-Organization-Id: <sub-organization uuid>
{ "videoDefaults": { "ladder": [360, 720, 1080, 2160], "download": true } }

On PUT an omitted videoDefaults leaves every video setting unset. On PATCH, videoDefaults changes only the fields it names, a field sent as null is unset again, and "videoDefaults": null unsets all four, so the organization uses its parent's. An invalid ladder is 422 validation_error (fields [["body","videoDefaults","ladder",0]]). GET /settings answers, besides the fields above:

{ "videoDefaults": { "ladder": [360, 720, 1080, 2160], "keepOriginal": true, "download": true, "thumbnails": true },
  "videoDefaultsOrigins": { "ladder": "organization", "keepOriginal": "parent", "download": "organization", "thumbnails": "default" },
  "videoDefaultsOwn": { "ladder": [360, 720, 1080, 2160], "keepOriginal": null, "download": true, "thumbnails": null },
  "videoPlatformDefaults": { "ladder": [240, 360, 480, 720, 1080], "keepOriginal": true, "download": false, "thumbnails": true } }

videoDefaults is what applies, videoDefaultsOrigins says where each value comes from (organization for the organization you asked about, parent, or default), videoDefaultsOwn is what this organization set itself, and videoPlatformDefaults is plycdn's own.

The callback is described under Renewing access below. It is required if you register assets with a callbackKey, and optional otherwise.

8Registering content

You upload the file to your own storage, then tell us where it is.

POST /api/content/v1/assets
Authorization: ApiKey YOUR_KEY
X-Organization-Id: <uuid>
Idempotency-Key: <your own unique value>
Content-Type: application/json

{
  "externalId": "lecture-2026-09-02",
  "filename": "Cardiology week 3.mp4",
  "kind": "video",
  "sourceUrl": "https://yourcompany.blob.core.windows.net/content/lecture.mp4",
  "sourceVersion": "\"0x8DF1151249B1D1B\"",
  "sourceAccess": { "url": "https://...mp4?<sas>" },
  "language": "multi",
  "audioTrack": 0
}
{ "assetId": "…", "jobId": "…", "revision": 1 }

Returns 202 — the work is queued, not done.

sourceUrl must be unsigned. It identifies the file; credentials travel separately in sourceAccess or come from your callback. A signed URL here is refused with source_url_must_be_unsigned.

sourceVersion must be the storage ETag, quotes included, or a sha256: digest of the content. We verify it before processing: if the file changed after registration you get source_version_changed rather than an index of something you did not register. Inventing a value like "v1" fails, because it will not match what your storage reports.

externalId is yours — your own identifier for the file. It must be unique per version within the organization; registering the same externalId and sourceVersion twice returns 409 source_version_already_registered.

Idempotency-Key makes a retry safe. Repeating a request with the same key returns the original response instead of creating a second asset. A key is remembered for 30 days.

Sending the same file again. What comes back depends on what you repeat:

  • The same request with the same Idempotency-Key returns the original response (the same assetId, jobId and revision). Nothing new is created.
  • The same externalId and sourceVersion under a different key is refused with 409 source_version_already_registered: that version is already registered.
  • The same externalId with a new sourceVersion creates a new revision of the same asset. The previous revision stays searchable until the new one is ready, so there is no gap in results.

sourceAccess supplies read access at registration. Omit it if you use a callback. Its unsigned form must equal sourceUrl, or the request is refused with source_access_mismatch.

language defaults to multi, which detects per segment and handles mixed speech. Set a specific language only when you know every recording is in it.

Sizes. externalId and sourceVersion are 1 to 512 characters, filename 1 to 255, sourceUrl at most 4,096, language at most 16, audioTrack 0 to 15. You can also send metadata, collections (at most 100) and principals (at most 5,000) here. A collections entry that does not exist is refused with 400 collection_not_found and nothing is registered. A callbackKey needs a callbackUrl in your settings: without one, 400 callback_not_configured.

contentSha256 is optional: 64 hex characters (either case; it is stored in lower case), a sha256 of the file's bytes. Send it for a large recording we read in ranges rather than downloading whole, so identical content can be recognised without a full fetch. See Duplicate content in the Integration guide — without it, that kind of file is indexed and charged normally every time, because there is nothing to compare.

Registering many at once

POST /api/content/v1/imports
{ "assets": [ { …as above… }, … ] }

Up to 100 per request, answered 202. Each item succeeds or fails independently:

{ "importId": "…", "results": [
  { "externalId": "a", "assetId": "…", "jobId": "…", "revision": 1 },
  { "externalId": "b", "code": "source_host_not_allowed" } ] }

Poll GET /imports/{importId} for the batch:

{ "importId": "…", "items": [
  { "jobId": "…", "assetId": "…", "state": "embedding", "progress": 75, "errorCode": null } ] }

9Following progress

Indexing is asynchronous. A video is transcribed and then prepared for search; a document has its text extracted and is then prepared for search. Poll rather than assume.

GET /api/content/v1/jobs/{jobId}
{ "jobId": "…", "assetId": "…", "revision": 1, "state": "transcribing",
  "stage": "transcribing", "progress": 45, "errorCode": null, "retryAt": null }
state Meaning
queued Waiting to start, or to start its next step
extracting Reading the file and taking its text out
transcribing Speech-to-text in progress
embedding Preparing the text for search
retry_scheduled A temporary failure; retryAt says when it will be attempted again
awaiting_source_access We could not read the file; supply fresh access to resume
ready Indexed and searchable
failed Stopped, and will not retry on its own
cancelled Cancelled before finishing
deleting Removing the index of a file you deleted
cleanup Clearing what a cancelled or replaced run left behind

stage is the step the job is on (extracting, transcribing, embedding, deleting or cleanup): state shows the same word while that step runs and queued while the job waits between steps. Unknown or another organization's job ids answer 404 job_not_found.

GET /assets/{assetId}/jobs lists every run for one asset, including earlier failed attempts. GET /activity returns a page of assets each with its most recent job — one call rather than one per asset, which is what you want for a dashboard.

Poll at a sensible interval; a minute is plenty. progress is a percentage within the current stage, not the whole pipeline.

10Searching

POST /api/content/v1/search
{ "query": "what does the patient take before bed", "kind": "video", "limit": 20, "offset": 0 }
{ "items": [ {
    "assetId": "…", "filename": "Cardiology week 3.mp4", "kind": "video",
    "snippet": "There is nothing like a good movie before bed…",
    "highlights": [ { "start": 36, "end": 46 } ],
    "revision": 1, "score": 0.032,
    "relevance": 0.83, "confidence": "high", "matchType": "both",
    "speaker": "instructor", "language": "en",
    "metadata": { "course": "CS101", "term": "autumn" },
    "location": { "startSeconds": 80.69, "endSeconds": 88.51,
                  "playFromSeconds": 77.69, "timingPrecision": "segment" },
    "sourceReference": { "externalId": "lecture-2026-09-02",
                         "sourceUrl": "https://…", "sourceVersion": "\"0x8DF…\"" } } ],
  "withheldAsWeak": 0, "hasMore": false, "terms": ["patient", "bed"],
  "searchId": "8f14e45f-ceea-467a-9f4b-4c2d1a9e77b3" }

Search is by meaning. A question finds the passage that answers it even when they share no words, and it spans every kind at once unless you narrow it.

query is 1 to 2,000 characters, limit 1 to 100 (20 when omitted) and offset 0 to 200. Results can be paged through the first 200 places: hasMore is false once a page reaches the 200th, and an offset above 200 is refused with 422 validation_error, fields [["body","offset"]]. Narrow the search with filter rather than paging deeper. Every result, and every citation in an answer, carries the file's own metadata object ({} when it has none), so you can label results without a second call. Every result, every moments entry and every citation in an answer carries passageId, which names that passage of that revision of the file. Treat it as an opaque string and pass it back as around to read what surrounds the result (Passages around a result, below). It stops working once the file is indexed again (412 revision_conflict): search again for the new one.

A time limit. Send timeoutMs (100 to 30,000) and the search answers within that many milliseconds of arriving. When time runs short, the final re-ranking step (How search ranks) is left out rather than the search failing: the response then carries "partial": true, "skipped": ["rerank"], ordered by the first two steps. A search that cannot find its candidates in time at all is 504 content_service_timeout, as without a limit. Without timeoutMs nothing changes. To continue a search page by page, send the response's nextCursor back as cursor (see Narrowing step by step below); offset keeps working as it always has. When both are sent, the cursor wins and the offset is ignored.

speaker and language describe the passage itself. speaker is filled in where we could tell the speakers in the recording apart, language where the transcription identified one; both are null on documents and wherever we do not know. language is the language of the passage, not of your question — an English question can return a Hindi passage, and labelling it is often worth doing.

source is present only on a file from one of your buckets or video libraries: { "kind": "bucket", "bucketId": "…", "objectKey": "lectures/week 1.pdf" } or { "kind": "video_library", "bucketId": "…", "videoId": "…" } (bucketId is the library's id). It is the same field on GET /assets/{assetId}, GET /assets, GET /activity items and /answer citations, and absent for anything else.

One result per file

A file that answers a query in several places - five moments in a lecture, three pages of a handbook - comes back as five or three results by default. Ask for one result per file instead:

POST /api/content/v1/search
{ "query": "internal complaints committee", "group": "file", "limit": 10 }
{ "items": [ {
    "assetId": "…", "filename": "POSH induction.mp4", "kind": "video",
    "snippet": "…the Internal Complaints Committee must be set up…",
    "highlights": [ { "start": 5, "end": 34 } ],
    "relevance": 0.86, "confidence": "high", "matchType": "both",
    "location": { "startSeconds": 128.4, "endSeconds": 141.0, "playFromSeconds": 131.2 },
    "momentCount": 3,
    "moments": [
      { "snippet": "…", "highlights": [ … ], "location": { "playFromSeconds": 42.0, … },
        "relevance": 0.61, "confidence": "moderate", "matchType": "keyword", "speaker": null, "language": "en" },
      { "snippet": "…the Internal Complaints Committee must be set up…", "location": { "playFromSeconds": 131.2, … }, … },
      { "snippet": "…", "location": { "playFromSeconds": 612.5, … }, … } ],
    "sourceReference": { … }, … } ],
  "withheldAsWeak": 0, "hasMore": true, "terms": ["internal", "complaints", "committee"], "searchId": "…" }
  • Each item is the file's best passage, with every field a result has always had, so code that reads results keeps working.
  • moments lists every matching passage in the file - up to twenty - in the order they occur: by time in a recording, by page, slide or line in a document. Offer each as a jump-to link: seek to its location.playFromSeconds, or open its location.page. momentCount is how many matched in total.
  • limit, offset and hasMore then count files, not passages, so a second page never repeats a file from the first.
  • group does not change what is found, how it is ranked or what it costs: one search either way. /answer ignores it, because an answer cites passages.

Leave group out for one result per passage, as before.

Marking the words that matched

Every result carries highlights: where the words searched for appear in its snippet, as start/end offsets (end exclusive) in UTF-16 code units - the way JavaScript and .NET index strings, so snippet.slice(start, end) and snippet[start..end] are exact. Other forms of a word count ("complaints" for "complaint"), as do your configured synonyms; words so common in your library that they distinguish nothing ("the", "for") are not marked, and adjacent marked words merge into one span so a phrase reads as a phrase. Render the snippet as text around the marks - never as HTML.

highlights is empty when a passage matched by meaning alone (matchType semantic): it answers the question without using its words. Say so rather than showing an unmarked snippet as though nothing matched - "matched by meaning" is the honest label.

terms on the response lists the words that were matched, for marking them inside a whole document when a result is opened; highlights covers only the snippet.

Two separate things narrow a search, and it is worth being clear which is which.

filter is a preference — it says which files you are interested in. Every field is optional and the ones you set combine with AND.

POST /api/content/v1/search
{ "query": "reciprocal rank fusion",
  "filter": {
    "collections": ["CS101"],
    "metadata": { "term": ["autumn", "spring"], "level": "undergraduate" },
    "createdAfter": "2026-01-01T00:00:00Z",
    "speaker": "instructor",
    "language": "hi"
  } }
Field
collections Only files in these collections, by the external id you gave each collection.
metadata Only files whose metadata matches. A single value must match exactly; an array matches any one of its values. At most 50 keys, each value a string, number or boolean or a list of at most 100 of them, and at most 64 KiB as JSON in all; beyond that the search is refused with 422 validation_error, fields: [["body","filter","metadata"]].
externalIds / assetIds Only these specific files. At most 100 externalIds; at most 1,000 assetIds - a selection, each document counted once (422 selection_too_large beyond); collections is capped at 100.
createdAfter / createdBefore When the file was registered with us.
speaker Only passages spoken by this speaker. Passages with no known speaker never match.
language Only passages in this language.

principals is a constraint — it says who is asking. See below; it is not part of filter, because a filter is something you may drop to widen a search and this is something you must not.

Narrowing step by step, and searching selected documents

A person who searched for "tax" and then for "audit" within those results is asking for documents that match both. Send the earlier searches as within, in order, and the new words as query:

POST /api/content/v1/search
{ "query": "checklist", "group": "file",
  "within": [ { "query": "tax" }, { "query": "audit", "filter": { "language": "en" } } ],
  "filter": { "assetIds": ["<assetId>", "…"] } }
{ "items": [ … ], "hasMore": true, "withheldAsWeak": 0, "terms": ["checklist"], "searchId": "…",
  "scope": { "documents": 41, "capped": [ { "step": 0, "query": "tax" } ], "empty": [], "unavailable": ["<assetId>"] },
  "nextCursor": "gAAAAABn…" }
  • Steps. Up to 5 (422 too_many_steps beyond). Each step is an ordinary search - the same meaning-and-wording match, your filter, your principals - resolved to the documents it matched, at most its 2,000 most relevant. The documents every step matched are the scope, and query is ranked only among them. A step's own filter narrows that step only; the request's filter and principals apply to every step and to query. A step whose words are blank is 400 empty_query.
  • A selection. filter.assetIds holds up to 1,000 documents. With steps, the search covers the selected documents that also passed every step; without steps, only the selected documents.
  • scope appears on every search that has steps or a selection: documents is how many documents it ran over; capped lists steps that matched more than 2,000 documents and were narrowed to their most relevant 2,000; empty lists steps that matched nothing. When you send a selection, unavailable lists the selected documents that can no longer be searched - deleted, gone from their source, or not visible to these principals. A step that matches nothing is not an error: the response has scope.documents: 0 and no items, and the useful thing to tell the reader is which step to remove.
  • Pages. nextCursor is present while more results exist. Send it as cursor, with the same query, steps, filter and principals, for the next page. A cursor is valid for 15 minutes: after that the search answers 410 cursor_expired - start again from the first page with the same scope. A cursor sent with a different query, steps, filter, principals or organization, or altered, is 422 cursor_mismatch. Results reach the same depth as with offset (the first 200 places).
  • Repeating a step is quick. Going back to an earlier step, or searching new words within the same steps, reuses steps resolved in the last five minutes. A file added, deleted or changed since is never hidden or shown wrongly: the scope is checked against your library as it is now.
  • Billing. A search with steps or a selection is one search, however many steps it has.
  • /answer takes within and a selection too, so an answer can be written from the documents in scope; it ignores cursor.

How search ranks

Every search works in three steps.

  1. Meaning and wording, together. The question is matched against passages by meaning, and separately by the words it contains. Wording matching understands word endings in 28 languages, Hindi and Tamil among them, and matches exact words in the rest. A passage that shares no words with the question can still be found by meaning, and an exact phrase, name or code is found by wording.
  2. One list. The two sets of matches are merged into a single ranking in which a passage found both ways rises. matchType on each result tells you which way it was found.
  3. A re-ranking step. The strongest candidates are read again with the question and the passage side by side, and re-ordered by how well each answers it. This step produces relevance and confidence. If the step is ever unavailable, the search still returns results, ranked by the first two steps.

Two settings change this for one request, in ranking:

{ "query": "pre-existing disease waiting period", "ranking": { "keywordWeight": 0.7, "rerank": "off" } }
  • keywordWeight, 0 to 1 (0.5 when omitted, the usual balance): how much wording counts against meaning in step 2. 1 matches by wording only, which suits codes, names and exact phrases; 0 by meaning only. Either end is also a little faster, because the other kind of matching is not run.
  • rerank: "auto" (the default) or "off", which leaves out step 3. The search is then faster, and relevance and confidence come from the first two steps: coarser, and not comparable with those of a re-ranked search. Compare relevance only between searches with the same rerank.

A value outside these is 422 validation_error. keywordWeight: 1 needs words to match on: a query made only of very common words then finds nothing (an empty page, still counted as a search), so keep some meaning in the mix for such queries.

Passages that fall below the relevance floor are not returned. They are counted in withheldAsWeak instead, so an empty answer can be told apart from an empty library.

How well a passage matched

Three fields describe the match, so you can present a strong result differently from a possible one.

Field
relevance 0 to 1. Comparable between queries — this is the one to show or threshold on.
confidence high, moderate or low. Anything weaker than low is not returned.
matchType keyword when the passage contains the words you searched for, semantic when it matched by meaning without sharing them, both when it did both.

matchType is worth surfacing. It is what explains to a reader why a passage that shares no words with their question is nevertheless the right answer — particularly across languages, where an English question can be answered by a Hindi passage.

score is the older ranking value. It orders results within one response and is not comparable between queries; prefer relevance for anything a person sees or a threshold acts on. It remains in the response so existing integrations keep working.

withheldAsWeak counts passages found but judged too weak to offer. An empty items with a figure here means the library was searched and had nothing good enough, which is a different thing from a library with nothing in it — and worth saying differently in your interface.

location describes where the passage sits, and its fields differ by kind. Treat it as open: read the fields you need and ignore the rest.

Kind Fields
Video, audio startSeconds, endSeconds, playFromSeconds, timingPrecision
PDF page, charStart, charEnd; read with its layout, also type, headingPath, pageEnd, bbox
PowerPoint slide (from one), title; read with its layout, also type, headingPath
A table row (PDF, PowerPoint or Word table) type: "table_row", tableId, row, cells, matchedCellId, with the page fields
Word block, heading, and row/column inside a table; a table row is also a table_row result as above (without a page)
Spreadsheet sheet, row
Delimited text (CSV) row
Plain text, Markdown lineStart, lineEnd, charStart, charEnd
HTML element, heading
SCORM package resource, title, heading; slide (from one) for slide-player courses, element for HTML pages, page for a PDF inside the package

Text read from a video's frames rather than its speech also carries source: "slide".

Table rows and cells

type says what a passage is: text, table (a whole table, its header first), table_row, slide, note (a slide's speaker notes, with the same slide and title), faq (a question with its answer) or references. Treat it as open. bbox is the passage's area on page as [left, top, right, bottom], each a fraction of the page measured from its top left, so it fits any size you draw the page at. pageEnd is present when a passage runs onto later pages. charStart and charEnd are offsets into the document's text; a table row has none, because its text is composed from its cells.

A table_row result carries its row (row, counting from one, header rows included), its table (tableId, the same for every row of it) and its cells; matchedCellId names the cell your query landed on:

"location": {
  "type": "table_row", "page": 7, "tableId": "t3", "row": 4,
  "headingPath": ["C. EXCLUSIONS", "Specific waiting periods"],
  "bbox": [0.08, 0.41, 0.92, 0.44],
  "cells": [
    { "id": "t3/r4c0", "row": 4, "column": 0, "rowSpan": 1, "colSpan": 1, "header": false,
      "columnHeader": "Disease", "text": "Cataract", "bbox": [0.08, 0.41, 0.36, 0.44] },
    { "id": "t3/r4c1", "row": 4, "column": 1, "rowSpan": 1, "colSpan": 1, "header": false,
      "columnHeader": "Waiting period", "text": "24 months", "bbox": [0.36, 0.41, 0.92, 0.44] }
  ],
  "matchedCellId": "t3/r4c0"
}

A cell's columnHeader is the header of its column (the headers of every column it spans, joined, for a cell that spans several). column counts from zero, as in Word tables, and a cell that spans rows appears in every row it spans. A cell that spans columns is named by every column header it spans in the row's text (Bronze / Gold: 60 days). Every package reads these fields (ContentLocation.Cells in .NET; cells in Node.js, Python, Angular and React). The Angular document viewer marks the row and the matched cell on the page; the browser packages' citedRegions and citedRow give you the same boxes, and the row as columns, for your own interface.

Seek to playFromSeconds, not to startSeconds. They answer different questions:

  • startSeconds and endSeconds bound the passage the snippet came from. They describe the recording, not the query, so the same passage reports the same bounds whatever was searched. Use them for display.
  • playFromSeconds is where to start playing: the moment inside that passage your query actually matched, with a short lead-in so playback does not clip the phrase. It moves with the query, and for a long passage it can be well after startSeconds.

timingPrecision is segment or word and reflects how finely the recording was timed. Where it is coarse the playback offset is estimated within the passage rather than exact, so treat it as a good place to start listening rather than a frame-accurate cue.

A snippet is the passage that matched — the unit the content was indexed as, which is a page, a paragraph, a spreadsheet row or a span of speech depending on the kind. Search returns matching passages, not whole documents or full transcripts of recordings.

A snippet is an excerpt, not the whole passage: for speech it is the sentence the query landed in widened with its neighbours, so it stays readable however the recording was chunked. Its length still varies with the content — a spreadsheet row may be a few words — and it is not capped to a display size, so lay results out to wrap or clamp rather than assuming a fixed row height. A leading or trailing … marks where an excerpt was trimmed.

searchId identifies this search. It is distinct for every request, including an identical repeat of the same query, and is the identifier we record the search under. Log it: quoting it lets us find the exact request. Every response carries an X-Request-Id header, refusals included, and if you send one (printable characters, up to 128) we echo it rather than issuing our own, so a request keeps a single identity across your infrastructure and ours.

score ranks within one response. It is not a percentage and not comparable between queries; do not show it as a confidence, and do not threshold on it.

Only the active revision of an asset is searchable. Content still indexing does not appear.

Passages around a result

A result's snippet is the part of its passage worth reading. When you need more of the file around it (to give your own assistant the full context, say), ask for it with the search:

POST /api/content/v1/search
{ "query": "cataract waiting period", "context": { "before": 1, "after": 2 } }

Each result then carries context: up to that many passages before and after it, in order, each { "passageId", "text", "location" }. before and after are 0 to 3; at the start or end of a file fewer come back. On /answer the citations carry it the same way. context cannot be combined with group: "file" (422 validation_error, fields [["body","context"]]).

After the search, or for more, read the passages around a result by its passageId:

GET /api/content/v1/assets/{assetId}/passages?around=3.17&before=2&after=2
GET /api/content/v1/assets/{assetId}/passages?around=3.17&section=true
{ "assetId": "…", "revision": 3, "unit": "section",
  "items": [ { "passageId": "3.16", "text": "…exactly as indexed…",
               "location": { "page": 6, "charStart": 10432, "charEnd": 11610 } } ] }
  • before and after are 0 to 10 (2 each when omitted).
  • section=true returns the result's whole section instead: the passages under the same heading (Word, HTML and SCORM files), on the same page (PDF), or, for documents read with their layout, under the same headings. unit says which you got: section, page, or passages for a file with neither (a recording or a spreadsheet), which returns the passage and two each side. A section is at most 50 passages, centred on yours, with "truncated": true when it was cut. Do not send before or after with it.

Reading a file's indexed text

The text we index from a file can be read back exactly as indexed, in order, a page at a time:

GET /api/content/v1/assets/{assetId}/passages?limit=50
GET /api/content/v1/assets/{assetId}/passages?from=3.66&limit=50

The response is the one above with "unit": "passages", plus next: send it as from for the next page; it is absent on the last page. limit is 1 to 200 (50 when omitted). revision, also in the ETag header, is the revision search uses; a passageId of another revision is 412 revision_conflict. Neighbouring passages can share a few words; charStart and charEnd, where the file has them, show where each sits.

Who is reading: as on GET /assets/{assetId}, send asReader=true and the reader's principals (repeated) whenever a person will see the text; a restricted file not granted to them is then 404 asset_not_found, exactly as search would never show it. Without either, it is your organization's own view. The browser packages always read as the signed-in person.

Reading passages is not billed and is part of every plan. Until the file's first indexing has finished it is 409 content_not_ready. From the packages: GetPassagesAsync (.NET), getPassages (Node.js), get_passages (Python), passages() (Angular and React) and usePassages (React).

11What your plycdn service can index

GET /api/content/v1/capabilities
{ "formats": [ { "kind": "document", "extensions": [".pdf"], "describes": "Each page is split into passages; a passage never crosses a page" },
               { "kind": "video", "extensions": [".mp4", ".mov"], "describes": "Transcribed audio, with timestamps" } ],
  "maxFileBytes": 21474836480, "maxDocumentBytes": 268435456, "maxAudioSeconds": 43200 }

describes is a short label for the format. For a PDF it reads "Each page is split into passages; a passage never crosses a page"; see What can be indexed for how passages are made.

Read this rather than hardcoding a list of file types. Formats are added to the service over time, and a client that asks will accept a new one without being rebuilt. The supplied Angular package already does this, falling back to the formats it shipped with if the call fails.

12Following a library

GET /api/content/v1/activity?limit=20&offset=0
{ "items": [ { "assetId": "…", "externalId": "lecture-2", "filename": "Week 3.mp4", "kind": "video",
               "sourceUrl": "…", "sourceVersion": "…", "activeRevision": 2, "latestRevision": 3,
               "createdAt": "…", "revisionState": "transcribing",
               "connectorId": "…", "connectorName": "Lecture recordings bucket",
               "latestJob": { "jobId": "…", "state": "transcribing", "stage": "transcribing",
                              "progress": 45, "errorCode": null, "attempt": 0, "updatedAt": "…" } } ] }

Files with their most recent run, in one call. Use this for a library or progress screen rather than listing assets and then asking about each one's job, which is a request per row.

connectorId and connectorName say which connector brought a file in, or are null when it was registered directly. Show the name beside the file: "where did this come from" is the first question anybody debugging a sync asks.

Narrowing it

Parameter
connectorId Only what that connector brought in
kind video, audio or document
state A job state from the table under Following progress, matched exactly — ready, failed, awaiting_source_access, or for work in progress queued, extracting, transcribing or embedding. Several states can be given separated by commas: state=queued,extracting,transcribing,embedding,retry_scheduled
limit, offset Paging: limit is 1 to 100 (20 when omitted); offset starts at 0
bucketId Only the files that bucket or video library made searchable
q A fragment of the filename (at most 200 characters), not a whole word: lecture-3 finds courses/2026/lecture-3-revised.mp4
createdAfter, createdBefore ISO 8601. URL-encode them — a raw + in a query string is read as a space, and an offset like +05:30 then fails validation

Everything combines with AND. Without these, a library screen is a reverse-chronological list and nothing else — which stops being usable the moment a connector brings in a few thousand files at once, and leaves you watching a wall of filenames until something succeeds or fails.

GET /api/content/v1/activity?connectorId=…&state=failed&limit=50

Finding documents by name

A document picker lists files by name, a page at a time:

GET /api/content/v1/activity?order=filename&q=lecture&limit=50
GET /api/content/v1/activity?order=filename&q=lecture&limit=50&cursor=gAAAAABn…

With order=filename the list is by filename (then by id, so files of the same name keep their order), and nextCursor is present while more remain: send it back as cursor with the same other parameters. A cursor sent with different parameters, or without order=filename, is 422 cursor_mismatch. A finder cursor does not expire, and can be up to 4,400 characters long (a long filename in any script makes it longer), so allow for that in a URL or a field that holds it; a file added since simply appears in its place.

To list only what one reader may see - open files, and restricted ones granted to one of their principals - add asReader=true and the reader's principals (repeated: &principals=user:1481&principals=group:nursing). Without either, the listing shows every file, as it always has. The browser controller of the ASP.NET Core package always lists as the signed-in reader.

A storage event reaches the library in seconds. A connector with a notifyUrl starts its sync within a few seconds of the notification rather than waiting for the next scheduled pass, so a file uploaded to your bucket appears here — with its job, its stage and its progress — while somebody is still watching the screen.

GET /api/content/v1/assets/{assetId}/jobs

Every run recorded for one file, newest first, including attempts that failed - which is what tells someone why a file is not searchable.

GET /api/content/v1/settings

The organization's effective settings, as described under Configure your sources first. The callback secret is reported only as a boolean (callbackSecretSet); it is never returned.

allowedHostCeiling is the set of hosts plycdn permits at all, which bounds your own sourceHosts. Empty means unbounded. Show it wherever you let somebody type a storage host: without it, a host outside the ceiling is refused with source_host_outside_ceiling and nothing on screen says a bound exists, let alone what it is.

13Renewing access

Access to your files can expire — a signed URL has a lifetime, and processing may start later than you expect or run longer. There are two ways to handle it.

Supply fresh access when asked. When a job is awaiting_source_access:

PUT /api/content/v1/assets/{assetId}/source-access
{ "url": "https://…?<fresh sas>" }

Paused jobs for that asset resume. It answers 202 with {"assetId": "…", "resumedJobs": ["<jobId>", …]}. The address must equal the asset's registered sourceUrl before its query string (source_access_mismatch otherwise). To keep address and credential apart, send an unsigned url plus sasToken instead — a signed url, or an unsigned one with sasToken, never a signed url with sasToken (ambiguous_source_credentials).

Or let us ask you. Register assets with a callbackKey and configure callbackUrl and callbackSecret in your settings. We then request access when we need it, and you never have to watch for awaiting_source_access. This is the arrangement to prefer: nothing is stored that can expire, so a file registered once stays readable for as long as it exists.

Every asset reports which of the two it is on, as sourceAccessMode:

renewable Registered with a callbackKey. We ask you for a URL each time we read it. Nothing expires.
stored A signed URL captured at registration. It will eventually die and someone must send another.

Worth checking first when a file stops being readable, because the remedy is opposite in each case — and a callbackKey only helps if your callback can resolve that file's externalId. A file registered with renewable access whose id your callback does not recognise is worse off than one with a stored link: there is nothing to fall back to.

The callback contract

POST <your callback URL>
Content-Type: application/json
X-Content-Timestamp: 1789458231
X-Content-Nonce: 9f4c1ab27e0d4358bd61f0a2c7e39d84
X-Content-Signature: <base64 HMAC-SHA256>

{"organizationId":"…","externalId":"…","sourceVersion":"…","sourceUrl":"https://…"}

The body is compact JSON, UTF-8, never over 16 KB. The signature is base64(HMAC-SHA256(secret, "<timestamp>\n<nonce>\n<body>")). Verify it against the raw bytes received, not a re-serialized copy of the parsed object — a different key order fails a request that was perfectly valid.

Reject anything whose timestamp is more than 300 seconds from now, and remember each nonce for at least that window so a captured request cannot be replayed.

Answer 200 with:

{ "url": "https://…?<sas>", "expiresAt": "2026-09-14T20:04:00Z" }

Everything before the query string must match the asset's registered sourceUrl, or the response is rejected with source_access_mismatch. HTTPS only, port 443, no credentials in the URL. To keep address and credential separate, return an unsigned url plus sasToken — one or the other, never both.

Any status other than 200, or an answer larger than 64 KB, is reported as source_callback_refused, and the job is retried with backoff rather than paused — an endpoint that is down comes back, and the next attempt asks it again. Answer 200 with a URL you can serve, for every externalId you have registered.

14Managing content

POST   /api/content/v1/assets/{assetId}/reindex     # process the current version again
POST   /api/content/v1/jobs/{jobId}/cancel          # stop work in progress
DELETE /api/content/v1/assets/{assetId}             # remove from the index
GET    /api/content/v1/assets?limit=20&offset=0     # list
GET    /api/content/v1/assets/{assetId}             # one asset, with state and warnings

reindex answers 202 with the new run (assetId, jobId, revision); while the file has work in progress it is 409 asset_busy, and it needs an Idempotency-Key. cancel answers 202 {"jobId": "…", "state": "cancelled"} (409 job_not_cancellable once the job has finished). DELETE answers 202 with the removal's assetId, jobId and revision. GET /assets takes limit (1 to 100, 20 when omitted) and offset; each asset carries sourceAccessMode, metadata, aclMode and extractContentFromVideoFrames as well.

Deleting removes our copy of the index. Your original file is untouched — it was never ours. Deletion is not reversible; register the file again to re-index it.

activeRevision is null until indexing finishes. Compare it with latestRevision to tell whether an asset is searchable yet.

Playing a file from your own storage

GET /api/content/v1/assets/{assetId}/playback

For a file that a bucket or video library made searchable (it carries a source), signs a link to play or open it, the same way the storage routes do. A library video answers a stream:

{ "format": "hls", "url": "https://…/v/…/master.m3u8?…", "nativeUrl": "https://…", "expiresAt": "2026-10-07T12:00:00+00:00", "posterUrl": "https://…" }

A file of a bucket answers "format": "file" with the link to it and nativeUrl and posterUrl null. For a file in a public bucket the link does not expire; its expiresAt is only a nominal time. 404 asset_not_playable answers for a file that was not made searchable from one of your buckets or libraries, from a bucket with address-locked links, a protected recording, or a library with no source to play (play it from where it lives); 404 asset_not_found for an unknown id or another organization's; 409 video_not_ready for a video that cannot be played yet. As a reader (asReader with principals) the permissions apply: a file the reader may not see answers 404 asset_not_found. PlycdnContentApi.GetPlaybackAsync calls it, and the .NET browser controller's assets/{id}/source route uses it.

Proof of deletion

When a file's deletion has finished (DELETE /assets/{id}, or the file removed from a connected bucket), you can fetch its deletion receipt: a statement, signed by plycdn, of what was removed and when, and the date its last copies leave our encrypted backups. Anyone holding the receipt can check it without your account and without asking us.

GET /api/content/v1/deletion-receipts?assetId={id}&limit=50&before={next}
{ "items": [ { "receiptId": "…", "assetId": "…", "issuedAt": "2026-10-11T09:00:04.512000+00:00",
               "receipt": { "iss": "https://plycdn.com", "typ": "plycdn.deletion-receipt.v1",
                            "receiptId": "…", "organizationId": "…", "assetId": "…",
                            "externalIdSha256": "9f2c…", "kind": "document", "revisions": [1, 2],
                            "requestedAt": "2026-10-11T09:00:00Z", "completedAt": "2026-10-11T09:00:04Z",
                            "backupsExpireBy": "2026-11-15T09:00:04Z",
                            "removed": ["search index", "indexed text", "transcripts", "stored working copies",
                                        "name and source address", "labels and access list"],
                            "kept": ["usage and billing records"] },
               "jws": "eyJhbGciOiJFZERTQSIs…" } ],
  "next": null, "pending": false }
  • Newest first. limit is 1 to 100 (50 when omitted); pass next as before for the next page.
  • With assetId: that file's receipt. While its deletion is still running the list is empty and pending is true; ask again shortly (it usually takes seconds). An id with no deletion answers an empty list with pending: false. Files deleted before Content Search 1.20.0 have no receipt.
  • A receipt never holds the file's name, its externalId or its source address: the deletion erased them, together with the file's metadata and the list of people it was shared with. externalIdSha256 is the SHA-256 (hexadecimal) of the externalId you registered the file with, as UTF-8, so you can show which of your files it is by hashing the id you hold.
  • requestedAt is when you deleted the file (it left search at that moment), completedAt when its stored data was removed, and backupsExpireBy 35 days after that.
  • removed and kept say exactly what the deletion covers. Usage and billing records stay, because what the file was charged still stands; so do the file's id, kind and dates, and your audit log's entries, for as long as your account exists.
  • Receipts are kept for the life of your account. Each organization sees its own: a sub-organization's receipts are read with its id, your organization's with your account's. Receipts are not billed, every plan has them, and any key reads them from your server.

Checking a receipt. jws is the receipt in the standard compact JWS form (RFC 7515), signed with EdDSA (Ed25519). Our public keys are at https://plycdn.com/.well-known/plycdn-receipt-keys.json (a JWK Set, RFC 7517). When we replace a signing key the new one is added and the old one stays, so every receipt stays checkable.

A key we retire (after a replacement, or if it may have leaked) gets a validUntil in the key file, an ISO 8601 time in UTC. A receipt whose signed completedAt is later than its key's validUntil is not valid, even though its signature checks: it was signed after we stopped trusting that key. Receipts signed before validUntil stay valid. A key without validUntil is current.

  1. Read the kid in the JWS header and take the key with that kid from the published keys.
  2. Verify the signature with any JOSE library that supports EdDSA, or the standard library as below.
  3. Compare the verified payload with the receipt you hold: any change fails the signature.
  4. If the key has a validUntil, the receipt is valid only when its completedAt is not after it.
// Node.js 18 and later, nothing to install. An ES module (save it as check.mjs); `item` is one entry of `items`.
import { createPublicKey, verify } from 'node:crypto';

export async function checkReceipt(item, keysUrl = 'https://plycdn.com/.well-known/plycdn-receipt-keys.json') {
  const { keys } = await (await fetch(keysUrl)).json();
  const [header, payload, signature] = item.jws.split('.');
  const { kid } = JSON.parse(Buffer.from(header, 'base64url'));
  const key = createPublicKey({ key: keys.find((k) => k.kid === kid), format: 'jwk' });
  const signed = verify(null, Buffer.from(`${header}.${payload}`), key, Buffer.from(signature, 'base64url'));
  // The statement that was signed: equal to item.receipt when nothing was changed.
  const receipt = JSON.parse(Buffer.from(payload, 'base64url'));
  // A key we retired has a validUntil: a receipt signed (completedAt) after it is not valid.
  const { validUntil } = keys.find((k) => k.kid === kid);
  const retired = validUntil !== undefined && new Date(receipt.completedAt) > new Date(validUntil);
  return { valid: signed && !retired, retired, receipt };
}

From the server packages: ListDeletionReceiptsAsync (.NET), listDeletionReceipts (Node.js), list_deletion_receipts (Python). The dashboard's Audit log lists them too, to copy or download.

15Reading and correcting a transcript

A recording's transcript can be read and corrected from your backend. A correction replaces the text of the segments you name, and the file is indexed again with your text, without being transcribed again.

GET /api/content/v1/assets/{assetId}/transcript
{ "revision": 3, "warnings": [],
  "segments": [ { "id": "s1", "text": "helo class", "start": 0.0, "end": 1.5,
                  "speaker": "A", "language": "en",
                  "words": [ { "text": "helo", "start": 0.0, "end": 0.4, "confidence": 0.61 } ],
                  "timingPrecision": "word" } ] }

The ETag header carries the same revision. To correct:

PATCH /api/content/v1/assets/{assetId}/transcript
If-Match: "3"
Idempotency-Key: <a new UUID>
Content-Type: application/json

{ "segments": [ { "id": "s1", "text": "hello class" } ] }

segments holds at most 10,000 edits, each text at most 20,000 characters. 202, with the indexing run it started (assetId, jobId, revision). A corrected segment keeps its times and loses its word timings (timingPrecision: "segment"). If-Match must name the latest revision: if the file was indexed again since you read it, 412 revision_conflict, so read it again. A document, or a recording still indexing, answers 409 transcript_not_ready; a segment id that is not in the transcript, 400 invalid_segment_ids. From .NET: GetTranscriptAsync and CorrectTranscriptAsync.

16Tagging, grouping and permissions

Three separate mechanisms, easy to confuse. Metadata describes a file, collections group files, and permissions decide who may find one.

Metadata

Your own tags, in your own vocabulary. We never interpret them — they exist so you can narrow a search with filter.metadata.

PUT /api/content/v1/assets/{assetId}/metadata        # and GET, to read it back
{ "metadata": { "course": "CS101", "term": "autumn", "week": 3, "level": "undergraduate" } }

This is a PUT: what you send becomes the whole document. Values may be strings, numbers, booleans, or arrays of those. Up to 50 keys per file, each key 1 to 128 characters; a string value is at most 512 characters and an array at most 100 values. It answers {"assetId": "…", "metadata": { … }}, which GET /assets/{assetId}/metadata returns again. Writing metadata needs the metadata feature in your plan (not_included_in_plan otherwise).

Re-tagging never triggers a reindex and never costs you indexing. Metadata is filtered on, not searched — it does not change what a passage means, only which searches it is eligible for. Retag a whole library as freely as you like.

You can also send metadata when you register a file, which saves a call.

Collections

Named groups — a course, a module, a folder. You address them by an external id you choose, which is normally the id the same thing already has in your system.

PUT    /api/content/v1/collections/CS101
{ "externalId": "CS101", "name": "Introduction to Computer Science" }

PUT    /api/content/v1/collections/CS101/assets
{ "add": ["<assetId>", "…"], "remove": ["<assetId>"] }

GET    /api/content/v1/collections?limit=50&offset=0   # with an assetCount for each
DELETE /api/content/v1/collections/CS101            # the grouping only; files stay indexed

The external id appears in the address, so it is 1 to 512 characters of letters, digits and _ . ~ - only: MATH-101 works, MATH 101 (a space) or an accented letter is refused with 422 validation_error. The name is 1 to 512 characters. A collection can also carry metadata, with the bounds of a file's. Creating or changing one needs the collections feature in your plan.

PUT .../assets takes at most 1,000 ids in each of add and remove, applies add first and then remove, and answers {"externalId": "CS101", "assetCount": 42}. An asset id that is not yours is 404 asset_not_found; a collection that does not exist is 404 collection_not_found. DELETE answers 204.

GET /collections lists by name, a page at a time: limit is 1 to 200 (50 when omitted) and offset starts at 0; a value outside those bounds is 422 validation_error. Each item carries externalId, name, metadata, assetCount, createdAt and updatedAt. There is no total: keep paging while a page comes back full, and stop at the first that is not.

Saving a selection as a collection. One call creates a collection holding up to 1,000 documents:

POST /api/content/v1/collections
{ "name": "Tax audits 2026", "assetIds": ["<assetId>", "…"] }
{ "externalId": "selection-3f9a1c2b7d4e", "name": "Tax audits 2026", "assetCount": 41, "unavailable": ["<assetId>"] }

It answers 201. The externalId is made for you. Documents that are deleted or unknown are left out and listed in unavailable; with "asReader": true and the reader's principals, so are documents that reader may not see. More than 1,000 is 422 selection_too_large; an empty name or no assetIds is 422 validation_error. It needs the collections feature of your plan, and is recorded in the audit log as collection.created.

Registering a file against a collection that does not exist is refused (400 collection_not_found) rather than creating one. A typo would otherwise produce a new empty collection and quietly drop the file out of the one you meant — a mistake that surfaces weeks later as "search is missing things".

Permissions

By default a file is open: anyone who can search your organization can find it. That is the right default for a course catalogue and the wrong one for anything a particular person should not see.

PUT /api/content/v1/assets/{assetId}/permissions     # and GET, to read it back
{ "mode": "restricted", "principals": ["user:alice", "group:cs101-enrolled", "role:faculty"] }

A principal is any opaque string your system understands — a user id, a group, a role, an enrolment key. We never parse it and never expand groups, because your directory is the only place that knows who is in what. Each is 1 to 512 characters; a file holds at most 5,000, and a search sends at most 1,000. mode is open (no principals) or restricted. The answer is {"assetId": "…", "mode": "restricted", "principals": [ … ]}, which GET /assets/{assetId}/permissions returns again. Restricting a file needs the permissions feature in your plan; returning one to open always works.

Then say who is asking, on each search:

POST /api/content/v1/search
{ "query": "…", "principals": ["user:alice", "group:cs101-enrolled", "role:faculty"] }

Send every principal the person holds, expanded on your side. A restricted file is returned when any one of them has been granted it.

Which plans. Searching with principals works on every plan: it returns the files that are open, and any restricted file one of the principals has been granted. Restricting a file, with the call above, needs the permissions feature, which is part of Enterprise (Plans and prices). Returning a file to open always works.

Four things worth being precise about:

  • Omitting principals is not a way to search everything. It means "I am not telling you who this is", and the search then returns open files only. A job or integration that forgets to send them loses access rather than gaining it.
  • PUT replaces the whole grant list. If you are mirroring permissions from another system, that system is authoritative and incremental grant/revoke would leave behind a permission it removed months ago.
  • Restricted files are excluded before ranking, not filtered out of the results afterwards. A passage you may not see is never retrieved, never scored, and never counted in any total.
  • Set permissions at registration — "principals": [...] on POST /assets — if a file should never be world-visible. A follow-up call leaves a window in which it is indexed and open.

To make the strict posture the default for everything you register:

PUT /api/content/v1/settings
{ "requireAcl": true, "sourceHosts": ["…"] }

New files are then restricted unless you say otherwise, so an ingestion path that forgets permissions hides the content instead of publishing it.

17Answering a question

Where searching returns the passages, this returns a written answer built from them, with the passages it used.

POST /api/content/v1/answer
{ "query": "what should a student bring to the viva", "principals": ["user:alice"] }
{ "searchId": "…",
  "answer": "Bring the referral letter and photo identification [1]. Arrive fifteen minutes early [2].",
  "citations": [ { "number": 1, "cited": true, "snippet": "…",
                   "location": { "startSeconds": 80.69, … },
                   "sourceReference": { "externalId": "lecture-2026-09-02", … } } ],
  "withheldAsWeak": 0 }

The body is the same as a search — filter, principals and kind all work identically, because this runs a search and then answers from it. Three things follow, and they are the point:

  • The answer only ever uses your content. Every claim is grounded in the passages, and each one is cited by number so a reader can check it. Every number in the answer is one of the citations listed with it: a reference to anything else is removed before the answer reaches you.

  • Nothing you cannot see can be cited, because nothing you cannot see was retrieved.

  • A question your library cannot answer gets "answer": null and no citations, rather than a confident paragraph. If nothing clears the relevance floor, there is nothing to answer from. This is the explicit "nothing found, no answer" signal: test for a null answer (in a stream, answered is false on the done event) and show your own "not found" message.

  • The answer is written in the language of the question. Ask in English about a Hindi passage and the answer is in English. The passages, snippets and quotes it cites stay in the language of the source, exactly as stored.

  • Only passages worth quoting are used. A passage can be relevant enough to return from a search and still be too distant to answer from; those are left out rather than padding the context. Which bands qualify is decided by plycdn.

Show the citations, and mind cited. citations lists every passage the answer was offered; cited says whether the answer actually leant on one. Show the cited ones — put the rest behind a disclosure or leave them out. Presenting both alike is how a reader ends up judging a good answer by a passage it never drew on. When an answer cites nothing at all, every passage comes back cited: true, because saying that none of your content was used would be a worse answer than showing the passages the answer was built from.

An answer about a lecture is worth much less without the timestamp that lets a reader jump to 14:32 and see it for themselves.

Answers are billed separately from the search underneath them, per answer — not per token, and not per passage.

A time limit. timeoutMs (500 to 28,000) bounds the whole answer, its search included. When the search leaves too little time to write the answer, or the answer is still being written when time runs out, you get "answer": null with the passages found, all "cited": false, and "partial": true, "skipped": ["answer"]. That is not charged as an answer (the search under it is a search, as always). On a streamed answer the limit bounds when the first words must arrive; once they have, the answer finishes. skipped can also hold "rerank", as on a search.

Quotes checked word for word

Send "quotes": true and the answer quotes the passage's own words for each claim, just before its citation, and every quote is checked against the passage it cites:

{ "answer": "Cataract has a 24-month waiting period: \"24 months\" [1].",
  "verified": true,
  "citations": [ { "number": 1, "passageId": "3.17", "snippet": "…",
                   "quotes": [ { "text": "24 months", "verified": true,
                                 "answerStart": 41, "answerEnd": 50,
                                 "snippetStart": 88, "snippetEnd": 97,
                                 "charStart": 10520, "charEnd": 10529 } ] } ] }
  • A quote is verified when its words are in the passage exactly. Differences in spacing, and in how accented characters are encoded, are ignored; nothing else is (not case, not punctuation). Quotes stay in the passage's own language even when the answer is in another.
  • A quote is checked against the whole passage the answer was written from, not only the snippet shown with it. answerStart/answerEnd are UTF-16 offsets into answer; snippetStart/snippetEnd into the citation's snippet (as highlights are), present when the quote lies within the snippet. charStart/charEnd are offsets into the document in the units of location.charStart, present where the location has one. An unverified quote has no offsets.
  • verified on the answer is true only when the answer quotes at least once and every quote matched, false otherwise (a quote citing a number that is not in citations counts as unmatched), and null when answer is null.
  • Quotes are off by default, because they make an answer a little longer to write.

Answers draw on every document in the search's scope that has a relevant passage, not just the one that ranks highest: when the passages come from several documents, each document's best passage is offered first, then the rest by relevance, up to sixteen in all (eight from a single document), and the answer says which document each fact comes from. Scope an assistant to its documents with filter.assetIds, a saved selection or collections. limit on /answer no longer caps how many passages are offered: an answer is written from up to eight passages of one document, or up to sixteen across several, whatever limit says.

Follow-up questions

A person rarely asks one question. Send the conversation so far as conversation — up to six earlier turns, oldest first, each {"role": "user" | "assistant", "text": "…"} of at most 4,000 characters — and the new words as query:

POST /api/content/v1/answer
{ "query": "and for next year?",
  "conversation": [ { "role": "user", "text": "What does the tax audit checklist cover?" },
                    { "role": "assistant", "text": "Every receipt and invoice from the quarter [1]." } ],
  "principals": ["user:alice"] }
{ "searchId": "…", "question": "What does the tax audit checklist cover for next year?",
  "answer": "…", "citations": [ … ], "withheldAsWeak": 0 }

The follow-up is restated as a question that stands alone, and that is what is searched and answered; question tells you what it was, so you can show it ("Searched for: …"). The conversation is used for that one step and nothing else: what may be searched is still your filter, within, the selection and principals, for the organization your key acts as — a turn cannot widen it, whatever it says. The answer is written only from the passages found, never from the conversation. We do not store the conversation; send it with each question. question appears only when you send a conversation. A turn with any other field, another role, empty or longer text, or more than six turns, is 422 validation_error with fields naming it ([["body","conversation",0,"text"]]). Each follow-up is one answer, billed as one; restating it is part of that answer.

Receiving the answer as it is written

Send Accept: text/event-stream and the answer arrives as it is written, so a reader sees the first words at once. Each event is one line of JSON:

event: delta
data: {"text":"Bring the referral letter "}

event: delta
data: {"text":"and photo identification [1]."}

event: citations
data: {"citations":[{"number":1,"cited":true,"snippet":"…","location":{"startSeconds":80.69,…},…}]}

event: done
data: {"searchId":"…","question":"…","answered":true,"withheldAsWeak":0}
  • delta events carry the text in order; join them for the answer. citations comes once, after the text, with exactly what citations holds in the JSON answer (and cited read from the finished text). done ends a complete answer: answered is false when nothing in your library answered the question (no delta events then, and citations is empty). question and scope appear on done as on the JSON answer.
  • With quotes, the citations event carries each citation's quotes and done carries verified. With timeoutMs, done carries partial and skipped when something was left out; an answer left out entirely sends no delta events, its citations all cited: false, and done with "answered": false.
  • A refusal before the first event is an ordinary error response with its status (not_included_in_plan, quota_exceeded, too_many_steps and the rest). After it, a failure ends the stream with one error event, {"code":"…","retryable":…}, carrying the code the whole answer would have been refused with.
  • Closing the connection stops the answer. A stopped answer is not billed; only an answer that reaches done is. Ignore any event whose name you do not know: more may be added.
  • Without the header, the answer is the JSON response above, exactly as before.

18Suggesting queries as someone types

GET /api/content/v1/suggest?prefix=recipro&limit=10

Draws on searches your organization has made before that found something. Two rules keep it useful and safe: a query is only ever suggested if it returned results, and only if at least three searches have used it — so one person's unique search is never shown back to their colleagues.

{ "prefix": "recipro", "items": [ { "query": "reciprocal rank fusion", "searches": 7, "meanResults": 12.4 } ] }

prefix is 1 to 200 characters (longer is 422 validation_error, fields [["query","prefix"]]); a prefix of fewer than 2 characters answers an empty items. limit is 1 to 25 (10 when omitted). Suggestions need the suggestions feature in your plan.

Not billed. It is a keystroke, not a question.

19Finding related content

GET /api/content/v1/assets/{assetId}/related?limit=10&principals=user:alice

Other files whose content sits near this one — for a "you might also want" panel on a file's page. One row per file, not per passage. Permissions apply exactly as they do on search, so pass principals here too (repeat the parameter for each). limit is 1 to 50 (10 when omitted). It answers {"searchId": "…", "assetId": "…", "items": [ … ]}, each item with assetId, externalId, filename, kind, metadata and a similarity score. It needs the related feature in your plan.

Billed as one search: no question was typed, but an answer was returned.

20Finding what is broken in your library

GET /api/content/v1/analytics/library?limit=20

A count by state, what needs attention, and the list worth acting on first: files that indexed successfully and hold nothing searchable. That is the most confusing state a library can be in — the job succeeded, the file looks correct everywhere else, and it simply never appears in results. Almost always a document with no readable text, or a recording with no speech in it.

Each entry names the file and carries the warnings recorded while it was processed, so you can tell which of the two it is without opening anything.

The answer holds states (a count of files by the state of their latest job; deleted files are not counted), needsAttention (how many files have failed or are waiting for access, however many items lists), items (those files, each with assetId, externalId, filename, kind, jobId, state, stage, errorCode, attempt, updatedAt and previousVersionSearchable), indexedButEmpty and sourceMissing. When previousVersionSearchable is true the latest re-index failed but the file's previous version is still searchable: the file counts as ready in states, and the library list reports it the same way (latestJob.previousVersionSearchable; filtering by state=ready includes it). limit is 1 to 100 (20 when omitted) and caps each list.

sourceMissing lists files that are registered here and no longer present where they came from — renamed, moved or deleted in your own storage. They are withheld from search results while that is true, because returning a link that cannot open is worse than returning nothing. Each entry carries sourceUrl and missingSince, so you can tell whether a bulk reorganisation in your storage has quietly taken content out of your index. Put a file back and the next sync clears the mark; nothing here has been deleted.

21Seeing what people search for

GET /api/content/v1/analytics/searches?days=30&limit=25

Returns a summary (summary), your most common queries (topQueries), a daily series (daily) — and the queries that returned nothing (withoutResults). days is 1 to 365 (30 when omitted) and limit 1 to 200 (25 when omitted); windowDays repeats the window. It needs the analytics feature in your plan. That last list is the one worth acting on: it names the gap between what your library holds and what your readers came looking for, and nothing else in your systems can tell you.

The dashboard shows the same figures under Content search → Search analytics, including the searches that found nothing. Step by step: See what people search for. Query text is kept for 90 days by default. Change it with searchLogDays on your settings, or set it to 0 and we keep none at all — searches still work and are still counted.

recordingSince is when we began keeping query text, or null if none is kept. Show it. These figures cover searches from that moment; earlier ones were counted and appear on your usage statement, but what was asked was not recorded — so without it the totals here look like they contradict the bill, which is the first thing anybody reconciling the two will conclude.

22Tuning relevance

Three tools, and one rule that applies to all of them: tuning changes the order of results. It never changes relevance. That number stays comparable between queries whatever you configure, so you can keep thresholding on it.

PUT /api/content/v1/tuning/synonyms
[ { "term": "viva", "expansions": ["oral examination"] } ]

Your own name for something, where it appears nowhere in your content. Replaces the whole dictionary, and answers it as {"items": [ { "term": "viva", "expansions": [ … ] } ]}. At most 500 terms; a term is 1 to 100 characters with 1 to 20 expansions of 1 to 100 characters each, and a term that only expands to itself is refused. Terms are compared without regard to case.

PUT /api/content/v1/tuning/boosts/current-year
{ "name": "current-year", "match": { "year": "2026" }, "factor": 3.0 }

Above 1 promotes, below 1 demotes: factor is above 0 and at most 10. Matched against the same metadata you filter on, or against a kind (video, audio or document), or both; a boost names at least one. The name in the address and in the body must be the same (name_mismatch), 1 to 100 characters of letters, digits and _ . ~ -. A boost cannot hide a result — that is what a filter is for.

PUT /api/content/v1/tuning/pins
{ "query": "exam policy", "assetIds": ["<assetId>"] }

For this exact query, put these files first, in this order. A pinned result comes back with "pinned": true so you can label it. The query is at most 400 characters and is stored trimmed and in lower case, which is how it is matched; at most 10 assetIds. The answer is {"query": "exam policy", "assetIds": [ … ]}, and sending an empty assetIds removes the pin.

Read what is configured, and remove a boost you no longer want:

GET    /api/content/v1/tuning/synonyms
GET    /api/content/v1/tuning/boosts
GET    /api/content/v1/tuning/pins
DELETE /api/content/v1/tuning/boosts/current-year

Changing tuning needs the tuning feature in your plan. DELETE on a boost answers 204.

A pin promotes; it does not inject. If the file does not answer the query well enough to be found, it will not appear — which tells you something true about that file.

23Keeping a source in step automatically

If your content already lives somewhere, a connector keeps your library in step with it instead of you writing and running the registration loop yourself. Three kinds are supported:

s3 — any S3-compatible storage. Amazon S3, Google Cloud Storage in interoperability mode, MinIO, or any other service that offers an S3-compatible endpoint and an access key. Give it a read-only key; we list and download, and never write.

POST /api/content/v1/connectors
{
  "kind": "s3",
  "name": "Lecture recordings bucket",
  "config": { "endpoint": "https://s3.ap-south-1.amazonaws.com", "bucket": "lecture-recordings",
              "region": "ap-south-1", "prefix": "courses/2026/", "accessKeyId": "AKIA…" },
  "credential": "<secret access key>",
  "schedule": "nightly"
}

azure_blob — an Azure Blob container, read with a container SAS carrying List and Read only.

POST /api/content/v1/connectors
{
  "kind": "azure_blob",
  "name": "Lecture recordings container",
  "config": { "blobService": "https://youraccount.blob.core.windows.net",
              "container": "lectures", "prefix": "courses/2026/" },
  "credential": "<container SAS token>",
  "schedule": "nightly"
}

blobService is the account endpoint — Storage account → Endpoints → Blob service — and container is the container name on its own; put any folder in prefix. The older single containerUrl field is still accepted, so nothing you already created needs changing.

Two things about the SAS are worth planning for rather than discovering:

  • It expires, and when it does the connector stops. Create it against a stored access policy on the container rather than ad hoc. You can then extend or revoke it from the Azure portal without sending us a new one, and revoking the policy revokes the access immediately. Without a policy the only way to extend it is to issue a new token and update the connector.
  • List and Read, nothing else. We list the container and download from it. We never write and never delete, so a token with more than that grants us access we will not use. A token missing List is the one failure that looks like success: the container appears empty rather than returning an error.

We do not ask for your storage account key, and you should not send one. A key cannot be scoped to a container and cannot be revoked without rotating it for everything else that uses it.

canvas — Canvas LMS course files, with course enrolments carried across as permissions.

POST /api/content/v1/connectors
{
  "kind": "canvas",
  "name": "Nursing school Canvas",
  "config": { "baseUrl": "https://yourschool.instructure.com" },
  "credential": "<access token>",
  "schedule": "nightly",
  "defaultAclMode": "restricted"
}

Instant sync from storage events

Every connector read back carries a notifyUrl. POST anything to it and the connector syncs soon after, instead of waiting for the schedule — point your bucket's event notifications at it (S3 via EventBridge, Azure Event Grid, GCS Pub/Sub push, MinIO webhook targets, or any event service that can POST to a URL). The payload is never trusted or parsed for content: an event is only ever "something changed", and the next run believes what the source itself lists. The URL is a capability — treat it like a password, and note that deleting the connector retires it.

The address is the credential, so the call carries no Authorization header. It answers 202 {"accepted": true} and queues the sync; an address that was altered or has been retired answers 401 invalid_callback, and one that is not shaped like a notification address at all 404 {"error": "Not found"}. The body is not read except for the Event Grid validation handshake below; it may be up to 256 KB and must not be compressed (415 unsupported_media_type). Each sender address may send 600 notifications a minute; past that the answer is 429, which event services retry. A 502 or 504 means we could not be reached for a moment; retry. notifyUrl is null where plycdn has no public address for events to reach.

Which events to send. Send creations and deletions. Nothing is gained by filtering narrowly, and a deletion you do not tell us about is one we only notice on the next scheduled run.

Source Subscribe to
Azure Event Grid Blob Created, Blob Deleted. Add Blob Renamed and Directory Renamed only on a storage account with a hierarchical namespace — on an ordinary account they never fire at all.
Amazon S3 s3:ObjectCreated:*, s3:ObjectRemoved:*, delivered through EventBridge. S3 notifications cannot call a web address directly.
Google Cloud Storage OBJECT_FINALIZE, OBJECT_DELETE on a Pub/Sub push subscription.
Any other event service Its object-created and object-deleted events, delivered as a POST to the address.

Which event schema. Azure Event Grid's Event Schema dropdown offers three. Event Grid Schema and Cloud Event Schema v1.0 both work — each has its own endpoint-validation handshake and notifyUrl answers both. Custom Input Schema also reaches us, because the body is never read; choose one of the first two so the subscription can validate itself. Creating an Event Grid subscription requires the Microsoft.EventGrid resource provider to be registered on the Azure subscription: Subscription → Resource providers → Microsoft.EventGrid → Register. On a new subscription it is not registered, and the storage account's Events page fails before it can ask you anything.

Renames. No storage service reports a rename as a rename. S3 has no rename operation, so a console rename is a copy followed by a delete; Cloud Storage behaves the same way; Azure emits BlobRenamed only on hierarchical-namespace accounts. So a rename reaches us as one path disappearing and an identical one appearing, and we match the two by content and simply re-point the existing asset — reported as moved. The transcript, the corrections made to it, the permissions and any link you have already shared all survive, and you are not charged to transcribe it again. Where the content is genuinely ambiguous — two identical files, one of them renamed — we re-index rather than guess, because attaching the wrong transcript to a recording is not something you could undo.

The credential is sealed when stored and never returned — not here, not by any later read. The connector tells you whether one is set (credentialSet) and nothing more. To replace it, send a new one; to keep it while changing anything else, leave the field out.

schedule is nightly or manual (manual when omitted). enabled (default true) switches a connector off without deleting it; syncPending is true while a requested sync has not started. A nightly run only indexes what changed at the source, so it costs nothing on a night when nothing did. defaultAclMode applies to everything the connector registers (restricted when omitted): for Canvas, restricted mirrors the source's own enrolments, so a student finds what they are enrolled in and nothing else. A bucket carries no enrolments, so its files register as organization-visible; restrict individual files afterwards through the permissions endpoint.

GET    /api/content/v1/connectors
GET    /api/content/v1/connectors/{connectorId}
PUT    /api/content/v1/connectors/{connectorId}
DELETE /api/content/v1/connectors/{connectorId}
POST   /api/content/v1/connectors/{connectorId}/sync

POST answers 201 with the connector, DELETE answers 204, and PUT replaces the configuration and answers the connector (leave credential out to keep the stored one; leave extractContentFromVideoFrames out to keep its stored value, or send null to follow your organization's setting). Connectors need the connectors feature in your plan. sync returns 202 as soon as the run is queued — {"connectorId": "…", "syncPending": true, "requestedAt": "…"} — because a first pass over a real library registers thousands of files and would outlast any request. Ask twice and you still get one run; a connector that is switched off answers 404 connector_not_found. Read the connector back for lastRunAt, lastError and lastSummary:

{ "new": 12, "changed": 3, "unchanged": 481, "reauthorized": 40,
  "moved": 2, "removed": 1, "failed": 0 }

changed and reauthorized are counted separately because the difference is what the run costs you. A file whose content moved is transcribed again; a file whose enrolments moved is not re-indexed at all, only re-granted. Enrolments change constantly, so collapsing the two would mean re-transcribing your library every time somebody joined a course.

moved is a file that was renamed or moved within the source. It is re-pointed, not re-indexed, so it costs nothing.

failed is a count, so the connector also carries failures — the items it could not register, most recent first, each with the object's path and an error code from the table below. Capped at twenty, so a connector pointed at a source that is refused wholesale names the problem rather than returning thousands of identical lines.

"failures": [
  { "externalId": "azure:lectures/week-1.mp4",
    "errorCode": "source_host_not_allowed",
    "seenAt": "2026-09-18T04:07:23Z" }
]

The two causes worth knowing, because both are a minute's work once named: source_host_not_allowed means the file sits on a host you have not declared under settings — a connector is held to the same allowlist your own registrations are, so a source can never introduce content from an address you never approved — and a format code means we do not read that file type. Everything else is in the error table.

removed means the source stopped listing it. We mark it removed rather than deleting it — a source that returns an empty page during an outage would otherwise erase a library, and there is no undo for that. What the mark does do is withhold it from search: a result you cannot open is worse than no result, and a renamed or deleted file would otherwise keep being returned with a link that no longer resolves. It appears under sourceMissing in library health, and the moment the source lists the file again the mark is cleared and it is searchable as before. Nothing is deleted at any point.

Deleting a connector does not delete your library. The link goes and the stored credential with it; everything it indexed stays indexed and searchable.

Connectors go through the same registration path your own calls do, which means the same host allowlist applies. A source returning files on a host you have not declared under settings is refused, and the run reports it rather than registering content from an address you never approved.

24What your plan includes

GET /api/content/v1/plan
{ "plan": "growth", "enforced": true,
  "features": ["analytics", "collections", "metadata", "related", "suggestions", "tuning"],
  "limits": { "maxAssets": 50000 } }

features is drawn from metadata, collections, suggestions, related, analytics, tuning, answers, slides, permissions, connectors, storage, video and serial_playback, and, once live streaming is switched on for your service, live (with live_captions, live_restream and live_ads when your plan includes live captions, restreaming and ad insertion and each is switched on for your service); search itself is never a feature. Without one, the calls it covers answer 403 not_included_in_plan: writing metadata, collections, tuning or a restricted permissions list; suggest, related, analytics/searches, answer and the connector routes; and, for storage, creating a bucket or a custom domain and starting or completing an upload (S3 and Azure writes included); for video, creating a library or a video; for serial_playback, turning it on for a library (a library whose viewers can't skip ahead; 403 not_included_in_plan without it); for live, every live route answers 403 feature_not_in_plan (not not_included_in_plan), as do the destination routes without live_restream and ad breaks and ad settings without live_ads. slides decides whether frames of a recording are read at all; it never refuses a call. limits holds the numeric ceilings your plan sets — maxAssets, and where they apply buckets, custom_domains, object_bytes, video_duration_seconds and storageRequestsPerMinute (S3 and Azure tool requests a minute per storage credential) — and a ceiling that is not listed has no plan limit; read it as data and expect new ones. While live is in features, limits also carries live streaming's safety caps in force for your organization, by the names live_cap_reached gives in detail.cap: live_concurrent_streams, live_stream_max_seconds, live_max_height, live_max_kbps, live_realtime_viewers_per_stream, live_inputs, live_dvr_seconds and live_destinations (a cap that does not apply is left out; see Safety caps). It also says which live input settings your plan leaves out: live_backup_ingest and live_redundant_transcoding are false when it does (turning that setting on is then refused with 409 live_setting_not_in_plan), and are absent when your plan includes it. The server packages read a limit by name: ContentPlan.Limit(PlanLimits.…), planLimit(plan, PLAN_LIMITS.…) and plan_limit(plan, name). The viewer watermark and player logo are in every plan and have no feature name.

This call is never gated and is safe to make from a page. Read it when your interface loads and hide what is not included, rather than offering a control that fails when pressed — and read it after a not_included_in_plan refusal to find out what you do have.

enforced is false where no plan is applied to your account; everything is then available and features lists everything. That is not the same as a plan that includes nothing.

25What you have used

GET /api/content/v1/usage?month=2026-09

or a range:

GET /api/content/v1/usage?from=2026-09-01&to=2026-09-30

Defaults to the current month. to includes its own day — the range above covers all of September, through the 30th, not just through the 29th.

The period is read in your account's time zone, not UTC — a calendar month means that month where your account is, and the response says which one in period.timeZone. Every amount is in your account's currency, given as currency.

Each line carries the quantity, what your plan includes at no extra charge, what is billable after that allowance, the unit price and the amount — so a figure on your invoice can always be traced back to the work that produced it.

The allowance and the monthly minimum apply only to a whole calendar month. month= and a from/to pair that exactly spans one month both get you priced lines: quantity, included, billable, unit price, amount and a total. Any other range — a week, a quarter, an arbitrary pair of dates — gets you quantities only: included, billable, unitPrice, amount and total are all null, because there is no single month to apply an allowance or a minimum against.

priced is false where pricing has not been configured for your organization yet: the lines carry quantities and total is null. Treat that as "not priced yet" rather than as a total of zero.

Your first and last months are prorated. Your service starts at the moment you go live, on whatever day of the month that is, and ends at the moment it ends, if it does. Usage before you go live, or after your service ends, is never invoiced, with one rule for delivery and storage API (S3/Azure) usage: it is counted in whole UTC days, so a UTC day that is partly inside your service counts in full. The UTC day you go live on and the UTC day your service ends on are billed whole, on your first and last statements, inside that month's included quantities and minimum like any other day (even when that day starts before, or ends after, your local month). To pay for no hours before going live, go live at 00:00 UTC. Usage from your last days that is counted after your final statement closes appears on a short follow-up statement. In a month your service covers only in part, your plan's monthly minimum and every included quantity — the dashboard search allowance too — are multiplied by the calendar days your service was active that month, counted in your account's time zone (a day counts when any part of it is inside the service), divided by the days in the month: going live at 10:30 on 17 September gives 14 of 30 days, so a 900.00 minimum becomes 420.00 and 300 included searches become 140. Usage itself is priced normally. Such a month's response carries proration, and each prorated line carries it too; a whole month carries neither, and is exactly as it would otherwise be. The dashboard search allowance, a count of searches, is prorated to a whole search (half up); other included quantities keep six decimal places and money two, as everywhere on a statement. Graduated price tiers are not prorated: a tier's starting quantity is the same in every month, so only the included quantity and the minimum shrink. Monthly quotas are not prorated either (see Your quotas).

Fields on the response

Field Meaning
plan Your plan's name.
currency Your account's currency. Every amount on this response is in it.
status "open" for the current, still-moving month, or "closed" once a statement exists for it (see Statements below) — /usage?month= for a closed month returns the statement's own stored figures rather than recomputing them.
statementNumber The closed statement's number, null while the month is open.
scope "account" when you called with X-Organization-Id set to your account (the parent organization), "organization" when you set it to a sub-organization — decides which of the fields below are present, per Account and sub-organization scope below.
payAsYouGo Whether work above quota continues (billed) or pauses at 100%, for your account.
total The sum of every line's amount, including the monthly minimum and any adjustment. null for a range that is not a whole month, when no prices are configured for your account yet, and always when X-Organization-Id is a sub-organization. A line with priced: false adds nothing to it.
organizations[] Present when X-Organization-Id is your account (the parent): one entry per organization with usage — organizationId, listAmount, and lines[] each carrying metric, dimension, quantity, included (always null: allowances, the dashboard search allowance included, apply to the whole account), billable (that organization's own billed quantity; null on the dashboard searches line, whose free allowance is one pool for the account), listAmount and duplicatesNotCharged. See Account and sub-organization scope below.
lines[].quantity How much of that metric was used.
lines[].included How much your plan includes at no extra charge.
lines[].billable quantity less included, floored at zero.
lines[].unitPrice Your price per unit, in your account's currency.
lines[].amount billable × unitPrice — what that line adds to your total.
lines[].listAmount quantity × unitPrice, the line's amount before your plan's included quantity is deducted. On a line with volume tiers (unitPrice is null), the quantity priced through the tiers from the first unit. On the Dashboard searches (over allowance) line it is null at the account scope: that line's amount already covers only the searches past the account's shared allowance.
lines[].priced false when the metric has no price configured for your account: unitPrice and amount are then null, and the quantity is still shown.
lines[].lateFor Only on a late usage line: the closed month (YYYY-MM) the usage belongs to. Absent on every other line. See Late usage lines below.
lines[].duplicatesNotCharged How many file versions in this line matched content already charged, and so were indexed but billed nothing — see Duplicate content.
proration Present only for a month your service covered in part (the month it started or ended in): activeDays, daysInMonth, and from / to, the first and last active days (YYYY-MM-DD, null when no day of the month was active). The minimum and every included quantity were multiplied by activeDays / daysInMonth. Absent for a whole month and for a range.
lines[].proration On a line whose included quantity was prorated (and on the monthly_minimum line when the minimum was): {"activeDays": 14, "daysInMonth": 30}. Absent otherwise.
lines[].currentRate On a month's priced line: the rate of the band its last billable unit is in. On a line of one price it equals unitPrice; on a line priced in bands of different prices (unitPrice is null) it is the rate you are paying now.
lines[].appliedRates On a month's priced line: each band the billable quantity went through, as {"from", "to", "unitPrice", "quantity", "amount"} (to is null for the last band). The amounts add up exactly to the line's amount.
lines[].provisional In an open month, on a line with usage that has not settled yet (delivery and storage-API figures settle a few days after the day): {"quantity", "amount", "estimated": true}, the estimate at your prices on the band it lands in. Never part of amount or total; absent when there is none. For a range, amount is null.
provisionalTotal In an open month, at the account: the sum of the lines' provisional.amount. Never part of total; absent when nothing is waiting to settle.
gbBytes The bytes in one of this period's GB: 1000000000 once the period is billed in decimal GB. Absent before.

Two kinds of line are not metered work. monthly_minimum is your plan's monthly minimum (prorated in a month your service covered in part), shown as its own line when your metered lines add up to less than it. Adjustment lines are a correction or credit, each with its own customer-visible description, never inferred from usage. index_gigabyte_months is measured once per day and prorated: a file kept searchable for half a month contributes half a GB-month, not a full one.

Late usage lines

Delivery figures settle a few days after the day they describe. One that settles after its month was already closed into a statement is never added to that statement: it is billed in the month that is open when it settles, on a line of its own. The line's label names the month (for example Delivery (India & Asia), late usage for 2026-08), lateFor holds that month ("2026-08"), and dimension is the price key followed by /late-2026-08, so it is never merged with the open month's own line for the same metric.

A late line is charged the way the month it belongs to would have charged it, on that month's plan, prices, included quantity and minimum: what that month would have charged with this usage included, less what it already charged. So on a late line:

  • included is the part the closed month's unused allowance (or its monthly minimum) absorbed, and billable the rest;
  • amount is not billable × unitPrice: a quantity that spans price tiers, or that the closed month's minimum partly absorbed, is charged exactly as that month would have charged it;
  • unitPrice is the rate charged when one rate covered every billable unit, and null otherwise.

Late lines are added to total, but they never count toward the open month's own monthly minimum. Several late batches for the same month add up the way one batch of their total would have.

The processing section (below) carries an events count per metric alongside the quantity — how many indexing runs contributed to it, useful for sanity-checking a bulk import.

Account and sub-organization scope

You call with a key of your account; X-Organization-Id chooses the scope (a key bound to one organization always has that organization's scope, and a key bound to your main organization sees the main organization's own quantities, never its sub-organizations'). Calling with it set to your account (the parent organization) returns every line for the whole account — the parent and all its sub-organizations together — plus organizations[]: each sub-organization's own quantities, billable quantities and listAmount. Per-organization amounts do not add up to the account total, because the included quantities, any tiers and the minimum apply once, to the account as a whole. They are informational: each organization's amount is also rounded to the cent on its own, so even where nothing else differs they can differ from the account's lines by rounding. The account's lines and total are authoritative. The quantities do add up exactly.

Calling with X-Organization-Id set to a sub-organization returns only that sub-organization's own lines — the metrics it recorded something for — each with unitPrice and listAmount but no amount or total, which describe the whole account's bill. Every line carries billable: the sub-organization's own billed quantity for a whole priced month (null for a range or an unpriced metric, as on every line). included is null. The Dashboard searches (over allowance) line is the exception to billable: the dashboard allowance is one pool for the whole account, shared by every sub-organization, so a sub-organization sees its own dashboard searches (quantity) with included, billable and listAmount all null; the account's line applies the allowance. duplicatesNotCharged counts its own file versions. The lines are the same, key for key and figure for figure, before and after the month is closed. There is no other organization, and no minimum or adjustment, in a sub-organization's view.

  • /related counts as a search.
  • /answer is one search plus one answer when it returns a written answer; with no passage above the confidence floor, it is a search only.
  • Each further page (offset > 0) is its own search.
  • A search made from your dashboard counts the same as one from your application, and counts toward the same searches quota — see Dashboard searches for the free monthly allowance that applies there.
  • A library with nothing indexed yet returns no results and is not charged.
  • A search that fails before a result is returned is not charged.

What we processed, billed or not

The same response carries a processing section describing everything your content went through in the period, whether or not an invoice line covers it:

{ "processing": [
    { "metric": "audio_hours", "label": "Audio transcribed", "unit": "hours",
      "quantity": 12.5, "events": 9 },
    { "metric": "ocr_frames", "label": "Video frames read for on-screen text", "unit": "frames",
      "quantity": 428, "events": 9 }
  ] }

No money appears here — it answers what happened, not what is owed. Everything listed is a figure you could count for yourself from your own library.

26Usage by day

GET /api/content/v1/usage/daily?from=2026-09-01&to=2026-09-30

Quantities per local day, for a chart. No money — this endpoint never returns a price, an amount or a total, whatever your plan looks like.

{ "period": {"from":"2026-09-01","to":"2026-09-30","kind":"range","timeZone":"Asia/Kolkata"},
  "timeZone": "Asia/Kolkata",
  "metrics": [
    { "metric": "media_hours", "label": "Video and audio indexed", "unit": "hours",
      "points": [ {"day":"2026-09-01","quantity":1.2}, {"day":"2026-09-03","quantity":0.4} ] }
  ] }
Parameter
from, to Optional; YYYY-MM-DD, to inclusive as elsewhere. Without from the period starts on the first of the current month, and without to it ends on the last day of the month from falls in (both in your account's time zone). At most 400 days: period_too_long; a malformed date or to before from is invalid_period.
metric Optional. One metric only, to narrow the response. invalid_metric if it is not one of your catalogue's metrics.
breakdown=organization Optional, account scope only (X-Organization-Id is your account). Adds organizations, the same series per organization (below). invalid_breakdown for any other value.

Days are in the account's time zone. Only days with recorded usage appear in points: a day that is missing had none, so chart it as 0. A metric with no usage at all in the period is left out, unless you asked for it with metric=, in which case it is present with no points. Content kept searchable is a level, so its daily figure is that day's size in GB rather than GB-months.

With breakdown=organization and X-Organization-Id set to your account, the response also carries the same series split by organization:

"organizations": [
  { "organizationId": "…",
    "metrics": [ { "metric": "searches", "label": "Searches", "unit": "searches",
                   "points": [ {"day":"2026-09-01","quantity":3.0} ] } ] } ]

Called for a sub-organization, the response has its own figures only, with no organizations key, whatever breakdown says.

27Your running charges

GET /api/content/v1/usage/charges?month=2026-11

What the month comes to so far, at your prices, day by day: what has settled and, apart from it, the estimate of what has not settled yet. month is YYYY-MM in your account's time zone; left out, the current month. The dashboard shows the same figures under Billing & usage → Costs, and How-to: your bill and running charges walks through them.

{ "month": "2026-11", "currency": "INR", "status": "open",
  "settledTotal": 15420.5, "provisionalTotal": 1210.0, "minimum": 0.0,
  "byDay": [ { "day": "2026-11-01", "amount": 512.4, "provisional": null },
             { "day": "2026-11-20", "amount": 0.0, "provisional": 410.0 } ],
  "lines": [ { "metric": "delivery_gb", "dimension": "india-asia", "label": "Delivery (India & Asia)",
               "amount": 14980.0, "provisionalAmount": 1210.0 } ] }
Field Meaning
status "open", or "closed" once the month's statement is issued (its figures are the statement's).
basis "billed" at your account. "list" for a sub-organization: its own lines at your list prices from the first unit, never a share of what the account is billed (included quantities and bands apply to the account as a whole).
settledTotal What has settled so far. The days add up to it; for a closed month it is the statement's total. null while no prices are set for your account.
provisionalTotal The estimate of what has not settled yet, null when nothing is waiting. Never part of settledTotal.
minimum Your plan's monthly minimum; null for a sub-organization. The settled days carry it evenly, so the month's days add up to the statement.
byDay[].amount What settled for the day: the month to date through the day less the month to date through the day before.
byDay[].provisional The estimate of the day's usage that has not settled yet; null for a day with none.
lines[] Each line month to date: amount settled, provisionalAmount estimated.

Called as a sub-organization, the response holds its own lines and days only, at list prices (basis: "list"), its own estimate at list too, and no minimum. A malformed month is 400 invalid_period. From your server: GetChargesAsync (.NET), getCharges (Node.js) and get_charges (Python), in the Content Search and in the plycdn storage and video packages.

28Your quotas

From your server. Reading your quotas, and setting each sub-organization's limits, are also in the plycdn storage and video packages (from 1.16.0) as well as the Content Search packages, with the same names: .NET, Node.js and Python.

GET /api/content/v1/usage/quotas
{ "month": "2026-09", "timeZone": "Asia/Kolkata", "payAsYouGo": false,
  "alertThresholds": [80, 100],
  "metrics": [
    { "metric": "media_hours", "label": "Video and audio indexed", "unit": "hours",
      "quota": 200.0, "used": 168.0, "remaining": 32.0, "percent": 84.0,
      "enforced": true, "alertsReached": [80] },
    { "metric": "index_gigabyte_months", "label": "Content kept searchable", "unit": "GB-months",
      "quota": 500.0, "used": 210.0, "remaining": 290.0, "percent": 42.0,
      "enforced": false, "alertsReached": [] }
  ],
  "dashboardSearches": {"allowance": 500, "used": 120, "remaining": 380, "overAllowance": false,
                        "unitPrice": 0.5, "currency": "INR", "serviceActive": true,
                        "serviceStartsAt": "2026-09-17T05:00:00+00:00", "serviceEndsAt": null},
  "serviceActive": true, "serviceStartsAt": "2026-09-17T05:00:00+00:00", "serviceEndsAt": null }
  • quota is null where none is set — unlimited for that metric.
  • enforced is true for the metrics that stop new work at 100% (media hours, document MB, searches, answers) and false for a metric that is only ever reported (content kept searchable is a level, not a flow, and refusing to keep content already indexed makes no sense).
  • alertsReached lists which of your account's alertThresholds this metric has crossed this month.
  • payAsYouGo: when true, work above a quota continues and is billed at your list price rather than refused.
  • serviceActive, serviceStartsAt, serviceEndsAt: your service period — when you went live and, if it ends, when it ends (UTC instants; null when open) — and whether it is active now. While serviceActive is false (before your service starts, or after your service has ended) nothing is billed, dashboard searches included; the same three fields are on dashboardSearches.
  • Quotas are not prorated. A monthly quota and its alerts are the same in every month, the month you go live or your service ends included, and count everything used in the calendar month, including anything before your service starts; only the minimum and the included quantities are prorated.
  • Quotas are soft. Work already under way when a quota is reached is allowed to finish and is charged normally, so used can pass 100% by whatever was already in flight. At 100%, with payAsYouGo: false and that metric enforced, new work of that kind is refused with quota_exceeded (429) until the quota is raised or the month resets. Reading, search results already returned, and playback are never affected.
  • dashboardSearches is your account's dashboard search allowance — one pool shared by your parent organization and every sub-organization, so used counts all of them, whichever calls — see Dashboard searches. In the month your service starts or ends it is the prorated allowance, and used counts only searches inside your service, exactly as the statement applies it. It shares the searches quota and its alerts. unitPrice is your list price per search past the allowance, null while searches have no price configured for your account.
  • organizationQuotas: called as a sub-organization, the limits your account set for it, those that are set, in the shape of Limits for each sub-organization; always [] for your account itself.
  • Called as a sub-organization, metrics and alertThresholds are []: the plan's quotas, and what has been used against them, are the whole account's, and only your account sees them.
  • Until a billing account is set up for you, the response is empty rather than an error: month, timeZone and dashboardSearches are null and metrics and organizationQuotas are [].

29Your monthly statement

From your server. Listing, reading and exporting statements are also in the plycdn storage and video packages (from 1.16.0) as well as the Content Search packages, with the same names: .NET, Node.js and Python.

Once a month ends, plycdn closes it into an immutable statement with a permanent number. A closed month's figures never change; a later correction appears as an adjustment line on a different, still-open month, never a rewrite of the closed one.

GET /api/content/v1/statements
{ "items": [
    {"statementNumber":"PLY-202608-1A2B3C4D","month":"2026-08","currency":"INR",
     "total":500.00,"closedAt":"2026-09-02T04:00:00Z"} ] }

Newest first. Only closed months appear here — the current, still-open month is /usage (with status: "open"), not a statement.

Called with X-Organization-Id set to a sub-organization, each item has total: null and a subtotal instead: that organization's own amount at list price for the month (null if it had no priced usage). It is informational — the sub-organization is billed on the parent account, whose total is authoritative. subtotal is never sent at the account scope.

GET /api/content/v1/statements/2026-08

The statement as JSON: the same lines and fields as /usage?month=2026-08 for that month, with status: "closed" and its statementNumber, exactly as stored at close and never recomputed. It also carries:

Field Meaning
month The month it covers, YYYY-MM.
customer Your account's display name, as printed on the statement.
closedAt When the month was closed.
sha256 A checksum of the stored statement, so you can tell it has not changed since you last read it.
organizationNames Display names for organizations, by organizationId, where we were given them at close.
proration As on /usage: present only when the month was covered in part, and stored with the statement.

It has no processing section — that is /usage. Called with X-Organization-Id set to a sub-organization, the statement is that organization's own view: the same lines its /usage showed for the month (see Account and sub-organization scope above), with total null, no sha256 (it covers the whole account's statement), no minimum or adjustment line, and empty organizations and organizationNames.

GET /api/content/v1/statements/2026-08/export

Returns text/csv; charset=utf-8 with Content-Disposition: attachment; filename="PLY-202608-1A2B3C4D.csv" — the same numbers as a downloadable file, one row per statement line:

Statement,PLY-202608-1A2B3C4D
Customer,<your display name>
Period,2026-08-01,2026-08-31,Asia/Kolkata
Plan,growth
Currency,INR
Status,closed

Section,Organization,Item,Metric,Quantity,Unit,Included,Billable,Unit price,Amount
account,,Documents indexed,document_megabytes,6.000000,MB,1.000000,5.000000,2.000000,10.00
account,,Monthly minimum,monthly_minimum,,,,,,486.83
organization,Acme Main,Documents indexed,document_megabytes,2.000000,MB,,2.000000,2.000000,4.00
total,,,,,,,,,500.00

A prorated month (the month your service started or ended in) adds a Service row under Status — the first and last active days and the proration — and a final Proration column, filled on each line whose included quantity or minimum was prorated:

Status,closed
Service,2026-09-17,2026-09-30,prorated 14/30 days

Section,Organization,Item,Metric,Quantity,Unit,Included,Billable,Unit price,Amount,Proration
account,,Documents indexed,document_megabytes,30.000000,MB,14.000000,16.000000,2.000000,32.00,prorated 14/30 days
account,,Monthly minimum,monthly_minimum,,,,,,358.00,prorated 14/30 days
total,,,,,,,,,420.00

A whole month's CSV has neither, and is exactly as above.

The Organization column names a sub-organization when you gave us its display name at close, otherwise its id. An organization row's Billable is that organization's own, as in organizations[].lines on /usage; Included is empty, and both are empty on the dashboard searches row, whose free allowance is shared by the whole account. Organization rows, like the per-organization amounts on /usage, are informational; the account rows and the total row are authoritative. 404 statement_not_found when that month has never been closed.

Text cells are safe to open in a spreadsheet. A text cell (a name, a label, a plan) that would begin with =, +, -, @, a tab or a carriage return is written with a leading ', so a spreadsheet shows it as text rather than running it as a formula: an organization named =Sales appears as '=Sales. Numbers are never altered.

Called with X-Organization-Id set to a sub-organization, the export has that organization's own lines only, as account rows whose Amount is the line's list amount, no organization rows, and an empty total row.

From .NET, ExportStatementCsvAsync returns this CSV as a plain string, not a stream — read it as text, not through GetAsync<T>.

30What was done to each file

GET /api/content/v1/usage/assets?from=2026-09-01&limit=50&offset=0

The question a period total cannot answer: not what you owe, but what happened to this recording. Each row names the file and what was done to it. limit is 1 to 200 (50 when omitted), offset starts at 0, and from and to default to the current month as on /usage.

{ "period": {"from":"2026-09-01","to":"2026-09-30","kind":"month","timeZone":"Asia/Kolkata"},
  "items": [
    { "assetId": "…", "organizationId": "…", "externalId": "lecture-04",
      "filename": "lecture-04.mp4", "kind": "video",
      "createdAt": "2026-09-14T09:12:00Z", "extractContentFromVideoFrames": null,
      "deleted": false, "billed": { "media_hours": 0.0 }, "duplicateOf": "…",
      "processing": { "audio_hours": 1.4, "ocr_frames": 62, "source_bytes": 734003200 } }
  ], "total": 38 }
Field Meaning
organizationId The organization the file belongs to.
deleted true for a file removed since — it still appears, because what it was charged still stands.
billed What was charged for this file in the period, by metric. 0 for a duplicate that was not charged.
duplicateOf When the file was not charged because identical content was already charged, the asset it matched; otherwise null. See Duplicate content.
processing What was done to it, charged or not.
total How many files had work or a charge in the period, before paging.

Called for your account (X-Organization-Id is the parent), this lists every file in the account — the parent and every sub-organization — newest first, each with its organizationId. Called for a sub-organization, it lists that organization's own files only. Because duplicates are recognised across the whole account, duplicateOf can name a file in another organization of the same account, which a sub-organization's own list does not contain.

A recording that declined frame extraction simply has no ocr_frames entry. extractContentFromVideoFrames is what that file was registered with — null means your organization's setting decided.

Neither this nor /usage is ever gated: whatever your plan includes, you can always see what your own content went through.

31Reading text shown on screen

Recordings are transcribed from their audio. Where on-screen reading is enabled for your account, we also take still frames at slide changes and read the text on them, so what was shown is searchable alongside what was said.

You decide whether that happens, in three places, most specific first:

POST /api/content/v1/assets
{ "externalId": "lecture-04", "filename": "lecture-04.mp4", "kind": "video",
  "sourceUrl": "https://storage.example.com/lecture-04.mp4", "sourceVersion": "\"etag\"",
  "extractContentFromVideoFrames": false }
Set it on Effect
An asset, at registration Decides for that recording. null inherits your organization's setting.
Your organization, under settings The default for every file that does not say for itself.
A connector The default for everything that source brings in. null inherits the organization.

false means audio only: no frames are taken from the recording at all. Omit it and nothing changes from how your integration behaves today. The setting is returned on the asset, so what a recording was registered with can always be checked afterwards, and it cannot buy a capability your plan excludes — a plan without on-screen reading reads no frames whatever you send.

32Storage and delivery

A separate capability from indexing: buckets hold files and serve them, whether or not those files are also registered with Content Search. Full walkthroughs and SDK usage are in Storage and delivery; this is the wire contract. The same buckets are also reachable with S3 and Azure tools (S3 and Azure compatibility). All of it is under the same base address and authentication as the rest of this guide.

Regions

GET /api/content/v1/regions
{ "items": [
    { "code": "mumbai",    "name": "Mumbai, India",    "strictCapable": true,  "country": "IN", "live": true,
      "endpoints": { "s3": "https://s3.in-mum.plycdn.net",
                     "s3VirtualHost": "https://{bucket}.s3.in-mum.plycdn.net",
                     "blob": "https://{account}.blob.in-mum.plycdn.net",
                     "blobGlobal": "https://{account}.blob.plycdn.net",
                     "upload": "https://in-mum.upload.plycdn.com" } }
  ] }

The list is the regions open for new buckets today, the same for every account; new regions are added over time. Treat region codes as strings and read the list rather than hard-coding it.

country is the ISO 3166-1 country the region is in; strict residency (strictResidency) is judged by country. A region code that does not exist, or is not open yet, fails with region_not_available. Each region also says storageOnly (true where files are stored and processing happens in India), processingCountry (the country where processing happens, IN) and drTargets (the locations where a copy of a bucket there can be kept). strictResidency is offered only where strictCapable is true; asking for it elsewhere fails with strict_residency_not_available. See Choose where files live. live is true where live streaming is offered: a video library in that region can have live inputs (creating one in a region where it is false fails with region_not_available).

endpoints are the region's hosts for S3 and Azure tools and for part uploads, as patterns: replace {bucket} with a bucket name and {account} with your storage account name. blobGlobal is the same for every region (it reaches your account's home region). Read hosts from here rather than building them, and treat the list of regions as data: regions are added over time. S3 and Azure compatibility explains each host.

Buckets

POST /api/content/v1/buckets          # 202
Idempotency-Key: <your own unique value>
{ "name": "course-media", "region": "mumbai", "visibility": "private", "strictResidency": false }

Idempotency-Key is required on this call (400 idempotency_key_required without it): repeating the call with the same key and body returns the first answer instead of creating a second bucket, and the same key with a different body is 409 idempotency_conflict. Video libraries, videos, custom domains and webhooks need one too.

{ "id": "…", "name": "course-media", "kind": "files", "region": "mumbai", "strictResidency": false,
  "visibility": "private", "state": "active", "failureReason": null, "suspended": false,
  "delivery": { "allowedDomains": ["learn.example.com"], "blockNoReferrer": false,
                "countriesAllow": [], "countriesBlock": [], "linkTtlSeconds": 900,
                "ipBinding": false, "rateLimitKbps": null,
                "webPagesOnOwnDomains": false },
  "uploadRules": { "maxObjectBytes": null, "allowedTypes": ["video/*", "application/pdf"],
                   "allowOverwrite": false },
  "cache": { "edgeTtlSeconds": null, "browserCacheControl": null, "rules": [] },
  "cors": { "allowedOrigins": [], "allowedMethods": ["GET", "HEAD"], "allowedHeaders": [],
            "exposeHeaders": [], "maxAgeSeconds": 600, "allowCredentials": false },
  "defaultHostname": "course-media.plycdn.net",
  "deliveryBaseUrl": "https://course-media.plycdn.net",
  "storedBytes": 0, "objectCount": 0, "createdAt": "…", "updatedAt": "…",
  "deletedAt": null, "purgeAfter": null }

name is 3 to 63 characters, unique across plycdn (see Bucket names); it is the bucket's hostname label: defaultHostname is {name}.plycdn.net.

Making a bucket searchable

One switch on a bucket or a video library (a library's id works wherever a bucket's does) makes its files, uploaded videos and live recordings searchable. Guides: Make a bucket searchable and Make a video library searchable.

search is accepted on POST and PATCH of /buckets and of /libraries (an admin key), and is in every bucket and library answer:

"search": { "enabled": false, "folder": null, "access": "open", "slides": "inherit", "language": null }
"search": { "enabled": false, "folder": null, "access": "open", "slides": "inherit", "language": null, "includePastRecordings": true }

The second form is a video library's. enabled is a boolean; folder a string or null (stored with a trailing /; null is the whole bucket); access is open or restricted; slides is inherit, on or off; language is a code such as hi or en-IN, or null to detect it passage by passage; includePastRecordings (default true, libraries only: on a files bucket it is 422 validation_error at ["body","search","includePastRecordings"]) says whether recordings that finished before search was turned on are included. A PATCH merges the fields it names; folder and language are cleared with null; null on any other field is 422 validation_error.

GET /api/content/v1/buckets/{bucketId}/search
{ "bucketId": "…", "kind": "files", "settings": { "enabled": true, "folder": null, "access": "open", "slides": "inherit", "language": null },
  "total": 1240, "counts": { "searchable": 312, "indexing": 925, "waiting": 3, "skipped": 0 },
  "reasons": { "allowance_reached": 3 } }

total is the sum of counts. While enabled, indexing includes files in scope not yet reached while they are being reached (counted up to 10,000), and none once your plan no longer includes search. reasons counts each reason present; absent ones are left out.

DELETE /api/content/v1/buckets/{bucketId}/search            # admin key

Removes the bucket's files from search and turns search off; answers 200 with the status above (enabled false, counts zero). The files themselves stay. A standard key is refused with admin_key_required (403). Two changes meeting on the same files can answer 503 processing_temporarily_unavailable (retryable, with Retry-After): ask again.

Each file (GET /buckets/{id}/objects, GET /objects/{id}) and each video, and so every video.* event, carries its state:

"search": null
"search": { "state": "searchable", "reason": null, "assetId": "…" }

null means search is not on for it. state is searchable, indexing, waiting or skipped:

state reason Meaning
searchable none Found by search
indexing none Being made searchable
waiting allowance_reached Your monthly search allowance is reached; it carries on when the allowance renews
waiting file_limit_reached Your plan's file limit is reached; it carries on when the limit is raised
skipped protected_delivery The bucket binds links to a viewer's address
skipped residency The bucket keeps processing in its country
skipped unsupported_type This kind of file is not searchable
skipped too_large Larger than search can read
skipped no_readable_copy A video with neither its kept original nor its MP4 download (a recording without its download)
skipped unreadable The file could not be read
skipped removed You deleted its search entry. It stays out of search until the file is uploaded again, or you remove the bucket from search and switch it on again. A copy or rename under a new name is a new file

Skipped files are checked again by themselves: once ipBinding is turned off on the bucket (a PATCH of its delivery), every file skipped for protected_delivery is made searchable, each once; a file unreadable is tried again up to three times, an hour apart, and then stays skipped. Uploading a file again checks it again. unsupported_type, too_large, no_readable_copy and removed stay until the file (or video) is written again.

Refusals: turning search on without storage (video, for a library) and Content Search in the plan is 403 not_included_in_plan, and so is access: "restricted" without the permissions plan feature (restricted files are found by nobody until granted). On a plan without search, a change to the settings while search is on is refused the same way: turn it off first (turning it off is always allowed). Another organization's bucket is 404 bucket_not_found.

Turning off a live input's indexRecording does not take recordings already registered out of search; the DELETE above does. A recording that could not be made searchable is withdrawn, not left failed.

Bucket names

GET /api/content/v1/bucket-names?name=course-media
{ "name": "course-media", "available": true, "reason": null, "hostname": "course-media.plycdn.net" }

hostname is the address a bucket of that name gets (so a form can show it before the bucket exists), whether the name is available or taken; null for an invalid name. Works with any API key, standard or admin, answered for the organization named in X-Organization-Id. reason is null, "invalid" (3 to 63 characters of a-z, 0-9 and -, starting and ending with a letter or digit, no -- in characters 3–4) or "taken" (in use anywhere on plycdn, held after a purge, retired, or not available). A deleted bucket that was ever public has its name retired: "taken" for every other account, for good; your own account and its sub-organizations still see "available" and may create it (see Bucket names). Advisory: POST /buckets decides, with 409 bucket_name_taken. More than 120 checks a minute for your account answers 429 rate_limited with Retry-After. A missing or longer than 100-character name is 422 validation_error.

GET  /api/content/v1/buckets
GET  /api/content/v1/buckets/{bucketId}
PATCH /api/content/v1/buckets/{bucketId}
DELETE /api/content/v1/buckets/{bucketId}
POST /api/content/v1/buckets/{bucketId}/restore
POST /api/content/v1/buckets/{bucketId}/retry

A bucket or library with a disaster-recovery copy carries replication (region, state, upToDateAt).

GET    /api/content/v1/buckets/{bucketId}/replication     # any key
PUT    /api/content/v1/buckets/{bucketId}/replication     # admin key: {"region": "<a code from drTargets>"}
DELETE /api/content/v1/buckets/{bucketId}/replication     # admin key

The answer is { "region", "state", "reason", "upToDateAt", "copiedObjects", "totalObjects", "billedGb", "transferGb" }; state is preparing, copying, active, attention, stopping, switching or off. Deleting a file deletes it from the copy too. Plans: Growth and Enterprise. Errors: replication_not_in_plan (403), bucket_not_active (409), replication_region_not_available, replication_same_region and replication_residency_conflict (400), replication_already_on and replication_busy (409), replication_not_found (rare: the copy changed while you were acting; try again) and feature_not_available (404). DELETE on a bucket with no copy answers 200 with state off. Step by step: Keep a disaster-recovery copy.

kind is "files", or "video" for a video library (see Video and webhooks); more kinds may follow, so treat any value your integration doesn't recognise as one to ignore rather than reject. state is creating, active, failed, deleting or deleted. A new bucket stays creating while it is provisioned, including a bucket that is only waiting on its TLS certificate — that is not itself a failure. If provisioning cannot finish before its attempts run out, the bucket becomes failed with a failureReason and retry re-attempts it from where it left off:

failureReason Meaning What to do
certificate_pending Provisioning ran out of attempts still waiting on the bucket's TLS certificate retry — usually succeeds once a certificate is available
no_storage_capacity No storage capacity could be reserved for the bucket's region retry, or try again later; consider another region if it persists
no_cdn_capacity No delivery capacity could be reserved retry, or try again later
provider_unavailable A transient fault outlasted every attempt retry
provisioning_failed Provisioning could not complete for any other reason retry; if it keeps failing, contact us

failureReason is null except in the case above and one more: a PATCH that changes delivery settings can fail to reach the edge after every attempt. The bucket then stays in whatever state it was in (usually active, or deleting if a delete is in progress — either way it keeps serving, or not serving, exactly as it did before the change) with "failureReason": "configuration_failed". Nothing to retry yourself: the change stays queued, and the next delivery-settings change (from you, or plycdn's own retry) that reaches the edge clears it. Treat any failureReason value you don't recognise the same as provisioning_failed. PATCH updates visibility, delivery, uploadRules, cache and cors (see Cache and CORS settings); DELETE soft-deletes with a 7-day restore window, after which restore fails with restore_window_passed — deletion stops serving immediately, even if the delivery settings behind it could not be fully applied. retry re-attempts provisioning for a failed bucket. Names are unique across plycdn (bucket_name_taken); an operation on a bucket that is not active (other than restore/retry/reading it) fails with bucket_not_active — retryable while the bucket is still creating, since it becomes active on its own. A bucket plycdn has taken down (see Takedowns in Storage and delivery) shows "suspended": true: it delivers nothing, and starting, renewing or completing an upload, or signing a link, fails with 403 bucket_suspended until plycdn reinstates it; listing, reading and deleting still work, so you can remove what was reported. Creation itself can fail with bucket_hostname_unavailable if no default hostname could be allocated — rare, and safe to retry. More than 20 bucket creations a day for your account answers 429 rate_limited (creating a video library counts as one). DELETE and retry answer 202; restore answers the bucket.

Limits on the settings: delivery.linkTtlSeconds 60 to 604,800; delivery.rateLimitKbps 64 to 10,000,000; delivery.allowedDomains at most 50 entries and each country list at most 250; uploadRules.allowedTypes at most 50; uploadRules.maxObjectBytes 1 to 1,342,177,280,000.

Web pages. delivery.webPagesOnOwnDomains (a switch, off by default) shows HTML pages in the browser instead of downloading them, on the bucket's own custom domains (and on a shared address that routes to it), so course packages such as SCORM or xAPI exports, Storyline's story.html or index_lms.html play as they did on your old host. It applies to text/html and application/xhtml+xml files, only on a private bucket with plycdn links. On the bucket's plycdn address ({name}.plycdn.net) pages always download. Other file types are unchanged. See Move from another cloud.

Changing a bucket. In a PATCH, a field you leave out is unchanged, and an explicit null removes a setting, returning it to its default:

Setting null means
delivery.rateLimitKbps no speed limit
delivery.linkTtlSeconds plycdn's default link lifetime (15 minutes)
delivery.allowedDomains, delivery.countriesAllow, delivery.countriesBlock no restriction (the same as [])
uploadRules.maxObjectBytes your plan's largest file
uploadRules.allowedTypes any type (the same as [])
cache.edgeTtlSeconds, cache.browserCacheControl plycdn's default
cache.rules no rules (the same as [])
cors.allowedOrigins CORS off (the same as [])
cors.allowedMethods, cors.allowedHeaders, cors.exposeHeaders, cors.maxAgeSeconds their defaults (GET and HEAD, none, none, 600)
PATCH /api/content/v1/buckets/{bucketId}
{ "delivery": { "rateLimitKbps": null }, "uploadRules": { "maxObjectBytes": null } }

The switches (delivery.blockNoReferrer, delivery.ipBinding, delivery.webPagesOnOwnDomains, uploadRules.allowOverwrite, cors.allowCredentials), visibility, and delivery, uploadRules, cache or cors as a whole always have a value, so null on any of them is refused with 422 validation_error, fields naming it (for example [["body","delivery","ipBinding"]]): send false, or the value you want. The audit entry (bucket.updated) records a removal as that field set to null in detail, and lists what was removed in detail.cleared (for example ["delivery.rateLimitKbps"]). Removing a setting that was never set changes nothing ("outcome": "unchanged"). In the .NET package, BucketPatch's ClearRateLimitKbps, ClearLinkTtlSeconds and ClearMaxObjectBytes send the null; a property left unset is not sent.

Objects

GET /api/content/v1/buckets/{bucketId}/objects?prefix=week-1/&cursor=…&limit=100
GET /api/content/v1/objects/{objectId}
PATCH /api/content/v1/objects/{objectId}
DELETE /api/content/v1/objects/{objectId}
{ "id": "…", "bucketId": "…", "key": "week-1/intro.mp4", "size": 123, "contentType": "video/mp4",
  "sha256": "…|null", "checksumState": "verified|unverified|pending|mismatch|not_requested", "etag": "…",
  "state": "stored|disabled", "metadata": {}, "url": "https://…|null",
  "createdAt": "…", "updatedAt": "…", "createdVia": "plycdn|s3|azure" }

createdVia says how the object was written: plycdn through this API, an SDK or the dashboard; s3 or azure through the S3- or Azure Blob-compatible endpoint (S3 and Azure compatibility). It describes the latest write of the key.

url is present only where an object can be reached without signing (a stored object in a public bucket). An unknown id fails with object_not_found. A disabled object ("state": "disabled", after a checksum mismatch or a takedown) is still listed and returned, so you can see and delete it, but it is never delivered: /sign answers object_not_found for it, as it does for a key or id of another bucket.

Listing. Objects come back in byte order of the key's UTF-8 (as S3 lists: B before a, é after z), disabled ones included. prefix is a literal key prefix, not a pattern: week-1/ lists every key that starts with it, at any depth. There is no delimiter, so group keys into folders yourself. limit is 1–1000 (100 when omitted). nextCursor is opaque: pass it back unchanged as cursor for the next page and stop when it is null; never build or parse one, since its format can change.

Metadata. PATCH replaces the whole metadata object, so send every label you want to keep: at most 64 keys, each value a string, number, boolean or null, and at most 8 KiB as JSON; anything else is validation_error. It answers the updated object.

Deleting. DELETE answers 204 with no body. The object stops being listed at once and its key can be uploaded again straight away; its bytes and any copies cached at the edge are removed shortly after.

PATCH and DELETE can answer object_busy (409, retryable) while another change to the same file is in progress, such as an upload landing on its key; nothing was changed, so retry shortly. A key is 1 to 1,024 bytes of UTF-8 with no leading or trailing /, no //, no . or .. segment and no control characters; one beginning .plycdn- (in any case or spelling) is reserved. A key that breaks these is refused with 422 validation_error at upload time. A \ in a file name is treated as a folder separator (/), so Windows paths work as they are. The rules apply to the name with /, so a\..\b is refused like a/../b, and the file is listed and served as a/b.

Content types. Every delivery response carries X-Content-Type-Options: nosniff: a browser uses the contentType the object was uploaded with and never guesses one from its bytes, so declare the right type when you start the upload.

A type that can run script in a browser is always delivered as a download, in a sandbox (Content-Disposition: attachment, Content-Security-Policy: sandbox), even if inline is asked for: HTML, XML (text/xml, application/xml, text/xsl and every …+xml type, SVG and XHTML included), multipart/x-mixed-replace, multipart/related and message/rfc822. Every other type is served as declared.

uploadRules.allowedTypes entries may end in /*, and image/* admits image/svg+xml, which is such a type. For files your users upload, list the image types you want (image/png, image/jpeg, image/webp, …) rather than image/*, so an SVG is refused. On a bucket with allowedTypes, a file whose first bytes are markup (HTML, SVG or XML) declared as another type (say image/png) is refused with file_type_not_allowed unless the bucket allows that markup type.

Delivery URLs and their query. A delivery request whose query string contains response, partNumber, versionId, uploadId or X-Amz- (written as here, in lower case, in upper case or with a capital first letter), or a percent-escape of any letter of those names, is refused with 403 at the edge: such parameters would make the storage behind the edge answer something other than the file. A query of your own that happens to contain one is refused too, for example ?download=Response.pdf: choose another parameter value. Other parameters pass (a signed link must still be used exactly as issued).

Uploads

POST /api/content/v1/buckets/{bucketId}/uploads   # 201
{ "key": "week-1/intro.mp4", "contentType": "video/mp4", "size": 123, "sha256": "…" }

contentType is one media type in lower case (type/subtype, optionally ; and printable parameters). A comma may appear only inside a quoted parameter value (text/plain; x="a,b"): a value such as video/mp4, text/html is 422 validation_error with fields [["body","contentType"]].

{ "id": "…", "bucketId": "…", "key": "week-1/intro.mp4", "size": 123, "contentType": "video/mp4",
  "partSize": 8388608, "partCount": 1, "state": "open", "expiresAt": "…", "ticketExpiresAt": "…",
  "ticketTtlSeconds": 86400,
  "parts": [ { "number": 1, "size": 123, "url": "https://in-mum.upload.plycdn.com/v1/<ticket>/1" } ],
  "objectId": null }
GET    /api/content/v1/uploads/{uploadId}
DELETE /api/content/v1/uploads/{uploadId}
POST   /api/content/v1/uploads/{uploadId}/renew
POST   /api/content/v1/uploads/{uploadId}/complete

objectId is null until the upload completes, then holds the id of the object it produced — a stable reference you can keep before complete's response arrives (a retried or resumed complete call, for instance, can look the object up by it directly). GET carries received (parts already accepted) instead of parts; renew returns fresh parts, ticketExpiresAt and ticketTtlSeconds for the same session. ticketTtlSeconds (returned by service 1.8.0 and later, on create and renew only) is how long the part URLs' ticket lasts from the moment you receive the response: time the ticket by it rather than by comparing ticketExpiresAt with your own clock; complete returns the finished object (the Object shape above) instead of parts/received. Part uploads themselves go directly to https://{label}.upload.plycdn.com/v1/{ticket}/{n} — never to api.plycdn.com and never to a hostname you configure.

An organization can hold at most 1,000 open uploads at once (each sub-organization counts its own); starting one more answers plan_limit_reached (403) until one completes, is aborted or expires.

A part upload is a PUT of exactly that part's bytes, with its Content-Length declared up front (no chunked bodies), and answers 200 {"part": n, "etag": "…"}. Sending the same part again replaces it. Its failures are part-sized and none of them loses the parts already accepted:

  • upload_too_slow (408, retryable): the body stopped arriving or arrived below the minimum rate; send the part again.
  • provider_unavailable (503, retryable): the upload server is busy or storage is briefly unavailable; wait for the Retry-After header (in seconds), then send the part again.
  • invalid_content_length (400): the length is missing or not a number, or the body is chunked. part_size_mismatch (400): the declared length is not this part's size, or the bytes that arrived did not total the declared length.
  • checksum_mismatch (422): the part's bytes did not match its Content-MD5; send it again.
  • ticket_expired / ticket_invalid (401): renew the upload for fresh part URLs.

A refusal that comes before the body has been read is answered and the connection closed. That covers an expired ticket, but also a busy upload server and a body cut for being too slow, and many HTTP clients, browsers among them, report any of these as a connection reset while still sending rather than as the answer. So a reset alone does not mean the ticket expired:

  • if the part URL's ticket is at or near its end (within a minute of it, judged by how long ago you received it against ticketTtlSeconds rather than by comparing your clock with ticketExpiresAt), renew the upload once — one renewal serves every part — and send the part on the fresh URL;
  • otherwise wait at least 5 seconds, a little more at random, and send the part again on the same URL.

Renewing on every reset turns a busy moment into a stream of needless renewals; cap how many times a single upload renews because of resets. The plycdn uploaders (@plycdn/angular/storage, @plycdn/react/storage and PlycdnUploader in Plycdn.AspNetCore.Storage) do all of this for you (three reset-driven renewals per upload, then ticket_expired), and send a part that meets checksum_mismatch once more.

An upload not in the open state fails with upload_not_open; past its 7-day limit, upload_expired. While another complete (or an abort) of the same upload is running, complete and DELETE answer upload_not_open marked "retryable": true: ask again shortly and you get the finished upload. DELETE on an upload that has already completed changes nothing and answers 200 with the completed upload and its object (and an abort that finds the upload's bytes already in place finishes it the same way); on an aborted or expired upload it answers that upload as it stands. Abort therefore never removes a file that finished uploading. complete before every part has arrived fails with upload_incomplete; a total that doesn't match the declared size fails with size_mismatch; a contentType outside the bucket's uploadRules.allowedTypes fails with file_type_not_allowed. A part number outside 1..partCount fails with part_out_of_range; a part whose size doesn't match what that part number requires fails with part_size_mismatch; an invalid or expired ticket on the part URL fails with ticket_invalid or ticket_expired.

A declared sha256 is verified after complete returns — always asynchronously, never as part of that response, since hashing a multi-gigabyte upload cannot hold completion open. checksumState starts unverified and later becomes verified or, if the stored bytes don't match, mismatch, at which point the object's state becomes disabled: it stops being retrievable or servable, and its bytes are quarantined. complete itself never fails with checksum_mismatch — for a declared sha256 that code describes the outcome, not a direct response (a part upload can answer it, but only about that part's own bytes, and sending the part again fixes it) — so poll GET /objects/{objectId} or watch the audit log if your integration needs to know before serving a file that was just uploaded.

Files plycdn brings into a bucket for you (an assisted migration, arranged with us) arrive as ordinary objects, with no upload session and no sha256. They start with checksumState pending while plycdn reads each one end to end and records its sha256, then become verified; a file whose bytes changed after it was brought in becomes mismatch and disabled, like a failed upload check. The audit log records the migration as bucket.adopted (one row per run) and object.adopted (one row per batch of files, with how many and their first and last keys), with plycdn as the actor. The files are stored and billed like any other from the day they arrive; bringing them in is not counted as upload volume.

Signing

GET  /api/content/v1/buckets/{bucketId}/signing-profile
POST /api/content/v1/buckets/{bucketId}/signing-key/rotate
POST /api/content/v1/sign
// signing-profile
{ "bucketId": "…", "scheme": "pl1", "keyId": "k1", "key": "…", "hostname": "course-media.plycdn.net",
  "hostnames": ["course-media.plycdn.net", "cdn.example.com"], "defaultTtlSeconds": 900, "ipBinding": false,
  "directoryScheme": null, "pathTokens": false, "tagsEnabled": false }
// POST /sign { "bucketId": "…", "key": "week-1/intro.mp4", "ttlSeconds": 900, "ip": null, "hostname": null }
// (on a shared address, also "pathPrefix": "org-content/documents/": see Shared address routes)
{ "url": "https://course-media.plycdn.net/week-1/intro.mp4?token=…&expires=1790000000",
  "expiresAt": "…" }

scheme is "pl1" (plycdn links: used by new private buckets) or "ps2" (buckets made before, and buckets that allow credentialed cross-origin requests, see CORS); directoryScheme is "pl1d" or "ps3" on a video library and null on a files bucket. Rotating the signing key invalidates every link already issued with the old key. On a pl1 bucket this takes effect within about a minute: links signed with the new key start working, and links signed with the old key stop, within that minute, so wait a minute (or retry) before handing out links signed with the new key. On a ps2 bucket it is at once. More than 60 rotations an hour for your account (across its organizations and buckets; refused ones count) answer 429 rate_limited with Retry-After, and the key is not changed. Storage and delivery documents both schemes (an HMAC-SHA256 token), with worked examples, for anyone signing links without calling /sign. An IP-bound link must bind the viewer's IPv4 address — IP-bound delivery serves IPv4 only. On a bucket with ipBinding, ip is required and must be IPv4 (an IPv4-mapped address such as ::ffff:1.2.3.4 counts as its IPv4 form); a missing or IPv6 ip is refused with 422 validation_error, fields [["body","ip"]], and so is any ip on a private bucket without ipBinding. On a public bucket /sign answers the object's plain URL with "expiresAt": null; ip and ttlSeconds play no part. The object must be stored and in the named bucket: a disabled object, or a key or id of another bucket, is object_not_found. A rotation that answers provider_unavailable may already have changed the key at the edge; plycdn stores the edge's key within a few minutes, so fetch the signing profile again before relying on the old one. A signed link must be used exactly as issued: appending, removing or reordering query parameters invalidates it.

ttlSeconds on /sign is 60 to 604,800. hostname on /sign is optional: leave it out (or null) for the bucket's default hostname, or name one of the bucket's active custom domains (see Custom domains below). hostnames in the profile lists every hostname a link may be signed on, the default first. A hostname that is not a hostname at all (empty, an IP address, * or _, one label) is 422 validation_error with fields [["body","hostname"]]; a well-formed one that is not the bucket's is 409 domain_not_active.

Custom domains

Serve a bucket on your own hostname (cdn.example.com) as well as its default one. Administrative: call these from your server with your API key; adding and removing a domain need an admin key (admin_key_required otherwise), while listing, reading and checking work with either. Walkthrough and SDK usage: Your own domain in Storage and delivery.

Route What it does
POST /domains Add a hostname to a bucket (202). Requires Idempotency-Key.
GET /domains?bucketId=&cursor=&limit= Your domains, oldest first, 100 a page (limit 1–100); nextCursor continues. bucketId is optional.
GET /domains/{domainId} One domain: its records, checks and state.
DELETE /domains/{domainId} Remove it (204). It disappears at once; we stop serving it within minutes.
POST /domains/{domainId}/check Check now (202). A failed or detached domain starts again with a new TXT value. At most once a minute per domain.
POST /api/content/v1/domains
{ "bucketId": "2f0c…", "hostname": "cdn.example.com" }
{ "id": "7d1e…", "bucketId": "2f0c…", "hostname": "cdn.example.com", "unicodeHostname": "cdn.example.com",
  "state": "pending_dns", "failureReason": null, "apex": null,
  "records": [
    { "type": "TXT",   "name": "_plycdn.cdn.example.com", "value": "plycdn-verify=k3x7…" },
    { "type": "CNAME", "name": "cdn.example.com",         "value": "q4n2w7t5c6aa.domains.plycdn.net" } ],
  "checks": { "ownership": "missing", "routing": "missing", "claim": "unknown", "certificate": "none" },
  "lastCheckedAt": null, "nextCheckAt": "…", "activeAt": null, "createdAt": "…", "updatedAt": "…" }

GET /domains answers { "items": [ … ], "nextCursor": "…" }, nextCursor being null on the last page.

hostname is accepted in any case, with or without a trailing dot, and in Unicode or its xn-- form; it is stored and returned in lowercase xn-- form as hostname, with unicodeHostname for display (media.例え.jp is hostname media.xn--r8jz45g.jp). Every spelling of one hostname is the same domain. A hostname must have at least two labels and at most 245 characters, and cannot be an IP address or contain * or _; anything else is 422 validation_error with fields [["body","hostname"]] and a detail that says what is wrong with its form. plycdn's own hostnames and reserved names (.local, .localhost, .test, .example, .internal and the like) are 422 hostname_not_allowed. The bucket must be active (bucket_not_active) and not suspended (bucket_suspended), both for adding a domain and for checking one now. A bucket takes at most 8 domains in any state (domain_limit_reached); your plan may set a lower ceiling across your organization (plan_limit_reached). Additions are limited per account per hour and per day: 20 an hour and 100 a day across all your organizations, counting every attempt, including domains you have since deleted; beyond that, 429 domain_rate_limited with Retry-After. Deleting a domain does not give an addition back.

Records. Each record has type, name and value, and the one that is not the ownership or routing record also a purpose (what it is for, in words to show people). Create them exactly as given, at your DNS host:

  • TXT _plycdn.{hostname} proves the hostname is yours. Keep it for as long as you use the domain: we check it daily.
  • CNAME {hostname} routes it to us. It must be DNS-only: if your DNS host offers a proxy in front of the hostname, turn it off for this record, or routing shows as elsewhere.
  • For a bucket that is moving from another cloud, a third record: CNAME _acme-challenge.{hostname} with purpose "Lets us issue and renew your certificate". Create it first and the certificate is issued before you change the routing record, so your hostname moves with no gap; the domain may stay in issuing_certificate until you switch (72 hours at most before dns_not_configured). Keep it as long as you use the domain. See Moving from another cloud.

Checks. ownership is found, missing or unknown (the TXT record); routing is found, missing, elsewhere (the hostname points somewhere else) or unknown; claim is free, held_elsewhere (another account serves this hostname) or unknown; certificate is none, pending or active. unknown means DNS could not give a definite answer this time; it never changes the state on its own.

States. pending_dns (waiting for both records) → verifying (records found; attaching and routing) → issuing_certificate → active. Or failed with a failureReason, or detached when a daily check found your records gone (confirmed by a second check an hour later). nextCheckAt is when we look next: every minute for the first ten minutes, every ten minutes up to an hour, hourly after that, and daily once active. A verifying domain whose TXT record is definitely gone goes back to pending_dns (it does not fail) until the record is back. A hostname added again while its previous domain is still being removed waits in verifying; if that removal has not finished within the verification window (about an hour), the new domain fails with hostname_in_use: check it again once the old one is gone.

failureReason Meaning What to do
dns_not_configured The records were not found within 72 hours, or the hostname did not route to us within an hour of attaching. Create both records exactly as given, then POST /domains/{domainId}/check.
hostname_in_use Another account serves this hostname and your records have not replaced theirs, or you added the hostname again and its previous domain was still being removed an hour later. Point the records at the values in this domain; the other account loses the hostname at its next daily check. After a re-add, check again once the previous domain is gone.
caa_blocks_certificate Your CAA records do not allow our certificate authority. Add the CAA record shown in records, then check again.
certificate_failed No certificate within 24 hours. Make sure nothing proxies the hostname, then check again.
dns_record_removed Your CNAME (or ALIAS) no longer points at the target. Restore it and check again.
ownership_record_removed Your TXT record is gone. It must stay for as long as you use the domain. Restore it and check again.
provider_unavailable We could not complete a step. Check again.

Checking again (POST /domains/{domainId}/check) a failed or detached domain returns it to pending_dns with a new TXT value in records: replace the old TXT record with the new one. The CNAME target does not change. While we are still removing the domain from our network (shortly after it failed or was detached), checking it again answers 202 with the domain still failed or detached; it moves to pending_dns with its new TXT value on its own once the removal finishes, so read it again (GET /domains/{domainId}) some minutes later rather than checking again.

A domain that fails caa_blocks_certificate carries a third record, the one to add:

{ "type": "CAA", "name": "cdn.example.com", "value": "0 issue \"…\"" }

Its value names the certificate authority that issues certificates for custom domains; add it exactly as given. Without CAA records at all, nothing needs to be added.

Apex domains (example.com) cannot have a CNAME: use your DNS host's ALIAS, ANAME or CNAME flattening to the same target. apex is null until we have seen your zone, then true for an apex and false otherwise.

Signing on your domain. POST /sign accepts "hostname": "cdn.example.com"; it must be the bucket's default hostname or one of its active domains, otherwise 409 domain_not_active. The signing profile (GET /buckets/{bucketId}/signing-profile) lists them in hostnames, default first. A link signed on one hostname has the same token on every other: the token covers the path and expiry, not the host. A public bucket serves its files at the same path on every active hostname; an object's url stays on the default hostname.

Shared address routes

One custom domain can serve several buckets, and one video library, by path: the address works like a front door with a list of routes. Administrative, like domains: saving or restoring a table needs an admin key (admin_key_required otherwise); reading it works with either key. A step-by-step walkthrough, with the code, is Serve several buckets from one address.

Route What it does
GET /domains/{domainId}/routes The domain's route table, its version and the last 20 versions. A domain that never had a table answers version 0, defaultRoute: true and no routes.
PUT /domains/{domainId}/routes Replace the table. Optional If-Match: "<version>": if someone saved a newer one, 409 version_conflict.
POST /domains/{domainId}/routes/restore Make an earlier version current again, as a new version. Body { "version": 2 }. Optional If-Match: "<version>", as for PUT. A target deleted since is kept and shown broken.
PUT /api/content/v1/domains/7d1e…/routes
If-Match: "2"
{ "defaultRoute": true,
  "routes": [
    { "pathPrefix": "org-content/videos/",    "bucketId": "2f0c…", "stripPrefix": false },
    { "pathPrefix": "org-content/documents/", "bucketId": "81aa…", "stripPrefix": true },
    { "pathPrefix": null,                     "bucketId": "c4d9…" } ] }
{ "domainId": "7d1e…", "hostname": "cdn.example.com", "defaultRoute": true,
  "routes": [
    { "pathPrefix": "org-content/videos/",    "bucketId": "2f0c…", "stripPrefix": false, "status": "ok" },
    { "pathPrefix": "org-content/documents/", "bucketId": "81aa…", "stripPrefix": true,  "status": "ok" },
    { "pathPrefix": null,                     "bucketId": "c4d9…", "stripPrefix": false, "status": "ok" } ],
  "version": 3, "updatedAt": "…",
  "versions": [ { "version": 3, "changedAt": "…" }, { "version": 2, "changedAt": "…" } ] }
  • Routes. Up to 50 per address (route_too_many). A bucket route has a pathPrefix of whole folders ending in /, such as org-content/videos/: 2 to 256 characters, no . or .. folder, no //, \, %, ? or #, and no folder that starts with .plycdn- (route_prefix_invalid). A bucket route's prefix cannot start with v/ or _s/: those paths belong to the video library route (route_prefix_reserved). Two routes cannot share a prefix (route_prefix_duplicate); one prefix may sit inside another, and the longest match wins.
  • A video library route has pathPrefix: null and owns /v/ and /_s/ on the address. At most one per address (route_video_twice).
  • Targets are buckets and video libraries of your organization and its sub-organizations. A target that is not yours is 404 route_target_not_found, and one you may not reach with this key is 403 route_target_scope.
  • Redirect rules. { "kind": "redirect", "pathPrefix": "old-docs/", "location": "https://www.example.com/docs/", "permanent": true, "keepPath": true, "keepQuery": true }. pathPrefix is a folder ending in /, or "" for the whole address (which also redirects the player (/v/) and share (/_s/) addresses). location is an absolute https:// or http:// address of at most 2,048 characters, with no credentials or # part. permanent sends 301 (302 when false; 308 or 307 for requests other than GET and HEAD); keepPath adds the rest of the path after the prefix to location; keepQuery keeps the viewer's query. Redirects are checked before the rules that send to buckets, longest prefix first, and an OPTIONS request on a redirected path gets the redirect. A redirect that leads back into itself is route_redirect_loop; a bad location or prefix is route_redirect_invalid.
  • Several buckets in one rule. A forward rule has bucketId or targets ([{ "bucketId": "…", "share": 70 }, …]): 1 to 5 different buckets, share a relative weight, a whole number from 1 to 100 (70 and 30 split viewers 7 to 3, exactly as 7 and 3 do; they need not add up to 100), all public or all private, and a video library rule has one library alone (route_targets_invalid). Both together is route_bucket_and_targets. A viewer is sent to one bucket for every file under the rule (per address, prefix and viewer). When it cannot answer, a GET or HEAD request is tried on the next bucket before any byte is sent: at most 3 tries, about 8 seconds each and 25 seconds in all; with every bucket down viewers get 503 with Retry-After: 30. Answers carry kind, and every forward rule carries targets with each bucket's share and status (ok, paused when the bucket cannot serve now, or its visibility no longer matches the rule's, and it is skipped, or broken); a rule saved with bucketId is answered as one target with share 100. A link on a rule with several buckets is checked with the first bucket's link key and access settings: the signing profile of every bucket of the rule lists the route with signWith (the first bucket) and signWithOrganization (its organization) when that bucket is in the same organization, or when you ask as the main account; a sub-organization never sees another organization's bucket or organization there, so links on a rule whose first bucket belongs to another organization are signed by that organization (or the main account). The server packages sign with it for you; POST /sign on any bucket of the rule signs with the first bucket when the buckets are in the same organization (otherwise sign through the first bucket's organization), and a link you sign yourself with another bucket's key is refused with 403. A paused first bucket still accepts its links while the others serve. Step by step: Redirect a path and Share traffic between buckets.
  • stripPrefix (default false). false: the bucket sees the whole path, prefix included, so /org-content/videos/a.mp4 is the key org-content/videos/a.mp4. true: it sees what follows the prefix, so the same address is the key a.mp4.
  • defaultRoute (default true): paths no route matches are served from the domain's own bucket. false answers them with a plain not-found page.
  • status is ok, or broken when a target was deleted: its prefix then falls to the default route, or to not-found, until you change the route.
  • Private address. The domain's own bucket must be private: a public bucket's domain is served directly and cannot carry routes (409 routes_need_private_address). Routes may point at public buckets.
  • Timing. A saved table is live within about a minute. No DNS or certificate change is needed, and a domain that already serves traffic can get routes later.
  • Links. A plycdn link on a shared address is signed over the full path the viewer sees, prefix included (see Serve several buckets from one address); a link for one route does not work under another. Links to a public bucket's route need no signature.
  • Signing profile. The signing profile of every bucket or library a route points at lists the address in routes (only when there are some): [{ "hostname": "cdn.example.com", "pathPrefix": "org-content/documents/", "stripPrefix": true }], one entry per route, with pathPrefix: null for the video library route. The address is not added to hostnames. Saving or restoring a table sends signing_profile.changed (reason domains_changed) for every bucket and library it adds or removes, so the server packages refresh their kept profiles.
  • POST /sign on the address. Give "hostname" the address. For a route that removes its prefix, also give "pathPrefix" (the route's prefix) and the key as stored: the link is https://<address>/<pathPrefix><key>. For a route that keeps its prefix, give the key as stored (it starts with the prefix) and no pathPrefix. A prefix the route keeps, or a missing prefix on a route that removes it, is 422 validation_error with fields [["body","pathPrefix"]]; an address with no route to this bucket is 409 domain_not_active. pathPrefix goes with a file's key or objectId only, never with videoId or liveInputId. A video library route's address signs a video's links with hostname alone.
  • Versions. Every save is a new version; the last 20 are kept. Each save is in the audit log as domain.routes_changed, with the table before and after.

Move from another cloud

Step by step, with the code in every server package: Moving from another cloud. Bring a bucket's files over from another cloud (Azure Blob, an S3-compatible bucket or a plain HTTPS origin) without downtime. Once a move is started, a file that is asked for and is not here yet is read from the old cloud, served and kept; the rest is copied in the background. One live move per bucket. Administrative: call these from your server with your API key. Setting up, changing, checking, pausing, resuming, switching off old links and closing need an admin key (admin_key_required otherwise); reading the move, its keys and its link usage work with either.

Route What it does
PUT /buckets/{bucketId}/migration Set up the move (201): kind (azure_blob, s3 or https), endpoint, container, prefix, credential (read-only: a container SAS granting only read and list, or for s3 a JSON text {"accessKeyId", "secretAccessKey", "region"} with region optional; an https source takes none), legacyLinks (off or azure_sas), legacyContainerInPath and legacyPathPrefixes (up to 10 fixed paths a gateway put in front of old links, such as org-content/videos/: a link that starts with one is read as the file that follows it in the container; other links as before). legacyLinks: "azure_sas" needs a private bucket with plycdn links (old_links_need_private_bucket otherwise) and an endpoint of the form https://<account>.blob.core.windows.net (migration_source_unreachable otherwise); an old link's file in the old container is prefix followed by the key. The credential is stored sealed and never shown again. Needs an Idempotency-Key header (idempotency_key_required without one); the server SDKs send one for you.
GET /migrations?state=&attention=&bucket=&limit=&cursor= Every move of your organization on one list: one row per bucket that has had a move (its live move, else its latest closed one), by bucket name. Each row is the same object as GET /buckets/{bucketId}/migration plus bucketName and lastOldLinkAt (when a link signed by the old cloud last arrived, or null). state is draft, checking, serving, sweeping, paused, complete or closed; attention is failed (a file failed), unmovable (a file cannot move), old_links (an old link arrived in the last 7 days) or credential_expiring (not closed and the read-only key expires within 14 days or already has); bucket is part of the bucket name (any case, at most 63 characters); limit is 1-100 (50 by default); cursor is the previous nextCursor. A value that is not allowed is 422 validation_error, naming the parameter. The answer has migrations, totals (all your moves, whatever the filters and page: buckets, byState, failed, unmovable, oldLinks, credentialExpiring; a state with none is left out of byState) and nextCursor (null on the last page). Never the key. Works with either key.
GET /buckets/{bucketId}/migration The move: source (never the credential, only credentialSet and credentialExpiresAt), state, legacyLinks, writesMovedAt, sweepConcurrency and progress (copiedObjects, copiedBytes, pending, copying, failed, unmovable, goneAtSource). After it is closed, the last one is still readable.
PATCH /buckets/{bucketId}/migration Change credential (a new read-only key, for example when the old one expires), legacyLinks, legacyLinksUntil (an optional date after which old links stop by themselves), writesMoved (true once your application writes new files to plycdn), sweepConcurrency (1 to 256) or legacyPathPrefixes (replaces the list; [] removes it). A field left out is unchanged. The source itself (kind, endpoint, container, prefix) cannot be changed: close the move and start a new one. It never moves the state: use check, pause, resume, switch-off-old-links and close for that.
POST /buckets/{bucketId}/migration/check Try the source now. Answers { "ok", "listing", "sampleKey", "unmovableSample": [{ "key", "reason" }], "state" }: whether the source can be listed, one key from it, and up to 20 keys of its first page that cannot be moved (invalid_key or reserved_key). With { "start": true } a good check also starts serving from the source (a draft move only; otherwise migration_state_conflict).
POST /buckets/{bucketId}/migration/pause Pause the background copy. A file asked for that is not here yet is still read from the old cloud and served, so your address keeps working.
POST /buckets/{bucketId}/migration/resume Continue from where it was paused.
POST /buckets/{bucketId}/migration/switch-off-old-links Refuse links signed by the old cloud from now on.
POST /buckets/{bucketId}/migration/close End the move: the old cloud is no longer read, old links stop and the stored credential is deleted. Allowed from draft, serving, paused and complete. Body { "confirm": true } is needed while keys we could not move (unmovable or failed) exist, and to close a move that is serving or paused (keys not copied yet then stop being served); migration_not_closable otherwise.
GET /buckets/{bucketId}/migration/items?state=&cursor=&limit= The keys the move found, by key, 100 a page (limit 1-100); state is pending, copying, copied, failed, unmovable or gone_at_source; each item has key, state, reason, size, attempts and updatedAt. nextCursor continues, null on the last page.
GET /buckets/{bucketId}/migration/link-usage?from=&to= Which kinds of link reached the bucket per day (days: day, kind, outcome, requests), which sites still send old links (sites: refererHost, requests, lastSeen) lastOldLinkAt, and coveredSince (when recording began without a gap, or null while usage is not being recorded: "none arrived" only means something from that day on). Dates are YYYY-MM-DD, at most 93 days, the last 30 by default.

Only a file bucket can move: a video library is refused with bucket_not_supported (422). The same codes come back from every call here: migration_not_found (404), migration_already_running, migration_state_conflict, migration_not_closable and bucket_not_ready (409), migration_source_unreachable, migration_credential_refused, migration_credential_too_broad and old_links_need_private_bucket (422), each with its fix in the table of error codes below.

A move's state is draft (set up, nothing served), checking (for a moment, while a check runs), serving (files are read from the old cloud on demand and the rest is copied in the background), complete (every file that can move has moved; keys that could not move are still served from the old cloud until you close), paused (the background copy waits; files are still served from the old cloud) or closed. A move becomes complete by itself once writesMoved is set and a full listing of the old cloud that began after it finds nothing left to copy. A move from an https source has no listing and never completes by itself: close it with { "confirm": true }.

An item's reason, when its state is unmovable or failed:

reason Meaning
invalid_key The key cannot be a plycdn key (over 1,024 bytes, an empty folder name such as //, a . or .. folder, a backslash, a control or text-direction character). Rename it at the source.
reserved_key The key is in plycdn's reserved space. Rename it at the source.
too_large The file is larger than the bucket's upload ceiling.
type_not_allowed The bucket's upload rules do not allow this file type.
content_not_allowed The file's content does not match an allowed type.
unsafe_content_type The file would be served in a way that can run scripts; plycdn will not serve it from your domain.
source_changed The file changed at the source while it was being copied; it is tried again.
source_unreadable The old cloud refused or failed to give the file after every attempt.
deleted_by_customer You deleted the file in plycdn, so it is not copied back.

Usage by resource

GET /api/content/v1/usage/resources?from=2026-09-01&to=2026-09-30&metric=delivery_gb&bucketId=…&cursor=…&limit=200
{ "items": [ { "resourceId": "…", "resourceName": "course-media", "metric": "delivery_gb",
               "day": "2026-09-01", "dimension": "india-asia", "quantity": 1.25, "unit": "GB",
               "provisional": false } ],
  "nextCursor": "…" }

A paged, per-bucket, per-day breakdown of the storage metrics (storage_gb_days, delivery_gb, requests_millions, upload_gb, and custom_domain_days, one per active custom domain of the bucket that day, invoiced as Custom domains in domain-months — see Storage and delivery for units and how each is measured), of encoding_minutes (unit minutes) against the video library that holds each video (see Videos), of live streaming's live_source_minutes, live_sd_minutes, live_hd_minutes, live_fhd_minutes, live_realtime_viewer_minutes and live_caption_minutes (unit minutes; see Live usage), and of the storage API's gateway_egress_gb, gateway_write_requests_millions and gateway_read_requests_millions (S3 and Azure tools; see Usage and pricing in S3 and Azure compatibility). from and to are UTC days, both counted, so a range spans at most 93 days — UTC days, except that storage_gb_days and custom_domain_days are measured on your account's own calendar day; leave out metric for all of them. dimension is the region (mumbai) for storage, uploads, encoding minutes and the storage API, and the region group (india-asia) for delivery. Storage API requests that name no bucket (listing buckets or containers, for example) are reported with your organization's ID as resourceId and "resourceName": null; a storage API day stays provisional until it settles after the UTC day ends. Days with nothing to report have no row. limit is 1–5000 (500 when omitted). cursor is a keyset cursor: follow it until the response carries none, rather than assuming a page count. The last three days of delivery figures are provisional ("provisional": true) until settlement; a settled figure is final and is what your invoices bill. A figure that settles after its month's invoice was closed is shown on the day it happened and billed on a later invoice, as late usage (see Late usage lines); so is a video that becomes ready after its month was closed.

Cache and CORS settings

Two more sections of the bucket body, on POST /buckets and PATCH /buckets/{bucketId}, and in every bucket response (defaults filled in). Caching and CORS in Storage and delivery explain them with examples.

PATCH /api/content/v1/buckets/{bucketId}
{ "cache": { "edgeTtlSeconds": 86400, "browserCacheControl": "public, max-age=3600",
             "rules": [ { "pathPrefix": "video/", "edgeTtlSeconds": 31536000,
                          "browserCacheControl": "public, max-age=31536000, immutable" },
                        { "extensions": ["m3u8"], "edgeTtlSeconds": 5, "browserCacheControl": "no-cache" } ] },
  "cors": { "allowedOrigins": ["https://learn.example.com"], "allowedMethods": ["GET", "HEAD"],
            "maxAgeSeconds": 3600, "allowCredentials": false } }

cache:

Field Values null / not set
edgeTtlSeconds 0–31,536,000 seconds the edge keeps a copy; 0 keeps none plycdn's default
browserCacheControl a Cache-Control value of public, private, no-cache, no-store, must-revalidate, proxy-revalidate, immutable, no-transform, max-age=, s-maxage=, stale-while-revalidate=, stale-if-error= (0–31,536,000); each once, at most 200 characters; not public with private, not no-store with max-age/s-maxage. Returned lower case, , -joined plycdn's default header
rules at most 20, first match wins; replaced as a whole when sent []

A rule is {"pathPrefix": "…"} (a key prefix, following the same rules as a purge prefix below) or {"extensions": ["…"]} (1–20 of 1–16 lower-case letters or digits, without the dot; a leading dot is dropped and case folded), plus edgeTtlSeconds, browserCacheControl or both. A value a rule leaves out comes from the bucket level; a request no rule matches uses the bucket level.

cors:

Field Values null / not set
allowedOrigins 1–20 exact origins https://host[:port] (http:// only for localhost and 127.0.0.1), no path, trailing /, userinfo or wildcard label; or exactly ["*"]. Returned lower case, default port dropped, internationalised hosts as xn-- []: CORS off
allowedMethods GET, HEAD ["GET", "HEAD"]
allowedHeaders ≤ 20 HTTP token names, lower case; or exactly ["*"] []
exposeHeaders ≤ 20 HTTP token names, lower case; or exactly ["*"] []
maxAgeSeconds 0–86,400 600
allowCredentials true / false; null refused false

Whenever allowedOrigins is set, delivery also always allows the request header range and exposes content-range, accept-ranges and content-length, after your own lists (* stays *). They are not added to the stored settings: cors reads back exactly as you set it.

Refused with 422 validation_error: duplicates, * mixed with other entries, any other method, and allowCredentials: true with * as the origin, the allowed headers or the exposed headers. That last rule is judged on the settings the bucket would have after the change, so a PATCH turning credentials on while * is stored is refused with fields [["body","cors","allowCredentials"]] and a detail. A bucket that allows credentials keeps the earlier link scheme (ps2); plycdn links (pl1) don't yet serve credentialed requests from another origin. A bucket made with allowCredentials: true is therefore a ps2 bucket, and a PATCH turning credentials on for a bucket with plycdn links is refused with the same fields and a detail that says to use a separate bucket; see CORS. CORS settings other than origins, saved while no origins are set, are kept and apply once origins are added. CORS decides which pages' scripts may read a response; it never decides who is served.

A change to either section is a delivery-settings change: applied at the edge shortly after, with configuration_failed as for any other (see Buckets). Copies already at the edge keep the lifetime they were cached with until they expire or are purged.

Cache purges

POST /api/content/v1/buckets/{bucketId}/purges   # 202
{ "urls": ["https://course-media.plycdn.net/week-1/intro.mp4"] }

The body is exactly one of {"urls": [...]} (1–100 absolute https:// URLs, each at most 4,096 characters, on the bucket's default hostname or one of its active custom domains), {"prefixes": [...]} (1–20 key prefixes: no leading /, 1–1,024 bytes, no control or invisible characters, no \, no //, no . or .. segment such as ./a/ or a/../b/, not in the reserved .plycdn- space in any case or spelling, and not a beginning of it in any case — ., .p up to .plycdn; a cache rule's pathPrefix follows the same rule) or {"all": true}; anything else is 422 validation_error. A URL on any other host (another bucket's, a custom domain that is not active, or with a port or userinfo) is 422 purge_url_not_in_bucket. A URL's query and fragment are ignored — a purge covers every cached variant of the path — and duplicates are merged.

{ "id": "…", "bucketId": "…", "bucketName": "course-media", "scope": "urls",
  "targets": ["week-1/intro.mp4"], "state": "queued", "failureReason": null,
  "requestedBy": "api_key:…", "createdAt": "…", "startedAt": null, "completedAt": null }
GET  /api/content/v1/purges?bucketId=…&cursor=…&limit=50
GET  /api/content/v1/purges/{purgeId}

The listing answers {"items": [ purge, … ], "nextCursor": "…" | null}, newest first, optionally for one bucket; limit is 1–200 (50 when omitted). An unknown purge id, or another organization's, is 404 purge_not_found.

  • scope: urls, prefixes or all. targets: the object paths or prefixes, percent-encoded as in a URL, without the leading / ([] for all).
  • state: queued → running → succeeded or failed. A purge made right after a change to the bucket's settings stays queued until that change has reached the edge (a few minutes at most), so nothing is cached again under the old settings. failureReason is null unless failed: purge_failed (the edge did not complete it after every attempt; purge again) or bucket_not_active (the bucket was deleted before the purge ran).
  • requestedBy: api_key:<id> or user:<id>.

The bucket must be active (409 bucket_not_active otherwise, retryable while creating); a bucket plycdn has taken down ("suspended": true) can still be purged. Purges are free. Per account, at most 60 purge requests an hour, and at most 10 of them with all; past either, 429 rate_limited with Retry-After. Every request with a valid body counts, including one then refused. Each request writes one cache.purged audit entry (resourceKind bucket, detail {outcome, purgeId, scope, count}), or a refused one with its code.

Delivery analytics

GET /api/content/v1/delivery/analytics?from=2026-09-01&to=2026-09-27&bucketId=…
{ "from": "2026-09-01", "to": "2026-09-27", "bucketId": null,
  "totals": { "gb": 12.345678, "requests": 1234567 },
  "days": [ { "day": "2026-09-01", "gb": 0.5, "requests": 1200, "provisional": false,
              "regionGroups": { "india-asia": { "gb": 0.4, "requests": 1000 },
                                "europe-north-america": { "gb": 0.1, "requests": 200 },
                                "latin-america": { "gb": 0.0, "requests": 0 },
                                "middle-east-africa": { "gb": 0.0, "requests": 0 } } } ],
  "regionGroups": [ { "regionGroup": "india-asia", "label": "India & Asia", "gb": 10.1, "requests": 1000000 } ],
  "buckets": [ { "bucketId": "…", "bucketName": "course-media", "gb": 12.3, "requests": 1234567 } ] }

from and to are required UTC days, both counted, so a range spans at most 93 days; a longer range or to before from is 422 validation_error. Every day of the range is listed, zero-filled. gb is GB of 2³⁰ bytes to 6 decimals; requests a whole number. regionGroups always lists the four region groups (india-asia, europe-north-america, latin-america, middle-east-africa) in that order, with their labels. Without bucketId, buckets lists up to 100 of your organization's buckets, largest first (a deleted bucket keeps its name); with it, buckets is [], and a bucket your organization never had is 404 bucket_not_found. provisional is true on a day with any figure not yet settled (the last three days or so, as in Usage by resource); settled days are final. The figures are the same metering data as delivery_gb and requests_millions in usage, in bandwidth and requests only. There is no breakdown by HTTP status code: it is not collected.

Traffic analytics

The daily figures above need nothing switched on. For breakdowns by the labels you choose, switch analytics on for a bucket or video library (the Storage guide explains it with examples). It is on every plan; there is no plan gate. These routes need an admin key and read the organization named in X-Organization-Id; an account (the parent organization) also sees its sub-organizations when it groups by organization or names a sub-organization's bucket.

The analytics section of a bucket or library, on PATCH /buckets/{bucketId} and PATCH /libraries/{libraryId} and in every response:

PATCH /api/content/v1/buckets/{bucketId}
{ "analytics": { "enabled": true, "ceiling": 50000,
                 "dimensions": [ { "name": "course", "type": "pathSegment", "index": 1 },
                                 { "name": "customer", "type": "tag", "tag": "customer" },
                                 { "name": "campaign", "type": "queryParam", "param": "campaign" },
                                 { "name": "folder", "type": "pattern", "pattern": "^/([a-z0-9-]+)/" } ] } }
{ "analytics": { "enabled": true, "dimensions": [ … ], "ceiling": 50000, "effectiveCeiling": 50000,
                 "since": "2026-10-02T14:00:00+00:00" } }
Field Values Not set / null
enabled true / false; null refused. Counting starts at the next full hour after it is switched on false
dimensions Up to 3 rules, replaced as a whole when sent; [] removes them; null refused []
ceiling 100 to 10,000,000 distinct values per breakdown per bucket per day; null returns to your plan's your plan's

A rule is name (a lower-case letter, then lower-case letters, digits and underscores, 32 characters at most, unique in the bucket, not organization or bucket) and type with the one field it uses: pathSegment with index (1 to 8), queryParam with param (1 to 64 letters, digits, _, ., -), tag with tag (a tag name), or pattern with pattern (a regular expression of at most 200 characters with exactly one capture group). It is searched for in the path after the path is decoded once (%20 is a space), reading at most its first 2,048 bytes (so an expression anchored with $ can miss on a very long path). Plain expressions only: look-ahead, look-behind and back-references are refused. A rule with another type's field, a bad name or a bad value is 422 validation_error with fields naming it; more than 3 rules names ["body","analytics","dimensions"]. A value is cut to 128 bytes. effectiveCeiling is the figure in force (the plan's: Starter 1,000, Growth 10,000, Enterprise 100,000, unless you set one) and since is the hour counting (re)started: in the future until that hour arrives, and moved each time you switch analytics off and on (null until first switched on). Changes apply to hours counted afterwards.

Values. A request with nothing to read has the value (none); a tag that fails its check, (unverified); and when a breakdown has more distinct values in a day than its ceiling, the rest are added together as other. They are ordinary rows in every answer below.

Signed-link tags. POST /sign takes "tags": { "customer": "acme" } (at most 8; name as a rule's tag; value 1 to 128 bytes, no control characters and none of &, =, ?, #) and returns the link carrying them, once link tags are enabled for your account (the signing profile's tagsEnabled). Tags are for private buckets and never on video playback links. A refused tag is 422 validation_error with fields ["body","tags"] (or ["body","tags",<tag name>] for one tag) and a detail sentence saying which rule: tags need a private bucket, tags are not available on video playback links, link tags are not available yet, a link carries at most 8 tags, a tag name is invalid, or a tag value is invalid (as for a custom domain's hostname, detail states the rule and never repeats the value). Public links label traffic with a query parameter and a queryParam rule instead.

GET /api/content/v1/analytics/delivery?from=2026-09-01&to=2026-09-27&bucketId=…&dimension=customer&groupBy=value&top=10
Parameter Meaning
from, to UTC days, both counted. Up to 403 days (13 months); longer or to before from is 422 validation_error
bucketId One bucket or library. Without it, every bucket of the organization (and, for an account, see below). A bucket you never had is 404 bucket_not_found; a deleted bucket's history stays readable
dimension One of the bucket's breakdowns by name. Left out: the totals
groupBy value (the breakdown's values; default), bucket, or organization
top 1 to 50 (10 when omitted): the largest series are kept, the rest are added together as other
{ "from": "2026-09-01", "to": "2026-09-27", "resolution": "day", "timezone": "UTC",
  "bucketId": "…", "dimension": "customer", "groupBy": "value",
  "series": [ { "key": "acme",
                "points": [ [1788220800, 5120000, 41, 30, 11, 40, 0, 1, 0], … ] },
              { "key": "other", "points": [ … ] } ],
  "totals": { "bytes": 1234567890, "requests": 9876, "cacheHits": 8000, "cacheMisses": 1876,
              "status": { "2xx": 9800, "3xx": 20, "4xx": 50, "5xx": 6 } },
  "topCountries": [ { "country": "IN", "requests": 6000 } ],
  "notices": [ { "kind": "ceiling_reached", "organization": "…", "dimension": "customer",
                 "from": "2026-09-10T00:00:00+00:00", "to": "2026-09-12T00:00:00+00:00" } ],
  "provisional": false }
  • Points are columnar. Each point is a flat list: [epochSeconds, bytes, requests, cacheHits, cacheMisses, status2xx, status3xx, status4xx, status5xx], epochSeconds being the start of the hour, day or month (UTC). Every series has a point for every time step of the range, zero where nothing was served.
  • resolution is hour for a range of up to 14 days, day up to 400 days, and month beyond that.
  • Without a dimension and with groupBy=value, the one series has the key total.
  • groupBy=bucket series have a label with the bucket's name; groupBy=organization has one series per organization (account only). other is always last.
  • topCountries is the ten countries with the most requests, as {country, requests}.
  • provisional is true while any figure in the range can still change (the most recent hours). Read the range again later.
  • notices (at most 200) each have kind, organization, dimension, from and to: ceiling_reached (values were grouped as other, for that breakdown, those days), hours_missing (hours that could not be counted yet or at all) and logging_disabled (hours when analytics was off, with dimension null).
GET /api/content/v1/analytics/delivery/breakdown?month=2026-09&by=dimension&dimension=customer&bucketId=…&format=json

One UTC calendar month. by is organization (the default: one row per organization and bucket) or dimension (one row per value of the breakdown named by dimension, which is then required, and always including other and (none) rows even when zero). Largest first. With by=organization, dimension and value are empty strings.

{ "month": "2026-09", "by": "dimension", "timezone": "UTC", "bucketId": "…", "dimension": "customer",
  "rows": [ { "organization": "…", "bucketId": "…", "bucket": "course-media", "dimension": "customer",
              "value": "acme", "bytes": 5120000, "requests": 41, "cacheHits": 30, "cacheMisses": 11 } ],
  "provisional": false }
  • JSON holds at most 50,000 rows; a month with more is 422 too_many_rows: ask for format=csv.
  • format=csv downloads delivery-<month>.csv with the columns organization, bucket, dimension, value, bytes, requests, cache_hits, cache_misses, up to 1,000,000 rows (more is too_many_rows). A cell that begins with =, +, - or @ (or their full-width forms, or a tab or return), even after spaces, is written with a leading apostrophe so a spreadsheet shows text; strip it if you read the file with a program. A plain -5 is written '-5. One download at a time per account, and the service allows only a few at once overall; a download refused for either reason is 429 export_busy (retryable, Retry-After 5 seconds): wait and ask again. If a download stops early, request it again.
  • Accounts. The parent organization's groupBy=organization and by=organization read every organization that has a bucket under the account (one row per organization and bucket in the month); naming a sub-organization's bucketId reads that organization. For an account, either of those (and any read naming a bucketId) is 422 too_many_organizations when more than 500 organizations have buckets under it. Read one sub-organization at a time by sending its id as X-Organization-Id (it sees only itself), or read your own organization without bucketId.
POST /api/content/v1/buckets/{bucketId}/analytics/preview
{ "rule": { "name": "course", "type": "pathSegment", "index": 1 } }
{ "sampleSize": 2000, "distinctValues": 14, "basis": "traffic", "note": null,
  "examples": [ { "value": "cs101", "count": 640 } ],
  "estimatedValuesPerMonth": 14, "estimatedMonthlyPrice": { "currency": "INR", "amount": "…" } }

Tries one rule on the bucket's recent requests, or on its file names when it has had no traffic (basis: "files"), and changes nothing. examples are the commonest values (at most 10). estimatedValuesPerMonth is at least that many a month, and estimatedMonthlyPrice is the list price of that many tracked values in your account's currency (null when none is set). note says why a preview is limited: a tag rule cannot be previewed from recent traffic (tags are not kept in it), and tag and queryParam rules cannot be tried on file names. Needs the bucket (404 bucket_not_found) and a valid rule (422 validation_error).

If the figures cannot be read at that moment, any of these routes answers 503 analytics_unavailable (retryable): try again shortly. Your delivery is never affected.

What is kept. Individual requests only for a few days; hourly and daily totals by breakdown value for 13 months. Analytics adds two lines to your statement on every plan, Requests analysed (each 100,000 requests) and Tracked values (each 100 distinct values per bucket per month), at the prices on your price list; see Plans and prices.

Audit

GET /api/content/v1/audit?from=2026-09-01&to=2026-09-30&action=bucket.deleted&resourceId=…&cursor=…
{ "items": [ { "at": "…", "actor": "user:…", "action": "bucket.deleted", "resourceKind": "bucket",
               "resourceId": "…", "detail": {}, "ip": "203.0.113.7" } ], "nextCursor": null }

Newest first. from and to are UTC days, both inclusive; limit is 1–500 (100 when omitted). actor is user:<id> for a dashboard user, api_key:<id> for a key, or plycdn for plycdn itself (provisioning, purges, checksum checks, domain checks, takedowns and migrations). Settings changes, key rotations, upload completions, deletions, cache purge requests (cache.purged) and takedowns (takedown.object, takedown.bucket, takedown.reinstated; for a video, video.disabled and video.reinstated) are all recorded here, and so are files plycdn brings into a bucket for you (bucket.adopted, object.adopted) and every custom domain's life (resourceKind domain): domain.added, domain.check_requested, domain.verified, domain.active, domain.failed, domain.detached, domain.deleted and domain.released (when we have stopped serving a deleted domain). Live streaming's changes are recorded too (resourceKind live_input or live_destination), among them live.destination_created, live.destination_updated, live.destination_deleted and live.break_inserted; a destination's key and an address are never in an entry. Saving a selection as a collection is recorded as collection.created (resourceKind collection, detail {documents}). Reads through a signed or public link are counted in usage, not logged per view.

Request log

GET /api/content/v1/storage/requests?from=2026-10-27T09:00:00Z&to=2026-10-27T10:00:00Z&bucket=photos&status=error&limit=100

Every request to your S3 and Azure storage endpoints, refused ones included. Newest first. Any key works (standard or admin); for a sub-organization add X-Organization-Id. All parameters are optional:

Parameter Meaning
from, to Time range, ISO 8601 with a zone (Z or an offset). from is inclusive, to exclusive. Default: the last hour. Earlier than the retention is cut to what is kept
bucket Bucket name
credential Storage credential id
accessKey S3 access key ID
account Azure account name
operation Exact operation: GetObject, Put Blob, Unknown
status 2xx, 3xx, 4xx, 5xx, error (400 and above) or an exact status such as 403
code Exact error code, as shown on the row, for example signature_invalid
requestId One request's ID
keyPrefix File name prefix
clientIp The address the request came from: one IPv4 or IPv6 address, such as 203.0.113.7
organization One organization of your account (an account reads all of its organizations without it; a sub-organization reads only itself)
cursor nextCursor of the previous page. It marks where the next page starts and isn't tied to the filters, so send the same filters with it
limit 1 to 500; 100 when omitted
{ "items": [ { "time": "2026-10-27T10:00:00.123Z", "protocol": "s3", "method": "GET", "operation": "GetObject",
               "status": 200, "code": "", "bucket": "photos", "key": "2026/a.jpg", "bytesIn": 0, "bytesOut": 1024,
               "durationMs": 12, "requestId": "…", "credentialId": "…", "accessKeyId": "PLY…", "account": "",
               "organizationId": "…", "region": "mumbai", "aborted": false, "clientIp": "203.0.113.7" } ],
  "nextCursor": null, "retentionDays": 30 }

credentialId is null when a refused request doesn't name one credential (an Azure request while the account has more than one key); code, accessKeyId and account are empty when they do not apply. A request whose access key ID or account name isn't yours (a mistyped key ID, for example) isn't in your log. clientIp is the address the request came from (IPv4 or IPv6), or null for requests logged before addresses were recorded. aborted is true when the caller hung up before the answer was complete. retentionDays is how far back the log reaches: 30 by default; plycdn can extend it for your account up to 365 days (contact us). Secrets, signatures, SAS tokens, query strings and file contents are never recorded. The log is not billed and does not count toward observability volumes.

Errors: 422 validation_error (a time without a zone, to before from, limit outside 1 to 500, a malformed filter or a malformed cursor), 404 sub_organization_not_found (an organization that is not yours), 400 query_timeout or query_too_expensive (narrow the range or add a bucket or access key) and 503 request_log_unavailable (retryable; try again in a minute). Dashboard: Storage → Request log. Step by step: Check that requests reach plycdn.

Storage credentials

Keys for S3 and Azure tools (S3 and Azure compatibility). Like API keys, they are managed by people in the dashboard only (Developers → Storage credentials). Listing answers 403 dashboard_session_required to every API key. Create, rotate and revoke answer 403 admin_key_required to a standard key and 403 dashboard_session_required to an admin key. No SDK has a method for them. They are documented so you know what the dashboard does and what it returns.

GET    /api/content/v1/storage-credentials
POST   /api/content/v1/storage-credentials                            # 201
POST   /api/content/v1/storage-credentials/{credentialId}/rotate
DELETE /api/content/v1/storage-credentials/{credentialId}
// POST body
{ "name": "nightly backup", "kind": "s3", "permissions": ["read", "write"],
  "bucketIds": ["…"], "expiresAt": null }
// A credential
{ "id": "…", "name": "nightly backup", "kind": "s3", "accessKeyId": "PLYEXAMPLEKEYID23456",
  "slot": null, "secretHint": "…abcd", "permissions": ["read", "write"], "bucketIds": ["…"],
  "state": "active", "expiresAt": null, "createdBy": "user:…", "createdAt": "…",
  "lastUsedAt": null, "revokedAt": null }

kind is s3 or azure. An S3 credential has an accessKeyId; an Azure one has a slot (1 or 2, Azure's key1 and key2) and needs the storage account to exist first (storage_account_not_found). permissions are any of read, write, delete and manage. bucketIds is null for every bucket of the organization, including later ones, or up to 100 of its buckets (another organization's bucket is bucket_not_found); manage is allowed only with null (validation_error otherwise). expiresAt is null (no expiry) or a future time with its timezone offset (2027-01-31T00:00:00Z, 2027-01-31T00:00:00+05:30); a time without an offset, or one in the past, is validation_error. state is active or revoked; once expiresAt has passed, the credential is refused on every request although its state stays active.

Creating and rotating add "secret" to the response: the secret access key (S3) or account key (Azure), shown this once and never again. rotate creates a second credential with the same name, permissions and buckets (an Azure key goes into the other slot) and leaves the old one working until you revoke it; DELETE revokes it (every new request signed with it is refused within 30 seconds), and revoking a revoked credential changes nothing. At most 20 credentials can be active per organization, and an Azure account holds two keys at a time (credential_limit_reached); revoked and expired credentials do not count. An unknown id, another organization's, or rotating a revoked or expired one is credential_not_found.

Storage account

Your organization's name and home region for Azure tools (S3 and Azure compatibility). The account is configuration, not a credential, so it is also available from your backend (GetStorageAccountAsync, CreateStorageAccountAsync, UpdateStorageAccountAsync in Plycdn.AspNetCore.Storage). Creating it and changing it need an admin key (admin_key_required otherwise); reading it works with either key.

GET   /api/content/v1/storage-account
POST  /api/content/v1/storage-account            # 201
{ "name": "acmelearning", "homeRegion": "mumbai" }
PATCH /api/content/v1/storage-account
{ "homeRegion": "mumbai" }
{ "name": "acmelearning", "homeRegion": "mumbai",
  "blobEndpoint": "https://acmelearning.blob.plycdn.net", "dnsState": "active", "createdAt": "…" }

name is 3 to 24 lower-case letters and digits, unique across plycdn, and cannot be changed (a PATCH carrying name is validation_error). Reserved names and region codes are validation_error; a name already taken is storage_account_name_taken; a second account for the same organization is storage_account_exists; GET or PATCH before one exists is storage_account_not_found. homeRegion is a region code (region_not_available otherwise). blobEndpoint is the account's global host; dnsState is pending until that host resolves after a create or a home-region change, then active, or failed if it could not be set up (contact us). The regional hosts (endpoints.blob on GET /regions) work from the start.

33Video and webhooks

Video libraries, their videos, playback links and webhooks. Walkthroughs, the player and SDK usage are in Video and webhooks; this is the wire contract, under the same base address and authentication as the rest of this guide. Video is a plan feature: without it, creating a library or a video answers not_included_in_plan.

The three creating calls, POST /libraries, POST /libraries/{libraryId}/videos and POST /webhooks, require an Idempotency-Key header (idempotency_key_required without one): repeating one with the same key and body returns the first answer, so a timeout never creates a second library, video or endpoint, and the same key with a different body is idempotency_conflict. The .NET package sends a fresh key for each call unless you pass your own.

Video libraries

POST /api/content/v1/libraries          # 202
{ "name": "acme-lectures", "region": "mumbai", "strictResidency": false,
  "delivery": { "allowedDomains": ["learn.example.com"] },
  "processing": { "ladder": [240, 360, 480, 720, 1080], "keepOriginal": true, "download": false, "thumbnails": true },
  "maxObjectBytes": null }
{ "id": "…", "name": "acme-lectures", "kind": "video", "region": "mumbai", "strictResidency": false,
  "visibility": "private", "state": "creating", "failureReason": null, "suspended": false,
  "delivery": { "allowedDomains": ["learn.example.com"], "blockNoReferrer": false,
                "countriesAllow": [], "countriesBlock": [], "linkTtlSeconds": 14400,
                "ipBinding": false, "rateLimitKbps": null,
                "webPagesOnOwnDomains": false },
  "uploadRules": { "maxObjectBytes": null, "allowedTypes": ["video/*"], "allowOverwrite": false },
  "defaultHostname": "acme-lectures.plycdn.net",
  "deliveryBaseUrl": "https://acme-lectures.plycdn.net",
  "storedBytes": 0, "objectCount": 0, "createdAt": "…", "updatedAt": "…",
  "deletedAt": null, "purgeAfter": null,
  "processing": { "ladder": [240, 360, 480, 720, 1080], "keepOriginal": true, "download": false, "thumbnails": true },
  "processingOrigins": { "ladder": "parent", "keepOriginal": "default", "download": "default", "thumbnails": "default" },
  "usesOrganizationProcessing": true,
  "videoCount": 12,
  "playback": { "serial": false },
  "watermark": null, "logo": { "mode": "brand" },
  "effectivePlayer": { "watermark": null, "logo": null } }

A library is the Bucket shape with kind: "video", plus processing (what it encodes with now), processingOrigins (for each setting, library, organization, parent or default), usesOrganizationProcessing, videoCount, playback, and the viewer watermark and player logo: watermark (the library's own settings, or null while it uses the organization's), logo ({"mode": "brand"} or {"mode": "off"}) and effectivePlayer (what its viewers get now: watermark, the full settings or null when off, and logo, {url, position, size, opacity, inset} or null). Only name and region are required; the name rules are a bucket's. A library is always private (sending visibility is 422 validation_error, fields [["body","visibility"]]), takes video/* uploads only and never overwrites (uploadRules.allowedTypes and allowOverwrite cannot be changed, here or through PATCH /buckets/{bucketId}), and its links last 4 hours (linkTtlSeconds: 14400) unless you set delivery.linkTtlSeconds. Leave processing out and the library uses its organization's video settings (videoDefaults, under Video settings in the settings section); given, it is the library's own, and a field you leave out takes the organization's value as it is when saved. ladder is one or more of 240, 360, 480, 720, 1080, 1440, 2160, each once, returned in ascending order; a height that is not one of those is validation_error with its index ([["body","processing","ladder",0]]), and a repeated one names the list ([["body","processing","ladder"]]).

GET    /api/content/v1/libraries
GET    /api/content/v1/libraries/{libraryId}
PATCH  /api/content/v1/libraries/{libraryId}
DELETE /api/content/v1/libraries/{libraryId}    # 202

GET /libraries answers {"items": [ … ]}: your libraries only, never your files buckets (which GET /buckets still lists, along with libraries). An unknown id, a files bucket's id or another organization's library answers 404 library_not_found. PATCH takes delivery, processing, playback, watermark, logo and maxObjectBytes: a field left out is unchanged; watermark is merged over what the library shows now and gives it its own ({"watermark": {"mode": "brand"}} on its own returns it to the organization's; null is refused); logo is {"mode": "brand"} or {"mode": "off"}. The watermark's fields and limits are in Viewer watermark and player logo; processing merges field by field, gives the library its own settings and applies to videos encoded afterwards; "processing": null makes the library use its organization's settings again; null on one of its fields is refused (validation_error, fields naming it), because each always has a value; null on a delivery setting removes it exactly as on a bucket, except that "linkTtlSeconds": null returns to the library default of 4 hours. maxObjectBytes: null returns to your plan's largest file. DELETE is the bucket's soft delete ("state": "deleting", purgeAfter), and deletes the library's videos. Restore, retry, the signing profile, key rotation and listing objects are the /buckets/{bucketId} routes, called with the library's id. Libraries count towards your plan's bucket limit (plan_limit_reached). A suspended library ("suspended": true) still lists, reads, changes and deletes, and refuses new videos and playback links with 403 bucket_suspended.

Videos

POST /api/content/v1/libraries/{libraryId}/videos    # 201
{ "title": "Week 1: Introduction", "size": 734003200, "contentType": "video/mp4",
  "sha256": null, "fileName": "week-1.mp4", "metadata": { "course": "physics-101" } }
{ "id": "…", "libraryId": "…", "title": "Week 1: Introduction", "status": "ready", "errorCode": null,
  "durationSeconds": 612.48, "width": 1920, "height": 1080, "hasAudio": true,
  "renditions": [ { "height": 240, "width": 426, "bandwidth": 524000 },
                  { "height": 1080, "width": 1920, "bandwidth": 5478000 } ],
  "captions": [], "poster": true, "thumbnails": true, "download": false,
  "encoding": { "ladder": [240, 360, 480, 720, 1080], "keepOriginal": true, "download": false, "thumbnails": true,
                "origins": { "ladder": "parent", "keepOriginal": "default", "download": "default", "thumbnails": "default" } },
  "sourceKey": "sources/week-1.mp4",
  "playbackPaths": { "playlist": "/v/<videoId>/master.m3u8", "poster": "/v/<videoId>/poster.jpg",
                     "thumbnails": "/v/<videoId>/thumbnails.vtt", "download": null },
  "originalKept": true, "storedBytes": 734003200, "encodingMinutes": 10.208,
  "disabled": false, "metadata": { "course": "physics-101" }, "uploadId": "…",
  "createdAt": "…", "updatedAt": "…", "playableAt": "…", "readyAt": "…" }

playbackPaths is where the video plays from on any of its library's hostnames: playlist (the stream) always, and poster, thumbnails and download once the video has them (null until then). They are fixed from the moment the video is created. They are not links: sign one for each viewer (POST /sign or a playback session) on the hostname you choose. Store the video's id, never a signed link, which expires.

That is the Video shape. The 201 from creating one is the Video shape ("status": "uploading") plus "upload": an Upload session (see "Uploads" above) with "videoId" set to this video and the key sources/{videoId}{extension}. Send its parts and complete it as any upload; completion moves the video to queued. title is 1 to 200 characters, size at least 1, fileName at most 200 characters, contentType a video/… type, metadata up to 50 keys of strings, numbers or booleans and at most 8 KiB as JSON. An Idempotency-Key header is required (see below). A library that is not active answers bucket_not_active.

An upload under sources/ in a library, at any depth (POST /buckets/{libraryId}/uploads with "key": "sources/week-2.mp4" or "key": "sources/course-1/week-1.mp4"), creates a video when it completes, titled after the file name (week-1); the completion answer and GET /uploads/{uploadId} carry its "videoId" (null on any other upload). A library upload whose key is not under sources/ is refused with 422 validation_error, fields [["body","key"]]. One video comes from each key: once a video has been made from a key, another upload of that key is refused with 409 video_source_exists, so the same file is never processed twice; delete that video to use the key again.

S3 and Azure tools. A library is also reachable with a storage credential from S3 and Azure tools (the AWS CLI, rclone, AzCopy, the Azure CLI and the SDKs), as a bucket or container of the library's name, with the same rules: files go under sources/, each becomes a video titled from its title metadata (x-amz-meta-title, x-ms-meta-title) or its file name, anything else is refused (InvalidArgument / InvalidInput), and a key a video already came from is 409. Such a key stays listed in sources/, read-only (its size, ETag and upload time; never its bytes, and it can't be deleted from there), so a copy run again skips it. See Compatibility for the endpoints.

GET    /api/content/v1/libraries/{libraryId}/videos?status=ready&cursor=…&limit=50
GET    /api/content/v1/libraries/{libraryId}/videos?sourceKey=sources/course-1/week-1.mp4
GET    /api/content/v1/videos/{videoId}
PATCH  /api/content/v1/videos/{videoId}
DELETE /api/content/v1/videos/{videoId}    # 202
POST   /api/content/v1/videos/{videoId}/reencode    # 202

sourceKey narrows the list to the video made from that key: the way to find what a file uploaded under sources/ became.

POST .../reencode encodes a ready video again with the settings that apply now (admin key). It answers the video, now queued; it keeps playing from its current qualities until the first new one is made, and the usual events follow. A video that is not ready (other than a failed one that had been ready, whose new encode failed), or is taken down, answers 409 video_not_ready; a video whose original was not kept answers 409 original_not_kept. Each re-encode is charged encoding minutes like the first encode, as its own usage entry. A re-encode that fails is not charged and loses nothing: the video goes back to ready with what it had (another video.ready event) and errorCode set, or, if no complete quality is left, to failed with its files and original kept; encode it again once the cause is fixed. A video's encoding (the four settings used and where each came from, or null) is part of the Video shape.

The list answers {"items": [ …Video… ], "nextCursor": "…"|null}, newest first; status filters, limit is 1 to 200 (50 when omitted), and cursor is followed until nextCursor is null. PATCH takes title and metadata (which replaces the whole object); a field left out is unchanged. DELETE answers {"id": "…", "status": "deleted"} and removes every file of the video at once, its source file under sources/ included: there is no restore. While the video's upload is being completed, DELETE answers 409 upload_not_open marked "retryable": true: ask again shortly. An unknown, deleted or another organization's video answers 404 video_not_found.

status is uploading, queued, encoding, playable (the lowest quality plays), ready or failed, or live for the video of a live stream that is on air (it then also carries liveInputId and "live": true, and goes on to playable and ready when the stream ends; see Live inputs and streams). A failed video's errorCode is one of:

errorCode Meaning
video_unreadable The file could not be read as video (damaged, truncated, zero length, or not the format its name says)
video_no_video_stream The file has no picture (audio only)
video_too_long Longer than your plan allows
video_resolution_unsupported Smaller than 16 or larger than 8192 pixels on a side
video_source_missing The uploaded file was deleted, or replaced by another upload to the same name, before encoding finished. For a video that never became ready, the key is free again: a new upload to it makes a new video and deletes this one
upload_abandoned The upload created with the video was aborted or expired before completing
encoding_failed Encoding failed on our side after every retry. Upload the file again

encodingMinutes is the source's duration in seconds ÷ 60, to six decimal places, counted when the video becomes ready (and again, as its own entry, each time it is encoded again); it is null until then, and a failed video is never counted. It appears in /usage as encoding_minutes (unit minutes) and in "Usage by resource" against the library. storedBytes is what the video holds in its library (qualities, images, download, kept original), which counts as that library's storage. A video plycdn has taken down shows "disabled": true. captions lists the video's caption tracks once captions are added to it.

POST /api/content/v1/sign
{ "bucketId": "<libraryId>", "videoId": "<videoId>", "ttlSeconds": 14400, "ip": null, "hostname": null }
{ "url": "https://acme-lectures.plycdn.net/v/<videoId>/master.m3u8?token=…&expires=1790000000&token_path=%2Fv%2F<videoId>%2F",
  "nativeUrl": null, "expiresAt": "…",
  "posterUrl": "https://acme-lectures.plycdn.net/v/<videoId>/poster.jpg?token=…",
  "thumbnailsUrl": "https://acme-lectures.plycdn.net/v/<videoId>/thumbnails.vtt?token=…",
  "downloadUrl": null }

Send exactly one of key, objectId and videoId (more than one, or none, is 422 validation_error). With videoId, the link covers every file under that one video (scheme pl1d, or ps3 on an earlier library, documented under Signing playback yourself in Video and webhooks) and nothing else. url is the stream's master playlist. nativeUrl is the same with the token in the path, for browsers that play the stream natively, and is null wherever the signing profile's pathTokens is false. posterUrl, thumbnailsUrl and downloadUrl are null when the video has no such file. ttlSeconds defaults to the library's linkTtlSeconds; ip works as for a file, and so does hostname: leave it out for the library's own hostname, or name one of the library's active custom domains, and every address in the answer is on it (409 domain_not_active otherwise; the token is the same on every hostname). A video that is not playable or ready answers 409 video_not_ready; a video from another library, or one taken down, answers 404 video_not_found; a suspended library answers 403 bucket_suspended; a library that requires the viewer watermark answers 409 watermark_required (its videos play through playback sessions only).

A library's signing profile (GET /buckets/{bucketId}/signing-profile) carries two more fields, "directoryScheme": "pl1d" (or "ps3" on a library made before plycdn links) and "pathTokens": false|true (on a files bucket, null and false). A library that requires the viewer watermark also carries "watermarkRequired": true (the key is there only then) and "serial": true, so signers refuse to sign its videos.

Playback sessions and progress

POST /api/content/v1/playback-sessions        {"bucketId", "videoId", "resumeId"?, "ttlSeconds"?, "ip"?, "watermark"?, "continues"?, "watermarkProof"?, "hostname"?}   (ip: required on an ipBinding library; on a library whose watermark shows ip, used for that line; refused otherwise. hostname: as on /sign, the library's own or one of its active custom domains, 409 domain_not_active otherwise)
GET /api/content/v1/playback-progress         ?bucketId=…&resumeId=…[&videoId=…][&cursor=…&limit=…]
DELETE /api/content/v1/playback-progress      ?bucketId=…&videoId=…&resumeId=…
GET /api/content/v1/libraries/{libraryId}/watch-time   ?from=…&to=…[&groupBy=…][&resumeId=…][&videoId=…][&cursor=…&limit=…][&format=csv]

A library's playback is {"serial": false} by default. Send "playback": {"serial": true} when you create the library or with PATCH /libraries/{id} to turn serial playback on, and false to turn it off. Without the serial_playback feature the answer is 403 not_included_in_plan; a library made before plycdn links answers 409 serial_playback_needs_plycdn_links (contact support to move it onto serial playback). Turning it on counts as a change of the library's signing keys, so it can answer 429 rate_limited with Retry-After, and while the library is being moved to another delivery network, 409 serial_playback_busy with retryable: true and Retry-After.

A session on a library with serial playback answers serial: true, url and nativeUrl (the same address), posterUrl, thumbnailsUrl and downloadUrl (null), expiresAt, pass, progressUrl (null without resumeId), watchedSeconds, durationSeconds and completed; on any other library, the POST /sign answer with serial: false. resumeId is 1 to 128 of A-Z a-z 0-9 . _ : @ -; with one, a session starts at the position plycdn has recorded for that viewer, never where a browser asks. A video not ready at the edge yet answers video_not_ready with retryable: true. Progress reads {videoId, watchedSeconds, durationSeconds, completed, completedAt, updatedAt, watchTimeSeconds, firstWatchedAt}, a list {items, nextCursor}; a reset answers 204 and starts the position and completion over, while watch time is history and is kept. See Serial playback.

A session on a library with serial playback also answers progressIntervalSeconds (60) and watchTimeSeconds (this viewer's total for the video). A session on any other library, started with a resumeId, answers the ordinary links with serial: false and pass, progressUrl, progressIntervalSeconds (120), watchedSeconds, durationSeconds, completed and watchTimeSeconds, so the viewer's watch time is kept; without a resumeId there is no session and the answer is the POST /sign answer. The player posts to progressUrl as text/plain:

{"pass": "<pass>", "position": <seconds>, "played": <seconds>}

played is optional (seconds, 0 to 10,000,000; left out means 0, so older players keep working) and is the session's total playing time so far, never an increment, so a save that is lost or repeated changes nothing. plycdn never counts more than the time that has really passed since the session started. Watch time is the time a video was playing for that viewer: pauses don't count, watching again does, and two players open at once both count.

Viewer watermark. watermark carries who is watching, for a library whose watermark shows them: {"name"?, "email"?, "phone"?, "viewerId"?, "look"?}, each detail plain text up to 1,000 characters, and look any of opacity (5 to 60), size, color, moveEverySeconds (10 to 300, or null to stay put) and placement, for this viewer only. The details are never stored. When the library shows a watermark or a logo, the answer gains watermark ({mode, lines, timeAt, look, moveEverySeconds, placement, proof?}) and logo ({url, position, size, opacity, inset}); on a library that shows neither it is unchanged. On a library that requires the watermark:

  • watermark is required on every session ({} with no details), else 409 watermark_required.
  • The session lasts at most 600 seconds and answers sessionId, renewBy (80 % of the way), pass, progressUrl (also without a resumeId) and progressIntervalSeconds: 60, with nativeUrl and downloadUrl null; watermark.proof is {"key": "<43 characters>", "everySeconds": 60}.
  • Check-ins add the proof: {"pass", "position", "played"?, "watermark": {"state": "present" | "tampered", "proof": "<key>"}}. One without it, with tampered or with another proof counts against the viewing.
  • Renew with a new session before renewBy: the same body plus continues (the current sessionId) and watermarkProof (its proof.key), both or neither (else 422 validation_error), with the same resumeId as the session (or none if it had none). A proof renews once. 403 watermark_proof_invalid for a proof that doesn't match or another resumeId, 403 watermark_tampered after two counted check-ins (carried over renewals, and for a resumeId over fresh sessions for an hour), 410 playback_session_expired more than 120 seconds after the session ended (then start a fresh session, without continues).

See Viewer watermark and player logo.

Watch time report

GET /api/content/v1/libraries/{libraryId}/watch-time

Needs an admin key (403 admin_key_required for a standard key) and is in every plan. Parameters:

Parameter Meaning
from, to YYYY-MM-DD, UTC, inclusive. Default: the last 30 days. At most 366 days.
groupBy viewer (default) or video.
resumeId One viewer: the items are that viewer's videos.
videoId One video: the items are its viewers. With both resumeId and videoId, one row.
cursor, limit Paging: limit is 1 to 500 (100 when omitted); follow nextCursor until it is null.
format=csv A CSV download of every row of the range, with no paging.
{ "from": "2026-10-01", "to": "2026-10-31",
  "totals": { "watchTimeSeconds": 482300, "viewers": 214, "videos": 18 },
  "items": [ { "resumeId": "member-42", "watchTimeSeconds": 11520, "videosWatched": 9, "videosCompleted": 6,
               "lastWatchedAt": "2026-10-23T09:12:44Z" } ],
  "nextCursor": null }

By video, an item is {videoId, title, watchTimeSeconds, viewers, completions}; for one viewer (resumeId), it is {videoId, title, watchTimeSeconds, watchedSeconds, durationSeconds, completed}. Items are ordered by watchTimeSeconds, most first. Watch time is summed over the days of the range; videosWatched, videosCompleted, completions, watchedSeconds and completed describe where viewers are now. The CSV answers as an attachment named watch-time-<library>-<from>-<to>.csv, with watch time in seconds. A library that doesn't exist answers 404 library_not_found; dates that aren't valid, a range over 366 days or a limit out of range answer 422 validation_error. See Watch time.

Live inputs and streams

Live streaming, from broadcasting to playing and recording, is explained in the Video guide; this is the wire contract. It is a plan feature (live): a plan without it answers 403 feature_not_in_plan, and until live streaming is switched on for your service every route below answers 404 feature_not_available. Every route except GET /live-inputs/{id} and POST /sign needs an admin key (403 admin_key_required for a standard key, which is why they belong in your backend).

Method and path What it does
POST /libraries/{libraryId}/live-inputs Create an input (201); the answer carries streamKey
GET /libraries/{libraryId}/live-inputs The library's inputs, oldest first: { "items": [LiveInput] }
GET /live-inputs/{id} One input. A standard key (or ?view=browser) gets the browser view
PATCH /live-inputs/{id} Rename, change settings, replace metadata
DELETE /live-inputs/{id} Delete an input with no stream running (204)
POST /live-inputs/{id}/stream-key Replace the stream key; the answer carries the new streamKey
GET /live-inputs/{id}/stream-key Show the current key again (audited): the same answer
POST /live-inputs/{id}/publish-tokens A token for one browser to go live (201)
POST /live-inputs/{id}/disable, POST /live-inputs/{id}/enable Stop and allow new streams; disabling ends the one running within seconds
POST /live-inputs/{id}/end End the running stream now
GET /live-inputs/{id}/streams The input's streams, newest first, paged
GET /streams/{id} One stream
GET /streams/{id}/captions The stream's caption languages and mode (a standard key may call it)
GET /streams/{id}/viewers Who watched it: peak, watch time, countries and a series
GET /streams/{id}/health Its health, minute by minute
POST /live-inputs/{id}/destinations, GET /live-inputs/{id}/destinations Add a restream destination (201); list an input's
PATCH /destinations/{id}, DELETE /destinations/{id} Change a destination; delete one (204)
POST /destinations/{id}/test Check that a destination's platform answers
POST /live-inputs/{id}/breaks Mark an ad break on the input's running stream (201)
POST /live-inputs/{id}/share-links, GET /live-inputs/{id}/share-links Make a share link (201); list an input's, newest first
PATCH /live-inputs/{id}/share-links/{linkId}, DELETE /live-inputs/{id}/share-links/{linkId} Change a share link or turn it off; delete one (204)
GET /watch-brand, PUT /watch-brand Read and change the watch page brand
PUT /watch-brand/logo, DELETE /watch-brand/logo Set the brand's logo (the image as the body); remove it (204)
GET /watch-domains, POST /watch-domains The organization's watch domains; add one (202)
GET /watch-domains/{id}, DELETE /watch-domains/{id} One watch domain; remove it (204)
POST /watch-domains/{id}/check Check a watch domain's DNS records now (202)
POST /sign with liveInputId Playback links for the stream running now (a standard key may call it)
POST /api/content/v1/libraries/{libraryId}/live-inputs        # 201, Cache-Control: no-store
Idempotency-Key: <your own unique value>
{ "name": "Main stage",
  "settings": { "delivery": "broadcast", "quality": "hd", "passthrough": true, "recording": true,
                "reconnectWindowSeconds": 60, "maxDurationSeconds": 86400, "latencyTarget": "lowest" },
  "metadata": { "event": "keynote" } }

name is 1 to 200 characters. Every settings field is optional and never null: on a create, what you leave out takes its default, on a PATCH, only the fields you send change (metadata, if sent, replaces the whole map; omit it to keep it). Settings apply from the next stream. delivery is broadcast or realtime; quality is source, sd, hd or fhd; passthrough and recording are booleans; reconnectWindowSeconds is 0 to 600; maxDurationSeconds is 60 or more and, with quality, must be within your safety caps (409 live_cap_reached); latencyTarget is lowest or balanced. The rest are described under Live input settings below: backupIngest, redundantTranscoding, captions, dvrWindowSeconds, indexRecording, protection and ads. metadata is up to 50 keys of strings, numbers or booleans, at most 8 KiB. A library in a region that does not offer live streaming answers 400 region_not_available (GET /regions shows "live": true where it is offered). Idempotency-Key is required (400 idempotency_key_required without it): repeating the create with the same key and body answers the same input with its stream key (recorded in the audit log like a show-key) instead of making a second input; the same key with a different body is 409 idempotency_conflict, and once the input is deleted the repeat answers 404 live_input_not_found.

{ "id": "5f0e…", "libraryId": "…", "name": "Main stage", "state": "idle",
  "streamKeyPrefix": "live_Ab3D",
  "streamKey": "live_Ab3D…",
  "ingest": { "rtmps": "rtmps://in-mum.live.plycdn.com:443/5f0e…?key={streamKey}", "rtmp": "rtmp://in-mum.live.plycdn.com:1935/5f0e…?key={streamKey}",
              "srt": "srt://in-mum.live.plycdn.com:9000?streamid=publish:5f0e…:live:{streamKey}&latency=120",
              "whip": "https://whip-in-mum.live.plycdn.com/5f0e…/whip" },
  "settings": { "delivery": "broadcast", "quality": "hd", "passthrough": true, "recording": true,
                "reconnectWindowSeconds": 60, "maxDurationSeconds": 86400, "latencyTarget": "lowest" },
  "stream": null,
  "metadata": { "event": "keynote" }, "createdAt": "…", "updatedAt": "…" }

That is the LiveInput shape. streamKey appears only in the answers of create, replace and show-key, which are never cached; lists and every other answer carry streamKeyPrefix alone. state is idle, connected (publishing, not yet watchable), live or disabled. ingest holds the four publishing addresses ({streamKey} in each is replaced by the key, and the input's id is already in place; whip is for browsers, with a publish token). stream is the stream running now, or null:

{ "id": "a91c…", "state": "live", "startedAt": "…", "liveAt": "…", "protocol": "rtmps", "renditionsVersion": 2,
  "qualitiesComing": false, "realtimeViewers": 0, "recordingId": "a91c…",
  "health": { "inputKbps": 4200, "fps": 30, "keyframeSeconds": 1, "audio": true, "width": 1920, "height": 1080, "latency": "low" } }

state is starting, live, reconnecting or ending while it runs. renditionsVersion grows whenever the set of qualities on offer changes. qualitiesComing is true while the stream is on air in its original quality only and its other qualities are being prepared (for about a minute after it goes live); they are then added by themselves, renditionsVersion grows and it is false. health is what plycdn measures of the incoming picture; latency is low or standard; any health value can be null before it is known.

The browser view. GET /live-inputs/{id}?view=browser, which a standard key always gets (the parameter is forced), answers only what a page may show:

{ "id": "5f0e…", "state": "live", "delivery": "broadcast",
  "stream": { "id": "a91c…", "state": "live", "startedAt": "…", "liveAt": "…", "renditionsVersion": 2, "qualitiesComing": false } }

stream is null when none is running.

POST /api/content/v1/live-inputs/{id}/publish-tokens          # 201, no-store
{ "ttlSeconds": 900 }
{ "token": "lpt1.…", "expiresAt": "2026-10-04T10:15:00+00:00", "whipUrl": "https://whip-in-mum.live.plycdn.com/5f0e…/whip" }

ttlSeconds is 1 to 3600 (900 when the body is empty or the field left out). The token is for this input, starts one stream, and is withdrawn when the key is replaced or the input is disabled or deleted. A disabled input answers 409 live_input_disabled. The browser sends it to whipUrl as Authorization: Bearer <token>; a refused token is publish_token_invalid.

POST /live-inputs/{id}/end answers the stream (the stream shape below) or 409 live_not_started ("retryable": true) when no stream is running. DELETE is 409 live_input_busy while one is. Disabling an input answers disabled at once and ends its running stream with input_disabled within about 15 seconds; enabling answers idle, or live if that stream has not finished ending yet.

GET /api/content/v1/live-inputs/{id}/streams?limit=50&cursor=…
GET /api/content/v1/streams/{id}
{ "items": [ { "id": "a91c…", "liveInputId": "5f0e…", "state": "ended", "endReason": "ended_by_request",
               "delivery": "broadcast", "quality": "hd", "rungs": ["720p", "480p"],
               "startedAt": "…", "liveAt": "…", "endedAt": "…", "durationSeconds": 3612, "disconnectedAt": null,
               "protocol": "rtmps", "renditionsVersion": 2, "realtimeViewers": 0, "recordingId": "a91c…", "health": null } ],
  "nextCursor": null }

A stream's state is starting, live, reconnecting, ending, ended or failed (no picture arrived within 30 seconds). endReason is null until it ends, then one of encoder_disconnected, ended_by_request, max_duration_reached, input_disabled, input_unsupported, input_no_video, input_bitrate_exceeded or processing_failed. limit is 1 to 100 (50 when omitted); follow nextCursor until it is null. rungs names the qualities on offer, for example 720p. durationSeconds is how long it ran, disconnectedAt when the encoder dropped (while it is reconnecting). recordingId is the stream's id, which is also its recording's video id (see Videos); it is present whether or not the input records, and the video exists only when it does and the stream went live (a stream that ended before any picture was delivered leaves no video). A stream id that does not exist is 404 video_not_found, and an input that does not exist is 404 live_input_not_found.

Live input settings

The settings of a live input beyond the first seven, as they appear in a LiveInput's settings (every one has a value in an answer):

Setting Values Default Notes
backupIngest boolean false Adds ingest.rtmpsBackup, ingest.rtmpBackup and ingest.srtBackup (the input's id with -backup after it, the same key, on the backup host name backup-{label}.live.plycdn.com where the region has one, otherwise the primary's) for a second encoder. Fixed while a stream runs; a plan option
redundantTranscoding boolean false A standby copy of the stream's processing. Fixed while a stream runs; a plan option
captions { "enabled": bool, "languages": [code, …], "mode": "realtime" | "nearLive" } { "enabled": false, "languages": [], "mode": "realtime" } At most two distinct language codes, at least one when enabled; each must be offered to the library. Replaces the whole object. Fixed while a stream runs. When your plan includes live_captions
dvrWindowSeconds 0 to 7,200 0 The seek-back window, in seconds; held to your live_dvr_seconds cap. Fixed while a stream runs
indexRecording boolean false Make recordings searchable. Needs video and Content Search in the plan, downloads on, and a library without strict residency. A library's own search switch does the same for every input
protection { "provider": string, "options": { … } } absent Content protection; "provider" is one of GET /live/protection-setups, and "none" removes it
ads { "enabled": bool, "vmapUrl": url, "vastUrl": url, "slate": url, "personalised": bool } absent Ad insertion: vmapUrl or vastUrl (not both) when enabled; https:// on port 443, up to 2,048 characters. Replaces the whole object. When your plan includes live_ads

400 protection_not_configured where a protection setup is refused, 409 live_setting_not_in_plan (detail.setting) for a setting your plan or service does not include, 409 live_input_busy for a fixed setting while a stream runs, and 409 live_setting_conflict for the two combinations below. An answer shows protection as the settings you saved; options is a plain list of names and values, and a credential is never written in one.

GET /api/content/v1/live/protection-setups          # admin key
{ "items": [ { "name": "standard" } ] }

The content protection setups your account may name in protection.provider: each is your own key service, set up with us. The list is empty when your account has none, and the route answers 404 feature_not_available and 403 feature_not_in_plan as the other live routes do.

Combinations that are refused: ads enabled with protection (detail.settings ["ads", "protection"]) and ads enabled with a dvrWindowSeconds above 0 (detail.settings ["ads", "dvrWindowSeconds"]), whichever you save second, and again when a stream starts. "enabled": false ads can sit beside either. A setting you leave out is kept, so setting dvrWindowSeconds above 0 on an input whose ads are enabled is refused too.

The three backup addresses, when on:

"ingest": { "rtmps": "…", "rtmp": "…", "srt": "…", "whip": "…",
            "rtmpsBackup": "rtmps://in-mum.live.plycdn.com:443/5f0e…-backup?key={streamKey}",
            "rtmpBackup":  "rtmp://in-mum.live.plycdn.com:1935/5f0e…-backup?key={streamKey}",
            "srtBackup":   "srt://in-mum.live.plycdn.com:9000?streamid=publish:5f0e…-backup:live:{streamKey}&latency=120" }

A stream running now carries two more fields in the admin answer, captions ({ "languages": ["en"], "mode": "realtime" }, or null) and, with ads, health.ads ({ "lastError": null | "ad_server_unreachable", "breaks": 3, "noFill": 0, "tracking": { "sent": 12, "failed": 0, "dropped": 0 } }). How they behave is in the Video guide.

Stream captions, viewers and health

GET /api/content/v1/streams/{id}/captions                     # a standard key may call it
{ "streamId": "a91c…", "mode": "realtime", "languages": [ { "language": "en", "name": "English" } ] }

mode is realtime or nearLive, the one in force; a stream without captions answers "mode": null and "languages": []. The captions themselves are read from the tracks in the playback links. An unknown stream is 404 video_not_found.

GET /api/content/v1/streams/{id}/viewers?from=2026-10-04T10:00:00Z&to=2026-10-04T11:00:00Z&step=300
GET /api/content/v1/streams/{id}/health?from=…&to=…&step=300

from and to (UTC, defaulting to the stream's own span) and step (60, 300, 900 or 3600 seconds; the smallest that gives about 500 points when left out) are the same on both. A step that is not one of those, or a range of more than 1,500 points, is 422 validation_error. Viewers:

{ "streamId": "a91c…", "from": "…", "to": "…", "step": 300, "peakConcurrent": 812, "viewerMinutes": 20431.0, "broadcastCounted": true,
  "countries": [ { "country": "IN", "viewerMinutes": 9120 } ],
  "series": [ { "at": "…", "viewers": 790, "broadcast": 640, "realtime": 150, "viewerMinutes": 3950.0 } ] }

broadcastCounted is false when the library has delivery analytics off, in which case only real-time viewers appear. countries is the top ten by viewer-minutes, from broadcast viewers. Health:

{ "streamId": "a91c…", "from": "…", "to": "…", "step": 300,
  "series": [ { "at": "…", "inputKbps": 4180.5, "fps": 29.97, "keyframeSeconds": 1.0, "speed": 1.01, "partPushP95Ms": 140, "gaps": 0, "failovers": 0 } ],
  "totals": { "gaps": 0, "failovers": 0 } }

Any value except gaps and failovers is null where nothing reported it in that step; health is kept 30 days. Both need an admin key.

Restream destinations

With live_restream in your plan: until restreaming is switched on for your service these routes answer 404 feature_not_available, and without it in your plan 403 feature_not_in_plan. Admin key.

POST /api/content/v1/live-inputs/{id}/destinations            # 201, Cache-Control: no-store
Idempotency-Key: <your own unique value>
{ "name": "Partner site", "url": "rtmps://live.partner.example/app", "key": "abcd-1234" }

Idempotency-Key is required (400 idempotency_key_required without it): repeating the create with the same key and body answers the same destination instead of adding a second one, and the same key with a different body is 409 idempotency_conflict.

name is 1 to 200 characters; url is 8 to 1,024 characters, rtmp:// or rtmps://, port 443 or 1935, without the key in it; key is 1 to 512 printable characters with no spaces and is never returned. A Destination:

{ "id": "d3f1…", "liveInputId": "5f0e…", "name": "Partner site", "url": "rtmps://live.partner.example/app",
  "state": "idle", "lastError": null, "startedAt": null, "createdAt": "…", "updatedAt": "…" }

state is idle, connecting, live or failed; lastError is null or one of destination_unreachable, destination_refused, destination_rejected_stream, destination_dropped and destination_address_forbidden. GET /live-inputs/{id}/destinations answers { "items": [Destination] }, oldest first. PATCH /destinations/{id} takes name, url and key, each optional and never null; a new address or key resets the destination to idle and a running push reconnects. DELETE /destinations/{id} answers 204 and removes the key. POST /destinations/{id}/test answers { "reachable": true } or 502 destination_unreachable ("retryable": true) after a few seconds; it never publishes and never uses the key.

Refusals: 400 destination_url_invalid, 404 destination_not_found, 409 destination_limit_reached (detail.cap live_destinations, detail.limit: 10 per input unless raised), 429 rate_limited (Retry-After) on creating, changing an address and testing (hourly allowances, and one test at a time per account). Deleting an input deletes its destinations. A protected stream is never restreamed.

Ad breaks

With live_ads in your plan: ad breaks and the ads setting answer 404 feature_not_available until ad insertion is switched on for your service, and 403 feature_not_in_plan without it in your plan. Admin key.

POST /api/content/v1/live-inputs/{id}/breaks                  # 201, Cache-Control: no-store
{ "durationSeconds": 30, "at": "now", "podId": "midroll-1" }

durationSeconds is above 0 and at most 600; at is "now" (the default) or a time with its UTC offset up to 24 hours ahead (up to ten seconds in the past counts as now); podId is 1 to 64 letters, digits and _ . : -. It answers a Break:

{ "id": "b71a…", "liveInputId": "5f0e…", "streamId": "a91c…", "state": "scheduled", "durationSeconds": 30.0,
  "requestedAt": "…", "startedAt": null, "endedAt": null, "podId": "midroll-1" }

state is scheduled, started, ended, missed or cancelled (with cancelledAt). Refusals: 409 live_not_started ("retryable": true: no stream is on air), 409 live_input_busy (it would overlap a break already asked for), 409 live_cap_reached (detail.cap scheduled_breaks, detail.limit 16), 422 validation_error for a time in the past or more than a day ahead. The live.ad_break webhook is sent when a break starts. In an ad address, [CACHEBUSTING], [TIMESTAMP], [BREAKMAXDURATION] and [PODID] are filled in, and with personalised also [SESSIONID] and [CLIENTUA]; one without a value is sent as -1. What a personalised request carries, and what is counted once per break, is in the Video guide.

GET    /api/content/v1/live-inputs/{id}/breaks?limit=50           # Cache-Control: no-store
DELETE /api/content/v1/live-inputs/{id}/breaks/{breakId}          # 200, Cache-Control: no-store

The list answers { "items": [Break] }, newest first by requestedAt; limit is 1 to 100 (50 when omitted). DELETE cancels a scheduled break due more than 45 seconds from now and answers it with "state": "cancelled" and cancelledAt; any other is 409 ad_break_not_cancellable (detail.state), and a break that is not this input's is 404 ad_break_not_found. Admin key. The audit log records it as live.break_cancelled.

POST /api/content/v1/sign
{ "bucketId": "<libraryId>", "liveInputId": "<liveInputId>", "mode": "realtime", "ttlSeconds": 900, "ip": null }

Send exactly one of key, objectId, videoId and liveInputId. mode is broadcast or realtime (the input's own delivery when omitted) and only goes with liveInputId. ttlSeconds is 60 to 604,800 (in real-time mode the links last at most 24 hours); ip works as for a video: give it only for a library with ipBinding, where it is required (on any other library it is 422 validation_error). A live link without ip expires on the next five-minute boundary after ttlSeconds (so it can last up to five minutes longer than asked): every viewer signed in the same five minutes gets the same link, which lets very large audiences be served from the edge. A link with ip is the viewer's own and expires exactly when asked. tags are refused on a live link with 422 tags_not_on_live, and hostname with 422 hostname_not_on_live (custom domains are not available for live links).

{ "live": true, "mode": "broadcast", "latency": "low", "streamId": "a91c…", "liveInputId": "5f0e…",
  "url": "https://acme-events.plycdn.net/v/a91c…/ll/master.m3u8?token=…",
  "fallbackUrl": "https://acme-events.plycdn.net/v/a91c…/master.m3u8?token=…",
  "whepUrl": null, "realtime": null, "rungs": null,
  "captions": [ { "language": "en", "url": "https://acme-events.plycdn.net/v/a91c…/captions/en/index.m3u8?token=…" } ],
  "dvrWindowSeconds": 0, "expiresAt": "…" }

For broadcast, url is the low-latency stream, fallbackUrl the standard one, latency low or standard, and rungs is null. For realtime, realtime is { "kind", "url", "token" } (below), whepUrl carries the same address with the token for kind whep, rungs lists the names of the qualities a viewer can choose, url is the broadcast stream for overflow and latency (low or standard) describes that overflow link; expiresAt is at most 24 hours away, following the viewer's token. mode is broadcast, with no whepUrl, when the input's own delivery mode is broadcast, and also when a real-time input's cap or capacity is reached. The first real-time viewer of a stream may see one automatic retry; nothing is needed from you. With no stream running the answer is 409 live_not_started with "retryable": true; a disabled input answers 409 live_input_disabled.

realtime.kind is whep or rtc: how the player connects. For whep, url is an https:// address and token goes with it; for rtc, url is a wss:// address and token is valid for five minutes, long enough to join, so a player that must rejoin asks for new links. captions has an entry for each caption language of the stream ([] without captions). dvrWindowSeconds is the seek-back window in seconds (0: none).

Two fields appear only when they apply:

"ads": { "sessionId": "…" },
"protection": { "scheme": "cbcs",
                "keySystems": [ { "system": "fairplay", "licenseUrl": "https://…", "certificateUrl": "https://…" },
                                { "system": "widevine", "licenseUrl": "https://…" } ] }
  • watermark and logo are there when the library or your brand shows them: a watermark of the fixed text and the date and time only ("mode": "show", no viewer details and no proof; it is not required on live) and the player logo, in the shapes of a playback session.
  • ads is there when the input's ads are personalised: the viewer's playback session is already part of url. It is absent when the stream is over its limit of personalised viewers (2,000 unless raised): the answer is then the shared link, so a client must accept an answer without ads and play url as given.
  • protection is there when the stream is protected, and the same object comes back on the playback link of a protected recording (POST /sign with a videoId, next to downloadUrl; a protected recording has no posterUrl, thumbnailsUrl or downloadUrl; a link you sign yourself from the signing profile never carries protection, so sign a protected recording through POST /sign). system is widevine, playready, fairplay or clearkey, each at most once, in the order fairplay, widevine, playready, clearkey; licenseUrl (required) and certificateUrl (optional) are https://, and the licenseUrl addresses can expire with the link and carry the viewer's binding. A player uses the first system its browser supports. A protected stream is always answered as broadcast, with realtime and whepUrl null. If the key information cannot be produced the answer is 503 protection_not_configured ("retryable": true) and no link is returned.

A share link lets anyone watch a live input without an account (Share a live stream). The four management routes need an admin key (403 admin_key_required for a standard key) and answer 404 feature_not_available while live streaming is not switched on, 403 feature_not_in_plan without it in your plan, and 404 live_input_not_found for an input that is not yours. Every answer carries Cache-Control: no-store.

POST /api/content/v1/live-inputs/{id}/share-links             # 201
{ "label": "Town hall, all staff", "password": "meeting-2026", "expiresAt": "2026-12-01T10:00:00Z", "showRecording": true,
  "title": "All hands", "layout": "cinema" }

Every field is optional. label is 1 to 100 characters; password is 4 to 128 characters; expiresAt has a time zone and is in the future; showRecording is true when left out. title, description, messages and layout are for this link only and are checked as for the brand; they win over the brand's, field by field. A ShareLink:

{ "id": "d4e5…", "liveInputId": "5f0e…", "url": "https://watch.plycdn.com/AbCdEfGhIjKlMnOpQrStUv",
  "urls": [ "https://watch.plycdn.com/AbCdEfGhIjKlMnOpQrStUv", "https://watch.example.com/AbCdEfGhIjKlMnOpQrStUv" ],
  "label": "Town hall, all staff", "hasPassword": true, "expiresAt": "2026-12-01T10:00:00Z", "showRecording": true, "disabled": false,
  "title": "All hands", "description": null, "messages": null, "layout": "cinema", "createdAt": "…", "updatedAt": "…" }

urls lists every address that opens the link: url first, then one on each of your active watch domains. title, description, messages and layout are null when the link follows the brand. GET /live-inputs/{id}/share-links answers { "items": [ShareLink] }, newest first. PATCH /live-inputs/{id}/share-links/{linkId} takes any of label, password, expiresAt, showRecording and disabled; a field you leave out is unchanged, and null removes label, password or expiresAt (title, description, messages and layout return to the brand's with null; showRecording and disabled take true or false, never null: 422 validation_error). DELETE answers 204 and the address stops working for good. The password is never answered: hasPassword says whether there is one. An input can have 50 links at most. Refusals: 404 share_link_not_found, 409 share_link_limit_reached (detail.limit: 50), and 422 validation_error (fields names the body field).

Watch page brand

Your organization's brand: the look of the pages share links open, and the player logo and viewer watermark every video library uses unless it has its own. Admin key; it needs no live streaming. GET /watch-brand answers a WatchBrand:

{ "accentColor": "#c2410c", "backgroundColor": null, "theme": "dark", "layout": "side_panel", "title": "Acme Summit", "description": null,
  "messages": { "starting": "Doors open soon" }, "siteUrl": "https://acme.example/", "siteLabel": "Visit Acme",
  "footerLinks": [ { "label": "Privacy", "url": "https://acme.example/privacy" } ], "logoSize": "large",
  "logoUrl": "https://watch.plycdn.com/api/watch/brand/…/logo?v=2", "inherited": false,
  "playerLogo": { "enabled": true, "position": "bottom-right", "size": "medium", "opacity": 80, "inset": 16 },
  "watermark": { "mode": "show", "fields": ["name", "email", "time"], "phoneMask": true, "text": "Example Academy", "opacity": 25,
                 "size": "medium", "color": "auto", "moveEverySeconds": 30, "placement": "anywhere" } }

playerLogo and watermark are left out until they are saved; their defaults are in Viewer watermark and player logo. In a PUT, the fields of either you name are merged over what is saved, and null returns it to the defaults. A watermark that is shown must show a field or the text (422 validation_error).

Defaults are theme dark, layout standard, messages {}, footerLinks [] and null for everything else (logoSize null shows the logo as small). inherited is true when a sub-organization has no brand of its own and shows its account's, logo included; its first PUT starts from the defaults, not from a copy of the account's brand, except that a playerLogo or watermark it names is merged over the account's, and a first logo upload keeps the account's watermark and player logo. A first PUT that names neither turns them off for the sub-organization's libraries that follow its brand (a watermark the account requires included), so send both in that first PUT (the dashboard always does).

Sub-organizations inherit the main organization's brand, so a key for the main organization only can read it but not change it: PUT /watch-brand, PUT /watch-brand/logo and DELETE /watch-brand/logo with such a key answer 403 organization_out_of_key_reach. Change it in the dashboard or with a key that reaches the whole account.

PUT /watch-brand takes the same fields except the logo. A field you leave out is kept; null returns it to its default. Colours are #rrggbb (either case; kept in lower case). theme is dark or light; layout is cinema, standard or side_panel. logoSize is small, medium or large: the logo is shown at most 32, 48 or 72 pixels high (56 for large on a phone); anything else is 422 validation_error. title is 1 to 120 characters, description up to 2,000, each of messages.starting, messages.ended and messages.password up to 300, siteLabel up to 40. siteUrl and each footer link's url must be https:// with no credentials, no spaces and at most 2,048 characters; footerLinks holds at most 3 entries of { "label", "url" } (label up to 40). All text is plain text. Anything else is 422 validation_error with fields.

PUT /watch-brand/logo takes the image itself as the body, with its Content-Type, up to 512 KB. The type is checked against the file's own bytes: PNG, JPEG or WebP, and it must agree with the declared type. A mismatch, an SVG, a GIF or an empty body is 422 logo_invalid; over the size is 413 logo_too_large. The answer is the WatchBrand. DELETE /watch-brand/logo answers 204. Changes appear in the audit trail as watch_brand.updated (its detail.changed lists the fields), watch_brand.logo_updated and watch_brand.logo_deleted.

Watch domains

Your own hostnames for watch pages (admin key; how to set one up). POST /watch-domains takes { "hostname": "live.example.com" } and answers 202 with a WatchDomain; GET /watch-domains answers { "items": [WatchDomain] }, oldest first; GET /watch-domains/{id} one; DELETE /watch-domains/{id} answers 204. POST /watch-domains/{id}/check (no body) looks at the records now and answers 202 with the WatchDomain; at most once a minute per domain (429 domain_rate_limited, with Retry-After). A failed or detached domain starts again from pending_dns.

{ "id": "e5f6…", "hostname": "live.example.com", "unicodeHostname": "live.example.com", "kind": "subdomain", "state": "pending_dns", "failureReason": null,
  "cnameTarget": "watch-target.plycdn.net",
  "records": [
    { "type": "CNAME", "name": "live.example.com", "value": "watch-target.plycdn.net",
      "purpose": "Points your domain to your watch pages", "status": "found" },
    { "type": "CNAME", "name": "_acme-challenge.live.example.com", "value": "k3m…q7.dcv.plycdn.net",
      "purpose": "Lets us issue and renew your certificate", "status": "missing" } ],
  "verification": { "records": [ … the same records … ],
                    "checks": { "ownership": "missing", "routing": "found", "claim": "unknown", "certificate": "none" } },
  "lastCheckedAt": "…", "nextCheckAt": "…", "activeAt": null, "createdAt": "…", "updatedAt": "…" }

records are what to create at your DNS host, each with type, name, value, purpose (what it is for, in words to show people) and status (what the latest look saw: found, missing, elsewhere for a record that points somewhere else, or unknown before the first look). Keep both records for as long as you use the domain; the certificate is renewed through the second. kind is subdomain; a domain added before 7 October 2026 may be apex, and its records are a TXT at _plycdn.<hostname> (purpose "Proves your organization owns the domain") and the CNAME, as before. lastCheckedAt is the latest look and nextCheckAt the next one (null once failed or detached).

state is pending_dns, verifying, issuing_certificate, active, failed or detached; failureReason is dns_not_configured, hostname_in_use, certificate_failed, dns_record_removed, ownership_record_removed or provider_unavailable. Share links open on the hostname only while it is active. Refusals: 409 watch_domain_limit_reached (detail.limit: 5), 409 domain_exists (you already added it), 422 hostname_not_allowed (plycdn's own names and names that are not public), 422 watch_domain_apex_unsupported (a bare domain such as example.com: detail.message says what to do, and detail.suggestions lists www.example.com and live.example.com; use a subdomain and redirect the bare domain to it at your DNS provider), 422 validation_error for a hostname over 237 characters, and 404 watch_domain_not_found. Additions count against the same hourly and daily allowances as custom domains. Audit actions: watch_domain.added, .verified, .active, .failed, .detached, .deleted and .check_requested.

The watch routes. These two are for viewers. They need no key or token, are called from the viewer's browser, and answer to any website (Access-Control-Allow-Origin: *, no cookies). They are on the API address (https://api.plycdn.com), outside /api/content/v1, and a viewer is limited to 60 looks and 20 sessions a minute.

GET /api/watch/{code}
{ "title": "Town hall", "state": "starting", "needsPassword": false, "showRecording": true,
  "brand": { "logoUrl": "https://watch.plycdn.com/api/watch/brand/…/logo?v=2", "accentColor": "#c2410c", "backgroundColor": null, "theme": "dark", "layout": "standard",
             "title": "Town hall", "description": null, "messages": { "starting": "Starting soon", "ended": "This stream has ended", "password": "Enter the password to watch" },
             "siteUrl": "https://acme.example/", "siteLabel": "Visit Acme", "footerLinks": [ { "label": "Privacy", "url": "https://acme.example/privacy" } ],
             "logoSize": "medium" } }

brand is what the page draws: for each field the link's own value, else the brand's, else the built-in one (title is the live input's name, messages the three built-in sentences, layout standard; logoSize is the brand's, null when none is set, which the page shows as small). title at the top is the same resolved title. The logo is served from GET /api/watch/brand/{organizationId}/logo on the same host. On a watch domain the same two routes answer on your own hostname.

code is the last part of the link's url (22 letters and digits). state is starting (no stream yet), live, recording (the stream is over and its recording is ready to play on this link) or ended (the stream is over and there is nothing to play).

POST /api/watch/{code}/session
{ "password": "meeting-2026" }

Send an empty object when the link has no password. While the stream is live the answer is the broadcast links, as in Live playback links; for a recording it carries the recording's playlist:

{ "state": "live", "url": "https://acme-events.plycdn.net/v/a91c…/ll/master.m3u8?token=…",
  "fallbackUrl": "https://acme-events.plycdn.net/v/a91c…/master.m3u8?token=…", "latency": "low",
  "expiresAt": "…", "captions": [ { "language": "en", "url": "https://…" } ] }
{ "state": "recording", "url": "https://acme-events.plycdn.net/v/a91c…/master.m3u8?token=…", "expiresAt": "…", "captions": [] }

fallbackUrl and latency come only with live. protection (as in the playback link) comes when the stream or recording is protected. The links last 15 minutes: ask again before expiresAt (the watch component does). The refusals are:

Status Code When
404 watch_link_not_found The code is unknown, or the link is turned off, expired or deleted, or its stream can no longer be watched. Every such case answers the same
409 watch_not_started The stream has not started (retryable: ask again in a few seconds)
409 watch_ended The stream is over and the link has no recording to show
401 watch_password_required The link has a password and none, or a wrong one, was sent
429 watch_password_attempts Five wrong passwords from one viewer in 15 minutes (retryable). Retry-After and detail.retryAfter give the seconds to wait; the right password is refused too until then

The body of the other watch requests is limited to 1 KB and carries only password (422 validation_error for anything else).

Live webhooks

live.connected, live.started, live.disconnected, live.ended, live.failover, live.destination_failed and live.ad_break can be subscribed to like the video events. Their data carries ids, not a video (liveInputId and streamId, plus protocol, reconnected, delivery, quality, reconnectWindowSeconds, endReason, durationSeconds and recording as the Video guide lists). The three newer ones carry:

Event Sent when data besides liveInputId and streamId
live.failover With backup ingest, the stream switched publisher; once per switch from, to (each primary or backup)
live.destination_failed A restream destination failed three times in five minutes; once per episode, never with its address or key destinationId, name, error (a destination's lastError)
live.ad_break An ad break started breakId, durationSeconds, startedAt

The request, signature, retries and log are as for every webhook.

Live usage

GET /usage/resources reports live streaming against the library: live_source_minutes, live_sd_minutes, live_hd_minutes and live_fhd_minutes (unit minutes, one per quality a stream is counted at), live_realtime_viewer_minutes (unit minutes, counted per viewer) and live_caption_minutes (unit minutes, counted per caption language while captions ran), each with the region as dimension. The same quantities are your statement's Live streaming and Live captions lines; restreaming is counted by the minute for each destination and shown as Restreaming on the statement (Plans and prices).

Webhooks

POST /api/content/v1/webhooks    # 201
{ "url": "https://api.customer.example/plycdn", "events": ["video.ready", "video.failed"], "description": "LMS" }
{ "id": "…", "url": "https://api.customer.example/plycdn", "events": ["video.ready", "video.failed"],
  "description": "LMS", "active": true, "secretRotatedAt": null, "previousSecretExpiresAt": null,
  "createdAt": "…", "updatedAt": "…",
  "secret": "pwhs_…" }

That is the Webhook shape; secret is in the create answer only, shown once. url is https:// only, at most 2048 characters (anything else is 422 validation_error, fields [["body","url"]]). It is 400 webhook_url_invalid unless it is printable ASCII (write an international name in its xn-- form and percent-encode the path), on port 443, without credentials (user:password@), and its name resolves to public addresses only (not private, local, link-local, multicast or otherwise non-public); the answer never says which. events is one to 20 of video.playable, video.ready, video.failed, live.connected, live.started, live.disconnected, live.ended, live.failover, live.destination_failed, live.ad_break and signing_profile.changed; an unknown event, or webhook.ping, is validation_error with its index. description is optional, up to 200 characters. An organization has at most 10 endpoints (409 webhook_limit_reached). Endpoints belong to one organization: a sub-organization's events go to its own endpoints only.

Repeating the create with the same Idempotency-Key answers the same endpoint with the same secret while that secret is still the endpoint's current one. After a rotation the repeat answers the endpoint as it is now, without secret (the rotation's answer carried the new one); after a delete it is 404 webhook_not_found.

GET    /api/content/v1/webhooks
GET    /api/content/v1/webhooks/{webhookId}
PATCH  /api/content/v1/webhooks/{webhookId}
DELETE /api/content/v1/webhooks/{webhookId}               # 204
POST   /api/content/v1/webhooks/{webhookId}/secret/rotate
POST   /api/content/v1/webhooks/{webhookId}/ping           # 202
GET    /api/content/v1/webhooks/{webhookId}/deliveries?state=failed&cursor=…&limit=50
POST   /api/content/v1/webhook-deliveries/{deliveryId}/redeliver    # 202

GET /webhooks answers {"items": [ …Webhook… ]}. PATCH takes url, events, description and active: a field left out is unchanged, and "description": null removes the description. "active": false pauses the endpoint: nothing is sent to it, and a delivery due while it is paused (a ping included) ends failed with lastError null and no lastStatus, since no request was made. An unknown, deleted or another organization's endpoint answers 404 webhook_not_found.

secret/rotate answers the new secret, shown once, and when the old one stops signing:

{ "secret": "pwhs_…", "previousSecretExpiresAt": "…" }

For 24 hours every delivery is signed with both secrets.

signing_profile.changed is sent when a bucket's or library's signing key, domains (its own, or a shared address's routes to it), link settings, serial playback or watermark requirement changed. The server packages use it to refresh their cached signing settings. Its data is bucketId (the bucket or library), kind (bucket or library) and reasons (any of key_rotated, domains_changed, delivery_changed, serial_changed, scheme_changed, watermark_changed):

{"id":"…","type":"signing_profile.changed","createdAt":"…","organizationId":"…","data":{"bucketId":"…","kind":"library","reasons":["key_rotated"]}}

Re-read the signing profile (GET /buckets/{bucketId}/signing-profile) when it arrives if you sign links from it yourself.

ping queues a real, signed webhook.ping to the endpoint ("data": {"webhookId": "…"}) and answers the delivery. deliveries lists an endpoint's deliveries newest first (state is pending, succeeded or failed; limit 1 to 200, 50 when omitted; follow nextCursor). The log keeps the last 90 days: a finished delivery (succeeded or failed) is removed 90 days after its createdAt. A page:

{ "items": [
  { "id": "…", "webhookId": "…", "eventId": "…", "event": "video.ready", "state": "pending",
    "attempts": 2, "nextAttemptAt": "…", "lastStatus": 503, "lastError": "http_error", "lastDurationMs": 412,
    "lastAttemptAt": "…", "deliveredAt": null, "createdAt": "…",
    "payload": { "id": "…", "type": "video.ready", "createdAt": "…", "organizationId": "…", "data": { "video": { "…": "…" } } } } ],
  "nextCursor": null }

nextAttemptAt is null unless the delivery is pending. redeliver sends a finished (succeeded or failed) delivery once more with the same id and body, and answers it pending. A delivery still pending, or one whose endpoint is paused, is answered as it is (202, unchanged): resume the endpoint first. An unknown delivery, one whose endpoint is deleted, or another organization's answers 404 webhook_delivery_not_found.

ping, redeliver and secret/rotate together are limited to 60 an hour for your account (across its organizations; refused calls count): past that, 429 rate_limited with Retry-After, and nothing is sent or changed.

What we send. POST <url> with a compact JSON body {"id": <event id>, "type": <event>, "createdAt": <ISO 8601>, "organizationId": <uuid>, "data": {"video": <Video shape>}} (for the live.* events data carries the stream's ids and facts instead, see Live webhooks) and the headers Content-Type: application/json, User-Agent: plycdn-webhooks/1, Plycdn-Event, Plycdn-Delivery (the delivery id, the same on every retry), Plycdn-Webhook (the endpoint id) and Plycdn-Signature: t=<unix seconds>,v1=<hex>, where v1 = hex(HMAC-SHA256(key = utf8(secret), msg = utf8(t) + "." + body)) over the exact body bytes sent. During a rotation's 24 hours a second v1, signed with the previous secret, follows the first. Verify before trusting a request, and refuse a t more than 5 minutes from your clock (see Webhooks in Video and webhooks).

Answers and retries. Any 2xx within 10 seconds is success. Anything else is retried after 1, 5, 15 and 30 minutes, then 1, 2, 4, 8, 12, 24 and 24 hours: 12 attempts over about 3.1 days, then failed. 410 Gone fails the delivery at once. Redirects are not followed, and your response body is never read or kept. Each attempt's outcome is in lastError (with the answer's status in lastStatus):

lastError Meaning
timeout No answer within 10 seconds
connection_failed The connection was refused or dropped
tls_failed The TLS handshake failed (an invalid or untrusted certificate)
dns_failed The endpoint's name did not resolve
address_forbidden The name resolved to a private, local or otherwise non-public address; nothing was sent
redirect_not_followed The endpoint answered with a redirect
http_error The endpoint answered with a status other than 2xx (lastStatus)

34Match navigation in your own interface

A grouped search (group: 'file') returns one result per file, with every place it matched in moments. The Angular preview moves between them itself ("Moving between matches in the preview" in the Integration guide). An interface of your own can use the same helpers, exported by both browser packages, @plycdn/content-search and @plycdn/content-search-react:

Helper Returns
matchesInOrder(result) The result's moments in file order: by time (playFromSeconds, else startSeconds), else page, slide, sheet and row, line, then paragraph. Matches at the same place keep the order they came in. A result without moments is a single match: the result itself.
matchIndex(ordered, location) The position of the match at location, or -1.
adjacentMatch(ordered, index, step) The match at index + step (step is 1 or -1), or undefined past either end. From -1, the next match is the first.
markerPositions(ordered, duration) { index, fraction, seconds } for each timed match within 0..duration; none until duration is finite and above zero.
matchPointer(moment, labels) The short name a button shows — 7:55, page 4, slide 3, Sheet1 row 12, line 40 — from the pointer* labels; a match with none of those is named by its title or heading, else "Passage n".

Two matches can share a location (two passages in the same second): after the first lookup, keep the position you moved to rather than looking it up again by location.

The labels' defaults are in DEFAULT_LABELS: matchPrevious Previous: {pointer}, matchNext Next: {pointer}, matchPosition Match {n} of {total}, matchAnnounce Match {n} of {total}, {pointer}, pointerTime {time}, pointerPage page {page}, pointerSlide slide {slide}, pointerRow row {row}, pointerSheetRow {sheet} row {row}, pointerLine line {line}, and names for player controls (play, pause, mute, unmute, volume, seek, back10, forward10, speed, quality, qualityAuto, captions, captionsShort, captionsOff, fullscreen, exitFullscreen). Translate by spreading your own over them.

Previous / Next and seek-bar markers in React (position the track relative and its buttons absolute):

import { useState } from 'react';
import { adjacentMatch, DEFAULT_LABELS as L, markerPositions, matchesInOrder, matchIndex, matchPointer,
  type SearchResult } from '@plycdn/content-search-react';

const fill = (t: string, v: Record<string, string | number>) => t.replace(/\{(\w+)\}/g, (_, k: string) => String(v[k] ?? ''));

export function Matches({ result, duration, seek }: { result: SearchResult; duration: number; seek: (seconds: number) => void }) {
  const ordered = matchesInOrder(result);
  const [at, setAt] = useState(() => matchIndex(ordered, result.location));
  const go = (i: number) => { const m = ordered[i]; if (!m) return; setAt(i); seek(m.location.playFromSeconds ?? m.location.startSeconds ?? 0); };
  const prev = adjacentMatch(ordered, at, -1), next = adjacentMatch(ordered, at, 1);
  return (<div>
    <div className="track">{markerPositions(ordered, duration).map(m => (
      <button key={m.index} style={{ left: `${m.fraction * 100}%` }} onClick={() => go(m.index)}
        aria-label={fill(L.matchAnnounce, { n: m.index + 1, total: ordered.length, pointer: matchPointer(ordered[m.index]!, L) })} />))}</div>
    <button aria-disabled={!prev} onClick={() => go(at - 1)}>{fill(L.matchPrevious, { pointer: prev ? matchPointer(prev, L) : '—' })}</button>
    <span>{fill(L.matchPosition, { n: at + 1, total: ordered.length })}</span>
    <button aria-disabled={!next} onClick={() => go(at + 1)}>{fill(L.matchNext, { pointer: next ? matchPointer(next, L) : '—' })}</button>
  </div>);
}

35Public pricing

Our list prices and the regions we offer are published without signing in, so a page of your own can show them without copying numbers that may change:

GET https://api.plycdn.com/api/public/pricing

No key or session is needed, and nothing about your account is in the answer. It is read-only, cached for a few minutes, and limited per address. If it cannot be produced right now it answers 503 with the code pricing_unavailable; try again shortly.

{
  "asOf": "2026-10-01",
  "currencies": ["INR", "USD"],
  "plans": [
    { "code": "starter", "name": "Starter",
      "features": [{ "code": "analytics", "label": "Search analytics" }],
      "limits": { "maxAssets": 2000, "storageRequestsPerMinute": 36000 },
      "dashboardSearchAllowance": 100 }
  ],
  "metrics": [{ "code": "searches", "label": "Searches", "unit": "searches", "dimension": null }],
  "prices": {
    "starter": { "INR": { "searches": [
      { "dimension": null, "tiers": [{ "from": 0, "unitPrice": 0.5, "included": 0 }] } ] } }
  },
  "regions": [
    { "code": "mumbai", "name": "Mumbai, India", "country": "IN", "strictResidency": true,
      "services": { "storage": true, "video": true, "search": true } }
  ]
}
  • prices is keyed by plan code, then currency, then metric code. Each metric lists one entry per dimension (a region or delivery area, with its key and display label; null when the price does not depend on one), and each entry lists its tiers: from from units a month, each unit costs unitPrice (in the currency's main unit), after the first included units.
  • Only list prices in force today are shown, for plans you can choose, and only for regions you can use. Enterprise terms are agreed with us.
  • strictResidency says whether a region can keep a bucket's processing inside its country.

36Observability

Logs, metrics and traces kept for your organization: you send them with an ingest key, and read them back with these routes. How to send, the tables, limits and worked examples are in the Observability guide. Every route here needs an admin API key (admin_key_required, 403, with a standard key), and the plan feature observability; without it they answer 403 not_included_in_plan, except reading the settings and, from them, shortening the retention or stopping the archive. Until a region is chosen the data routes answer 409 observability_not_enabled. All are under /api/content/v1, with X-Organization-Id as elsewhere. The one exception is the six read routes (query, validate, reference, export, tail and trace), which also accept a read-only query key (plyq_…, below) in place of an admin key.

Settings

GET   /api/content/v1/observability/settings
PATCH /api/content/v1/observability/settings
{ "region": "mumbai", "retentionDays": 90, "archiveBucketId": "6f5c1c9e-..." }

GET answers { "enabled": false } until a region is chosen, then:

{ "enabled": true, "region": "mumbai", "retentionDays": 90, "archiveBucketId": null,
  "enabledAt": "2026-10-16T09:30:00Z", "updatedAt": "2026-10-16T09:30:00Z",
  "endpoints": { "otlpHttp": "https://in-mum.telemetry.plycdn.com:4318", "otlpGrpc": "in-mum.telemetry.plycdn.com:4317",
                 "prometheusRemoteWrite": "https://in-mum.telemetry.plycdn.com:4318/api/v1/write",
                 "ndjson": "https://in-mum.telemetry.plycdn.com:4318/v1/ndjson",
                 "syslog": "in-mum.telemetry.plycdn.com:6514", "fluentForward": "in-mum.telemetry.plycdn.com:24224" } }

PATCH takes any of region, retentionDays and archiveBucketId (a bucket id, or null to stop archiving) and answers the same shape. The first PATCH with a region turns observability on. retentionDays is one of 7, 15, 30, 90, 180 or 365, up to your plan's limit (plan_limit_reached, 403), and defaults to 30 when enabling. The region cannot change once chosen (observability_region_fixed, 409) and must offer observability (region_not_available, 400). The archive bucket must be one of your active file buckets in the same region (archive_bucket_invalid, 400). Shortening the retention deletes older data permanently (copies in our encrypted backups expire within 15 days); lengthening it keeps only what is still held. Settings changes are in the storage audit log (observability.settings_updated, and observability.retention_changed with the old and new days).

Ingest keys

GET    /api/content/v1/observability/ingest-keys
POST   /api/content/v1/observability/ingest-keys           { "name": "checkout-service" }
DELETE /api/content/v1/observability/ingest-keys/{id}

GET answers { "items": [{ "id", "name", "prefix", "createdAt", "revokedAt" }] }, newest first. POST answers 201 with the same fields plus key (plyt_ and 32 characters), in this answer only, with Cache-Control: no-store; name is 1 to 100 characters. At most 20 keys are active (ingest_key_limit_reached, 409). DELETE answers 204, an unknown id is ingest_key_not_found (404), and a revoked key stops being accepted within a minute. The audit log records observability.key_created and observability.key_revoked.

Query keys

A query key is a read-only key for the six read routes, optionally held to a row filter: it can read only the rows the filter lets through, whatever statement it sends. Use one to give a customer, a partner, a support engineer or a team access to part of your data, or an exporter a key that can read and nothing else. Step by step, with code: Give a customer, a team or a partner access to part of your logs.

GET    /api/content/v1/observability/query-keys
POST   /api/content/v1/observability/query-keys
{ "name": "acme support", "rowFilter": { "all": [
    { "source": "attribute_or_resource", "key": "tenant", "in": ["ACME"] },
    { "source": "service", "notIn": ["billing"] } ] } }
DELETE /api/content/v1/observability/query-keys/{id}

These three need an admin API key or a dashboard session (a standard key is refused with admin_key_required, 403; a query key with query_key_not_allowed, 403), and act on the organization named by X-Organization-Id. POST also needs the plan feature observability (not_included_in_plan, 403).

  • name is 1 to 100 characters. rowFilter is optional: a key without one is a read-only key over the whole organization.
  • GET answers { "items": [{ "id", "name", "prefix", "rowFilter", "organizationId", "createdAt", "lastUsedAt", "revokedAt" }], "activeLimit": 200 }, newest first, revoked keys included. lastUsedAt is updated about once a minute. rowFilter is shown in one spelling (values sorted without repeats, nested groups of the same kind merged), so it can differ from what you sent while meaning the same. POST answers 201 with the same fields plus key (plyq_ and 32 characters), in this answer only, with Cache-Control: no-store. plycdn keeps a one-way fingerprint and the first eight characters (prefix).
  • DELETE answers 204; an unknown id is query_key_not_found (404); revoking one already revoked changes nothing. Revoking takes effect on the next request, and a log tail or download the key has open is cut within 30 seconds.
  • At most 200 keys are active per organization (query_key_limit_reached, 409). They are separate from API keys (your two usable API keys are untouched) and from ingest keys.
  • A key made with an admin API key stops working when that API key is deactivated or expires. A key made in the dashboard lives until it is revoked.
  • Creating and revoking are in your account audit log as observability.query_key_created and observability.query_key_revoked.

The row filter. A filter is a condition, or a group of conditions:

{ "all": [ { "source": "resource", "key": "deployment.environment", "in": ["production"] },
           { "any": [ { "source": "attribute", "key": "tenant", "in": ["ACME", "GLOBEX"] },
                      { "source": "service", "in": ["checkout"] } ] } ] }
Part Rule
Condition source, key (not for service) and either in or notIn, never both.
source resource reads the resource attributes; attribute reads the record's own attributes (a log's, a span's, or a metric point's); attribute_or_resource uses the record's own attribute when it has the key and its resource attribute otherwise; service matches the service name and takes no key.
in The row matches when the value is one of the listed values. A row without the attribute does not match.
notIn The exact opposite of the same condition with in. A row without the attribute matches notIn; for attribute_or_resource, a row with neither the attribute nor the resource attribute matches too.
Group { "all": [...] } (every part) or { "any": [...] } (at least one), nested at most 3 levels deep.
Limits 1 to 8 conditions in the whole filter; 1 to 1,000 values in all; a key is 1 to 128 characters of letters, digits and . _ - / :; a value is 0 to 256 characters of text; the filter is at most 64 KiB once written out.

For attribute_or_resource the record's own attribute wins: a record whose own tenant is GLOBEX is outside ["ACME"] even when its resource says ACME. A filter that breaks a rule is validation_error (422), and the detail names the rule.

Using a key. Send it where an API key goes, on the six read routes only:

POST /api/content/v1/observability/query
Authorization: ApiKey plyq_YOUR_KEY
  • It works on POST /observability/query, /validate and /export, GET /observability/reference, /logs/tail and /traces/{id}; the statement, the limits and the answers are the same, and the filter is applied to everything the statement reads, however it is written. A statement that tries to read outside the filter returns no rows or query_invalid.
  • Everywhere else, including the settings, keys, volumes, slow queries and archive status, it is refused with 403 query_key_not_allowed. An unknown or revoked key is 401, as an API key is.
  • X-Organization-Id may be left out, or must be the key's own organization.
  • A filtered key's answers carry elapsedMs only: stats.readRows and stats.readBytes are null. What a filtered key reads is counted in your organization's usage and read allowance like any other read.
  • A trace is found only through rows in scope: a filtered key learns nothing about traces outside its filter.
  • Its statements share your organization's limits: when all of them are in use the answer is query_busy (429, retryable).

Query

POST /api/content/v1/observability/query
{ "sql": "SELECT count() FROM obs.logs WHERE ServiceName = {svc:String} AND Timestamp >= {from:DateTime64(3)}",
  "params": { "svc": "api" }, "from": "2026-10-16T00:00:00Z", "to": "2026-10-16T12:00:00Z" }

sql is one read-only statement (SELECT, WITH … SELECT, DESCRIBE or EXPLAIN) of up to 65,536 characters over the tables obs.logs, obs.spans, obs.trace_ids, obs.metrics_gauge, obs.metrics_sum, obs.metrics_histogram, obs.metrics_exponential_histogram and obs.metrics_summary. params (up to 256, together at most 49,152 bytes counting names and URL-encoded values) fills {name:Type} placeholders; from and to (ISO 8601) are always available as {from:DateTime64(3)} and {to:DateTime64(3)} and default to the last hour. Answer:

{ "columns": [{ "name": "count()", "type": "UInt64" }], "rows": [["12"]], "stats": { "readBytes": 2048, "elapsedMs": 3.5 } }

64-bit whole numbers (UInt64, Int64) arrive as strings. A statement runs for at most 30 seconds (up to 120 where your account's ceiling was raised and the query asks for it), reads at most 50 GB and returns at most 100,000 rows. Refusals: query_invalid (400: not one read-only statement over your tables, or a mistake in the SQL; the detail says what), query_too_expensive (400), query_timeout (400).

dialect is sql (the default) or kql: with kql, sql holds one KQL (Kusto Query Language) query, such as logs | where Timestamp > ago(1h) | summarize count() by ServiceName, over the same tables (by name: logs, spans, …, or obs.logs), with the same limits and the same answer. A second statement, SQL mixed into the query, a set or settings change, a table function or anything outside your tables is query_invalid (400), as is a KQL mistake. See Asking questions with KQL.

maxExecutionMs (optional, 1,000 to 30,000 for a query, or up to your account's raised ceiling of at most 120,000: the reference's limits.queryMaxExecutionMs) sets the time a statement may run; outside the range it is validation_error (422). In SQL, SETTINGS max_execution_time = N (seconds) does the same. stats are readBytes, readRows and elapsedMs; for a query key with a row filter (below) readRows and readBytes are null and only elapsedMs is set, in query, validate, tail and trace answers alike. More refusals: query_busy (429, retryable, Retry-After 1 second: eight of your statements are already running) (or as many as your account's raised limit, the reference's limits.concurrentStatements) and read_quota_exceeded (429, retryable, Retry-After is the seconds until the hourly allowance renews, 1 to 3,600; Starter only, as Growth and Enterprise have no hourly read limit). All the limits: Read limits.

Validate and reference

POST /api/content/v1/observability/validate
{ "dialect": "kql", "sql": "logs | where Timestamp > ago(1h) | summarize count() by ServiceName" }

The body is a query's (maxExecutionMs is ignored). Answer 200: { "valid": true, "dialect": "kql", "columns": [...], "stats": {...} }, or { "valid": false, "dialect": "kql", "error": { "code": "query_invalid", "message": "...", "line": 1, "column": 8 } }: a query that does not check out is an answer, not an error. line and column point into your own text and are null when they cannot be told (a KQL query that plycdn rewrote before checking it). Checking reads no table data, except what a scalar subquery (SQL) or an in (<query>) (KQL) needs to work out its value, and WITH TOTALS reads a little; the answer's stats show what was read, and that counts as read like any query. Check a query before running it.

GET /api/content/v1/observability/reference answers { "kql": { "operators", "functions", "aggregations" }, "tables", "errors", "limits" }: every KQL entry has name, syntax, description and example; tables list their columns; errors are code, status, retryable and meaning; limits are the numbers in Read limits, with hourlyReadLimited: true when your organization is held to hourlyReadBytes (Starter), false when it has no hourly read limit (Growth and Enterprise). It needs an admin key and a plan with observability, but not that it is switched on. KQL reference.

Export

POST /api/content/v1/observability/export
{ "sql": "SELECT * FROM obs.logs WHERE Timestamp >= {from:DateTime64(3)}", "format": "parquet" }

The body is a query's (dialect included) plus format, ndjson (the default) or parquet. The answer is the file itself, application/x-ndjson or the Parquet media type, with a Content-Disposition filename, streamed as it is produced: no row limit, 10 minutes and 10 GB at most (maxExecutionMs, 1,000 to 600,000, lowers the time), and two at a time (export_busy, 429). The answer carries an X-Query-Id header: look the statement up with GET /observability/slow-queries?queryId=<id> a few seconds after it ends to see what it read. Refusals come before the first byte. If the download fails part-way the connection is dropped, so a client sees an incomplete transfer: the server packages raise an error. Discard the file and run the export again.

Tail logs

GET /api/content/v1/observability/logs/tail?service=checkout&severity=17&contains=declined&cursor=1760607667120

A text/event-stream. service, severity (1 to 24, and above), contains (up to 8 words) and cursor are all optional. Events: logs ({ "rows": [...], "cursor": "…" }, each row with timestamp, service, severity, severityNumber, body, traceId, spanId, attributes, resource), end ({ "cursor": "…" }, after 300 seconds) and error (the body of an error response, then the stream ends); : heartbeat comment lines arrive every 15 seconds. The stream runs about 8 seconds behind real time. Resume from the cursor of the last event you received, including after an end. Logs stamped more than a day before they arrive are stored and queryable but not tailed. Four tails run at once (tail_busy, 429, with Retry-After).

Trace

GET /api/content/v1/observability/traces/{traceId} (32 lower-case hexadecimal characters) answers { "traceId", "spans": [...] }, oldest first, up to 10,000 spans: each has start, spanId, parentSpanId, name, kind, service, durationNs (a string), statusCode, statusMessage, attributes, resource, events and links. An unknown trace is trace_not_found (404).

Volumes

GET /api/content/v1/observability/volumes?from=2026-10-01&to=2026-10-16 (dates; the last 30 days by default, at most 400, else validation_error):

{ "retentionDays": 30, "days": [{ "day": "2026-10-16", "rows": 1204331, "ingestedGb": 0.84, "retainedGb": 12.6, "scannedGb": 0.31,
  "complete": true, "receivedGb": 0.31,
  "rejected": [{ "signal": "logs", "reason": "older_than_retention", "records": 1200, "requests": null }],
  "signals": { "logs": { "rows": 1000000, "receivedGb": 0.25, "ingestedGb": 0.7, "retainedGb": 10.1 },
               "metrics": { "rows": 200000, "receivedGb": 0.05, "ingestedGb": 0.12, "retainedGb": 2.3 },
               "traces": { "rows": 4331, "receivedGb": 0.01, "ingestedGb": 0.02, "retainedGb": 0.2 } } }] }

receivedGb is the size of your requests as sent (not billed); ingestedGb is the size of the rows as plycdn stores them (billed); retainedGb is a daily level of what was being kept (a month's sum is GB-days); scannedGb is what your queries, exports and tails read. signals splits rows, received, stored and kept into logs, metrics and traces (the totals are their sum); what was read is not split. They are the quantities of the meters telemetry_ingest_gb (data stored from what you sent), telemetry_stored_gb_months (data kept) and telemetry_scanned_gb (data read) on your usage and statement. complete is true once the day has ended and every figure has counted it (after 00:05 UTC the next day); today never is. rejected lists what was not kept, by signal and reason (older_than_retention, counted in records; ingest_invalid, ingest_too_large and not_stored, counted in requests). Ask for today with from and to as today. Up to 400 days of history. Volumes, and what is billed, Refused and removed data.

Slow queries

GET /api/content/v1/observability/slow-queries?from=2026-10-16T00:00:00Z&minDurationMs=2000&limit=50 answers your organization's own finished queries (query, tail and trace calls, SQL and KQL; a download only when asked for by queryId) that took at least minDurationMs (default 1000; 0 for all), newest first. queryId returns the one statement with that id (an item's queryId, or the X-Query-Id of an export), whatever its duration. from and to (ISO 8601) default to the last 24 hours; from is at most 30 days ago. limit is 1 to 1000 (default 100); pass nextCursor back as cursor for the next page (null on the last). A backwards range, one reaching back more than 30 days or an unknown cursor is validation_error (422).

{ "items": [{ "queryId": "6b1f3c1e-8a52-4c43-9f0e-2d7a1a5c9e10", "at": "2026-10-16T09:41:07.120344Z", "durationMs": 4210, "readRows": 182000000, "readBytes": 9830400000,
  "resultRows": 12, "memoryBytes": 512000000, "dialect": "kql", "failed": false, "errorCode": null,
  "query": "logs | where Body contains 'timeout' | summarize count() by ServiceName", "queryTruncated": false }],
  "nextCursor": null }

at is when the query finished. A failed query has failed: true and errorCode, the code it was answered with (query_invalid, query_too_expensive, query_timeout or observability_unavailable). query is the first 4,096 characters of the text (queryTruncated says whether it was cut); params values are not shown.

Archive status

GET /api/content/v1/observability/archives?from=2026-11-01&to=2026-11-09

What the nightly archive (Archiving to your own bucket) did, day by day and signal by signal. Both dates are inclusive and default to the last 30 days; the range is at most 92 days, else validation_error (422). An admin key or a dashboard session; a query key is refused with query_key_not_allowed.

{ "archiveBucketId": "6f5c1c9e-...", "archiveSince": "2026-11-01",
  "days": [{ "day": "2026-11-08",
    "signals": [
      { "signal": "logs", "state": "written", "key": "observability/logs/2026/11/08/logs-20261108.parquet", "bytes": 9499, "rows": 25,
        "sha256": "9f2c…", "reason": null, "completedAt": "2026-11-09T00:21:07Z" },
      { "signal": "spans", "state": "empty", "key": null, "bytes": null, "rows": 0, "sha256": null, "reason": null, "completedAt": "2026-11-09T00:21:09Z" },
      { "signal": "metrics_sum", "state": "failed", "key": null, "bytes": null, "rows": null, "sha256": null,
        "reason": "engine_unavailable", "completedAt": null }],
    "manifest": { "state": "written", "key": "observability/manifests/2026/11/08/manifest-20261108.json", "bytes": 612, "sha256": "ab41…", "reason": null } }] }
  • Days are newest first, and only days that have rows are listed. archiveBucketId and archiveSince are the bucket and the first day archived, or null when archiving is off.
  • state is pending (not done yet), written, empty (nothing to write that day, rows is 0) or failed (reason says why: archive_bucket_invalid, engine_unavailable, storage_unavailable, or a short code). sha256 is that of the file's bytes, in hexadecimal.
  • manifest is one small JSON file written to the same bucket once every signal of the day is settled, whatever the outcome, listing each signal with its state, file, size, rows and sha256. It is null for days archived before manifests existed. A day whose bucket was no longer usable shows failed with archive_bucket_invalid: fix the bucket in Monitoring & logs → Settings.

Sending data

Ingest keys send to the addresses in endpoints (OpenTelemetry over HTTP on port 4318 and gRPC on 4317, Prometheus remote write 2.0, and JSON lines at /v1/ndjson) with Authorization: Bearer plyt_… or X-Plycdn-Ingest-Key. These are not routes of /api/content/v1; their refusals are ingest_key_invalid (401), ingest_wrong_region, not_included_in_plan, organization_suspended and ingest_refused (403), ingest_invalid (400, naming the line for JSON lines), ingest_too_large (413), rate_limited (429, with Retry-After) and observability_unavailable (503, retryable). OpenTelemetry accepts gzip and zstd, JSON lines gzip: the 5 MB limit is on the bytes as sent and a request may be up to 20 MB once decompressed (Sending compressed data). A request is answered once it is safely queued, so there is no per-record partial success (why). See Sending data.

37Integrations: Logthread

Send an organization's storage request log, video and live events, and daily delivery totals to a Logthread workspace. Step by step, with code in every server package: Send your plycdn activity to Logthread. The three routes need an admin API key (admin_key_required, 403, with a standard key) and act on the organization named by X-Organization-Id: a sub-organization has its own connection. Under /api/content/v1.

Route Does
GET /integrations/logthread Reads the connection.
PUT /integrations/logthread Connects with an ingest key, replaces the key, or changes which activity is sent.
DELETE /integrations/logthread Disconnects and forgets the key. 204; the same when not connected.

PUT body

Field Type Notes
ingestKey string, 8 to 512 characters A Logthread ingest key. Required while not connected. It is checked with Logthread before it is kept. Leave it out to change signals only.
signals object storage, video and delivery, each a boolean. A field left out keeps its value (on for a new connection).

Answer (GET and PUT; the key is never returned)

Field Type Notes
connected boolean false when not connected or disconnected.
status string connected, paused (Logthread asked plycdn to wait; sending resumes by itself), disconnected (Logthread refused the key: connect with a new one) or not_connected.
keyHint string or null The last four characters of the key.
signals object storage, video, delivery: which activity is sent.
connectedAt string or null When it was connected (ISO 8601).
lastExport object storage, video, delivery: when each last arrived, or null.
lastError string or null The last problem in a word: key_rejected, workspace_suspended, daily_quota_exceeded, rate_limited, unreachable or batch_refused. The next batch that arrives clears it.
pausedUntil string or null While paused, when sending tries again.
workspaceName string or null The workspace's name when connected in one click in the dashboard.
connectedVia string or null key (an ingest key) or connect (one click).
oneClickAvailable boolean Whether the dashboard offers Connect to Logthread.

What arrives in Logthread: logs with service.name plycdn-storage (the request log of your S3 and Azure storage endpoints: status, duration_ms, bytes_in, bytes_out, bucket, aborted…; attr.key in queries) and plycdn-video (the events your webhooks receive), and the daily gauges plycdn.delivery.gb and plycdn.delivery.requests from plycdn-delivery (one point per day at 00:00 UTC; quantities only). Every record carries cloud.provider = plycdn, cloud.account.id and cloud.account.name. Delivery is best effort with retries; records older than 72 hours are dropped rather than sent late. Errors: logthread_key_rejected (422), logthread_unreachable (503, retryable), logthread_connect_failed (422) and validation_error (422, no key while not connected); see Errors.

38Errors

Errors are JSON with a stable code. Match on the code, never on the message. The one exception is a rate-limit rejection at the gateway, which carries a plain error message instead; creating keys and sub-organizations too fast answers rate_limited. Routes under /api (keys, sub-organizations, the audit) also carry a readable error: match on code.

Request bodies. The account routes (/api/sub-organizations, /api/account-audit) and the dashboard's own account and sign-in routes read at most 100 KB (413 payload_too_large). Request bodies are not accepted compressed (Content-Encoding) except on /api/content/v1 and the dashboard's content routes (/api/content-settings, /api/content-activity, /api/content-add, /api/content-admin, /api/content-connectors), and there only once the Authorization credential has verified: anywhere else, the dashboard's storage relay (/api/content-media) included, a compressed body is 415 unsupported_media_type. None of the SDKs compresses a request.

{ "code": "source_host_not_allowed", "retryable": false }

retryable: true means the same request may succeed later. Back off; do not retry in a tight loop. Validation errors (422, which add fields) and the refusals made at the gateway before a request reaches the service (a missing or invalid key, an organization your key does not cover, a rate limit) carry code without retryable: treat a missing retryable as false. Every response carries an X-Request-Id header, refusals included.

Code Status What to do
invalid_api_key 401 Check the key and that it has not been revoked or expired
api_key_required 401 No key in the Authorization: ApiKey header, or a key sent in the query string (refused on every route) or in a JSON request body (never read as a key). Send it in the header only
asset_not_found, job_not_found, import_not_found 404 Unknown id, or it belongs to another organization
asset_not_playable 404 GET /assets/{id}/playback: the file was not made searchable from one of your buckets or video libraries, or its bucket has address-locked links, or it is a protected recording, or no source can be played; play it from where it lives
validation_error 422 The body, path or query does not match the shape of the request. fields lists where each fault is — [["body","query"]] means query is missing, empty or too long. Where the value itself is safe to repeat - a storage host that is not a bare hostname - detail says what is wrong with it; for a custom domain's hostname, detail says what is wrong with its form (never repeating the value). The sub-organization routes answer fields with the first field at fault; their older field (that field's name) is still sent for older integrations: read fields
empty_query 400 A search needs a non-blank query. A query of only spaces passes the schema and is refused here
too_many_steps 422 More than 5 within steps. Remove one, or start a new search
selection_too_large 422 More than 1,000 documents in filter.assetIds (each counted once), or in a selection being saved as a collection. Select fewer
cursor_expired 410 The cursor is more than 15 minutes old. Start again from the first page with the same query, steps and filter
cursor_mismatch 422 The cursor belongs to another search - a different query, steps, filter, principals or organization - or was altered. Start again from the first page
payload_too_large 413 The body is too large: over 10 MiB on the content API (register a source URL rather than posting content), over 64 KiB on the dashboard's storage relay (/api/content-media), whose requests are all small JSON, or over 100 KB on the account routes (/api/sub-organizations, /api/account-audit) and the dashboard's own account and sign-in routes
invalid_content_length 400 The Content-Length header is missing or not a number. On a storage part upload, also a chunked body (Transfer-Encoding): a part must declare its exact length up front
invalid_source_url 400 A sourceUrl must be https, on port 443, with no embedded credentials and no #fragment
ambiguous_source_credentials 400 The URL carries a query string and a sasToken was supplied. Send the credential once, in one place
organization_required 400 The X-Organization-Id header is missing or not a UUID
organization_forbidden 403 The key does not cover that organization, or the sub-organization has been deactivated
organization_out_of_key_reach 403 This API key can't reach that organization. Use a key for that organization, or one that reaches the whole account (Developers → API keys). Also answered when a key for the main organization only changes settings, video settings or the watch page brand, which sub-organizations inherit
source_host_not_allowed 400 Add the host under settings, then register again
source_url_must_be_unsigned 400 Put credentials in sourceAccess, not in sourceUrl
source_access_mismatch 400 The access URL points at a different file
source_version_already_registered 409 That externalId and sourceVersion already exist
source_version_changed 409 The file changed in your storage; register the new version
source_version_unverifiable 409 Your storage returned no ETag; supply a sha256: version
source_access_expired 403 A stored link is no longer valid. Supply fresh access, or move the file to a callbackKey so it is renewed for you
source_callback_refused 403 Your access callback did not answer 200. Nothing needs to be sent to us — check that it is up and that it resolves that file's externalId. Retried automatically
callback_not_configured 400 At registration: you sent a callbackKey but no callbackUrl is set in your settings. Set it, then register again. (On a job it is 503: the settings no longer carry the callback)
organization_daily_limit 429 A protective daily limit on processing was reached; work resumes tomorrow. Contact us if you expect this volume
quota_exceeded 429 Not retryable until your quota is raised or the month resets. detail names the metric, used, quota and the reset date; for a limit your account set on one sub-organization it says so (Limits for each sub-organization)
file_too_large 413 Beyond the configured limit; GET /capabilities gives the sizes
unsupported_document_format 400 Convert to a supported format
ocr_required 400 No page of the document could be read, neither from its text nor as a scanned page
asset_busy 409 A job is already running for that asset; wait for it to finish
not_included_in_plan 403 That feature is not part of your plan — GET /plan says what is (the feature names are listed under What your plan includes)
serial_playback_requires_session 409 This library's videos play only through a playback session: POST /playback-sessions (the server packages' sign route does it for you)
serial_playback_needs_plycdn_links 409 This library can't turn on serial playback yet: contact support to move it onto serial playback, or create a new library with serial playback on
serial_playback_unavailable 409 A live stream's recording can't be played in a library with serial playback
serial_playback_busy 409 The library is being moved to another delivery network, so serial playback can't be turned on yet. Retryable: wait for Retry-After and send it again
progress_not_found 404 The viewer (resumeId) hasn't started this video, or was started over since and hasn't watched it again
playback_session_expired 410 A progress save for a session that has ended, or for a pass that isn't one plycdn gave, or a watermark renewal more than 120 seconds after the session ended: start a new session (the players do)
watermark_required 409 The library requires the viewer watermark, and this request can't draw it: a plain link (POST /sign with a videoId), a session without watermark, or a player that didn't say it draws it. Start a session with watermark ({} when you have no details) from a player that draws it (Viewer watermark)
watermark_proof_invalid 403 A watermark renewal's continues and watermarkProof don't match a session of this library and video, carry another viewer's details or resumeId, or renew a session already renewed. Final: stop, never start a fresh session instead (except once, when it answers the retry of a renewal that got no answer)
watermark_tampered 403 The player reported the watermark removed or hidden in two check-ins of this viewing (or of this resumeId within the hour). Final: stop playing
plan_limit_reached 403 Your plan's ceiling for that resource is reached
idempotency_key_required 400 Send an Idempotency-Key header on that write (see Retries under Practical notes for which writes need one)
idempotency_conflict 409 The same key was used for a different request
revision_conflict 412 The If-Match revision is stale, or a passageId names an earlier revision of the file; read or search again
collection_not_found 400 / 404 400 when registering a file against a collection that does not exist (create the collection first); 404 when you address a collection that does not exist
external_id_mismatch, name_mismatch 400 The body contradicts the id in the path
job_not_cancellable 409 The job already finished
transcript_not_ready 409 Indexing has not produced a transcript yet
content_not_ready 409 The file's first indexing has not finished, so it has no text to read yet (GET /assets/{assetId}/passages)
invalid_segment_ids 400 A correction referred to segments that are not in that transcript
too_many_principals, too_many_synonyms, filter_too_many_values, too_many_pages, package_too_many_entries 400 Beyond a documented ceiling — the detail says which
filter_value_not_scalar 400 A filter value must be a string, number or boolean
invalid_period 400 month is not YYYY-MM, a date is not YYYY-MM-DD, to is before from, or both month and from/to were given. detail says which
period_too_long 400 Usage covers at most 400 days per request
usage_unavailable 503 Retryable. Your usage figures cannot be computed right now — on /usage, /usage/daily, /usage/assets or /usage/quotas. Nothing about your request is wrong, and your searches, answers and indexing carry on as normal. Try again later, and contact us if it persists — we are alerted to it
processing_temporarily_unavailable 503 Retryable. A temporary problem on our side — on a search, an answer or any other call. Nothing about your request is wrong. Back off and try again; contact us if it persists — we are alerted to it. The same code on a job is explained under Why a file failed to index
processing_failed 502 Not retryable. A problem on our side that repeating the same request will not fix — nothing about your request is wrong. Contact us with the x-request-id; we are alerted to it
statement_not_found 404 That month has never been closed into a statement
invalid_callback 401 A connector's notifyUrl was altered or has been retired (see Instant sync from storage events)
invalid_metric 400 /usage/daily's metric is not one of your catalogue's metrics
invalid_breakdown 400 /usage/daily's breakdown is not organization
answers_not_configured 503 Written answers are not enabled for your account
credential_required 400 A connector needs an access token to read the source
connector_name_taken 409 Another connector already has that name
connector_not_found 404 Unknown, disabled, or another organization's
connector_kind_unsupported 400 That connector type is not available here
region_not_available 400 Storage — the region code doesn't exist, or isn't open yet; read GET /regions. Live streaming — creating an input in a library whose region does not offer it ("live": false in GET /regions)
bucket_not_found 404 Storage — unknown id, or it belongs to another organization
bucket_name_taken 409 Storage — bucket names are unique across plycdn; held for 90 days after a purge, and for good (for other accounts) if the bucket was ever public
bucket_not_active 409 Storage — the bucket is creating, failed, deleting or deleted; check state. Retryable only while creating (it becomes active on its own); otherwise retry, restore or recreate it
bucket_suspended 403 Storage — plycdn has taken the bucket down ("suspended": true): no uploads and no signed links until it is reinstated; listing, reading and deleting still work. Contact [email protected]
bucket_hostname_unavailable 503 Storage — could not allocate a default hostname for the bucket; retry the create. Retryable
certificate_pending — Storage — a bucket failureReason: provisioning ran out of attempts still waiting on the bucket's TLS certificate; retry
configuration_failed — Storage — a bucket failureReason: a delivery-settings change did not reach the edge after every attempt; the bucket keeps serving (or not) as before, and the next successful change clears it
no_cdn_capacity — Storage — a bucket failureReason: no delivery capacity could be reserved for provisioning; retry, or try again later
no_storage_capacity — Storage — a bucket failureReason: no storage capacity could be reserved for the bucket's region; retry, or try again later
migration_not_found 404 Move from another cloud — the bucket has no move (or it was never set up)
migration_already_running 409 Move from another cloud — the bucket already has a live move; change its key or old-link settings with PATCH, or close it (with { "confirm": true } while it is running) and start a new one to change the source
migration_state_conflict 409 Move from another cloud — the action does not fit the move's state (for example resuming a move that is not paused, or starting one that is not a draft)
migration_not_closable 409 Move from another cloud — keys we could not move or that failed exist, or the move has not completed (closing it stops reading the old cloud); look at GET .../migration/items?state=unmovable and ?state=failed, then close with { "confirm": true }
migration_source_unreachable 422 Move from another cloud — the source address cannot be reached from plycdn (not public, not resolving, or not answering), or old links are on and the endpoint is not https://<account>.blob.core.windows.net (where old links are checked); fix the endpoint and check again
old_links_need_private_bucket 422 Move from another cloud — legacyLinks: "azure_sas" on a bucket that is public or does not use plycdn links; old links (and the certificate made before the switch) need a private bucket with plycdn links. Move into such a bucket, or leave old links off
migration_credential_refused 422 Move from another cloud — the old cloud refused the credential (wrong, expired or without read and list access)
migration_credential_too_broad 422 Move from another cloud — an Azure SAS that can write or delete, or an account-wide SAS, is refused; create a container SAS with read and list only
bucket_not_ready 409 Move from another cloud — the bucket is not active yet; retryable while it is creating
bucket_not_supported 422 Move from another cloud — the bucket is a video library; only file buckets can move
invalid_key — Move from another cloud — a file's reason: the name has a character or shape plycdn does not allow (an empty folder name such as //, a . or .. folder, a backslash, a control or text-direction character); rename it in your old storage
reserved_key — Move from another cloud — a file's reason: the name starts with plycdn's reserved prefix; rename it
too_large — Move from another cloud — a file's reason: larger than the bucket's upload limit; raise the limit in the bucket's settings
type_not_allowed — Move from another cloud — a file's reason: the bucket's upload rules do not allow this file type; allow it in the settings
content_not_allowed — Move from another cloud — a file's reason: the content does not match the type it claims; fix the file
unsafe_content_type — Move from another cloud — a file's reason: it would run scripts when opened from your address, so it is not served there; serve it as a download or remove it
source_changed — Move from another cloud — a file's reason: it kept changing in your old storage while it was copied; it is copied again once it stops changing, or upload it to plycdn yourself
source_unreadable — Move from another cloud — a file's reason: your old storage refused or failed to give the file after every attempt; check the key has not expired and the file exists
deleted_by_customer — Move from another cloud — a file's reason: you deleted it in plycdn, so it is not copied back; nothing to do
domain_not_found 404 Storage — unknown domain id, or another organization's (a deleted domain is not found either)
domain_exists 409 Storage — this organization already has that hostname, in any spelling; use the existing domain (GET /domains) or delete it first
domain_limit_reached 409 Storage — the bucket already has 8 domains; delete one first
domain_rate_limited 429 Storage — too many domain additions for your account (20 an hour and 100 a day, across your organizations), or a check-now within a minute of the last one on that domain (a custom domain or a watch domain). Retryable: wait for the Retry-After seconds
hostname_not_allowed 422 Storage — a plycdn hostname, or a reserved name (such as .local, .localhost, .test, .internal), cannot be added as a custom domain
domain_not_active 409 Storage and video — POST /sign or POST /playback-sessions named a hostname that is neither the bucket's (or library's) default hostname nor one of its active domains
route_prefix_invalid 422 Shared address routes — a pathPrefix is not whole folders ending in / (2 to 256 characters, no . or .. folder, no //, \, %, ? or #, nothing under .plycdn-), or a bucket route has none; fix the prefix
route_prefix_reserved 422 Shared address routes — a bucket route's pathPrefix starts with v/ or _s/, which belong to the video library route; choose another folder
route_prefix_duplicate 422 Shared address routes — two routes share one pathPrefix; give each its own (one inside another is fine)
route_too_many 422 Shared address routes — more than 50 routes on one address; remove some
route_video_twice 422 Shared address routes — more than one video library route (pathPrefix: null) on one address; keep one
route_target_not_found 404 Shared address routes — a route's bucket or video library does not exist, or is not yours; pick one from GET /buckets or GET /libraries
route_redirect_invalid 422 Shared address routes — a redirect rule's location is not an absolute https:// or http:// address (at most 2,048 characters, no user name, password or # part), or its pathPrefix is not whole folders; give a full address and a prefix ending in / (or "" for the whole address)
route_redirect_loop 422 Shared address routes — a redirect leads back into itself or into redirects that lead back; send it to a different address or folder
route_targets_invalid 422 Shared address routes — a rule has no bucket or more than 5, the same bucket twice, a share outside 1 to 100, buckets of both visibilities, or a video library with other targets; give 1 to 5 different buckets of one visibility with whole shares
route_bucket_and_targets 422 Shared address routes — a rule has both bucketId and targets; keep one
route_version_not_found 404 Shared address routes — the version to restore is not one of the domain's last 20; read versions first
route_target_scope 403 Shared address routes — the key may not reach a route's bucket or library (it belongs to an organization the key does not cover); use a key that does
routes_need_private_address 409 Shared address routes — the domain's own bucket is public, so its domain is served directly and cannot carry routes; give the address a private bucket
version_conflict 409 Shared address routes — If-Match named a version that is no longer the latest; read the table again, apply your change, and save again
validation_error (tags) 422 Storage — POST /sign refused tags. fields is ["body","tags"] or ["body","tags",<tag name>] and detail says why: "Tags need a private bucket; on public links use a query parameter instead", "Tags are not available on video playback links", "Link tags are not available yet; sign the link without tags" (tags are not yet switched on for your account), "A link can carry at most 8 tags", "A tag name starts with a lowercase letter and uses only lowercase letters, digits and underscores, up to 32 characters", or "A tag value cannot be empty or contain control characters or any of & = ? #" / "can be at most 128 bytes long". Nothing is signed
too_many_rows 422 Delivery analytics — a monthly breakdown has more rows than the response allows (50,000 as JSON, 1,000,000 as CSV); narrow it to one bucket or breakdown, or use format=csv
too_many_organizations 422 Delivery analytics — an account read would span more than 500 organizations; read one sub-organization at a time (send its id as X-Organization-Id), or read your own organization without bucketId
export_busy 429 Delivery analytics and observability exports — another download is running, yours (at most two observability exports at a time) or the service is at its limit of simultaneous downloads; wait the Retry-After seconds and ask again. Retryable
analytics_unavailable 503 Delivery analytics — the figures cannot be read right now; try again shortly. Retryable. Delivery is not affected
restore_window_passed 409 Storage — more than 7 days since deletion; the bucket cannot be recovered
purge_not_found 404 Storage — unknown cache purge id, or another organization's
purge_url_not_in_bucket 422 Storage — a purge URL is not on the bucket's default hostname or one of its active custom domains (another bucket's host, a domain not active, or one with a port or userinfo)
purge_failed — Storage — a cache purge's failureReason: the edge did not complete it after every attempt; purge again. A purge can also fail with bucket_not_active when its bucket was deleted before it ran
object_not_found 404 Storage — unknown key, or it was deleted; /sign also answers it for a disabled object and for an objectId from another bucket
object_exists 409 Storage — the key is taken and allowOverwrite is false
video_source_exists 409 Video — a video was already made from this key (a file uploaded under sources/, from any tool). Uploading it again would process the same file twice; delete that video first, or upload under another name. Through the S3 and Azure endpoints the key stays listed, read-only, and deleting it there is refused with this code
object_busy 409 Storage — another change to this file is in progress (an upload landing on its key, or another delete or metadata change); nothing was changed. Retry shortly. Retryable
upload_not_found 404 Storage — unknown upload id
upload_not_open 409 Storage — the upload already completed, was aborted, or expired. Also answered to a part sent for such an upload, and (marked retryable) to deleting a video while its upload is being completed
upload_expired 410 Storage — past the 7-day session limit; start a new upload
upload_incomplete 409 Storage — complete called before every declared part arrived
size_mismatch 422 Storage — the bytes received don't total the declared size
checksum_mismatch 422 Storage — on an object, a declared sha256 did not match and the object is disabled. On a part upload, the part's bytes did not match its own Content-MD5 (sent by you, or computed as it arrived): send that part again
file_type_not_allowed 415 Storage — not in the bucket's uploadRules.allowedTypes
ticket_invalid 401 Storage — the part upload ticket doesn't verify; copy it again rather than editing it
ticket_expired 401 Storage — renew the upload for a fresh ticket
part_out_of_range 400 Storage — the part number isn't between 1 and partCount
part_size_mismatch 400 Storage — a part's declared size doesn't match what the plan requires for that number, or the bytes that arrived didn't total it
provider_unavailable 503 Storage — transient; retry with backoff. From the upload server it also means it is busy: wait for the Retry-After it sends, then send the part again. Retryable
upload_too_slow 408 Storage — a part's body arrived too slowly (a stalled or very slow connection) and was cut; the connection is closed. Send the same part again, nothing else is lost. Retryable
forbidden 403 Storage — your IPlycdnStorageAuthorizer refused the operation; the default refuses everything until you implement one
library_not_found 404 Video — unknown library id, a files bucket's id, or another organization's library
video_not_found 404 Video — unknown or deleted video, or another organization's; on /sign, also a video from another library or one plycdn has taken down
original_not_kept 409 Video — encoding a video again when its original was not kept (keepOriginal was false when it was made)
video_not_ready 409 Video — /sign for a video that is not playable or ready yet; wait for video.playable or check status
live_input_not_found 404 Live streaming — unknown or deleted live input, or another organization's
live_not_started 409 Live streaming — retryable: the input has no stream running yet (playback links) or at all (end); try again in a few seconds
live_input_disabled 409 Live streaming — the input is disabled (publish tokens, playback links); enable it first
live_input_busy 409 Live streaming — deleting an input, or changing backupIngest, redundantTranscoding, captions or dvrWindowSeconds, while a stream is running; end it first or wait. Also an ad break that overlaps one already asked for
live_cap_reached 409 Live streaming — a safety cap is reached; detail.cap names it (live_concurrent_streams, live_stream_max_seconds, live_max_height, live_max_kbps, live_realtime_viewers_per_stream, live_inputs, live_dvr_seconds, live_destinations or scheduled_breaks) and detail.limit its value. A running stream is never cut; ask us to raise the cap
tags_not_on_live 422 Live streaming — tags sent with a live playback link; leave them out
hostname_not_on_live 422 Live streaming — hostname sent with a live playback link; custom domains are not available for live links
live_quota_exceeded 409 Live streaming — the live allowance set on your account is used up
publish_token_invalid 401 Live streaming — an encoder's stream key or a browser's publish token was refused (wrong, replaced, expired, already used for a stream, or the input is disabled)
stream_key_in_use 409 Live streaming — another encoder is already publishing to the input
feature_not_available 404 Live streaming is not switched on for your service yet; the same for restream destinations and ad breaks while those are not switched on
feature_not_in_plan 403 Live streaming, restreaming or ad insertion is not part of your plan
ad_break_not_cancellable 409 Live streaming — the ad break has started, ended, was missed or cancelled, or is due within 45 seconds; detail.state says its state
ad_break_not_found 404 Live streaming — no such ad break on this live input
live_setting_not_in_plan 409 Live streaming — a live input setting your plan or service does not include was turned on; detail.setting names it (backupIngest, redundantTranscoding, captions or indexRecording)
live_setting_conflict 409 Live streaming — two settings cannot be on together; detail.settings is ["ads", "protection"] or ["ads", "dvrWindowSeconds"]. Also refuses a stream start
protection_not_configured 400, 409, 503 Live streaming — the content protection setup is not available to your account or refused its options: 400 where it is saved, 409 when a stream would start, 503 (retryable) on a playback link
destination_url_invalid 400 Live streaming — a restream address is not rtmp:// or rtmps:// on port 443 or 1935, carries a key or credentials, or does not resolve to a public address
destination_not_found 404 Live streaming — unknown or deleted restream destination, or another organization's
destination_limit_reached 409 Live streaming — the input has as many destinations as its live_destinations cap allows; detail.cap and detail.limit say
destination_unreachable 502 Live streaming — retryable: a destination test could not reach the platform. Also a destination's lastError
share_link_not_found 404 Live streaming — unknown or deleted share link, or another input's
share_link_limit_reached 409 Live streaming — the input has 50 share links; detail.limit says
watch_link_not_found 404 Share links, on the public watch routes — the address is unknown, turned off, expired or deleted, or the stream can no longer be watched
watch_not_started 409 Share links — retryable: the stream has not started
watch_ended 409 Share links — the stream is over and there is no recording to show
watch_password_required 401 Share links — the link has a password and none, or a wrong one, was sent
watch_password_attempts 429 Share links — retryable: too many wrong passwords; wait for Retry-After
logo_invalid 422 Watch page brand — the logo is not a PNG, JPEG or WebP, or its type does not match the file
logo_too_large 413 Watch page brand — the logo is over 512 KB
watch_domain_limit_reached 409 Watch domains — five already; detail.limit says
watch_domain_not_found 404 Watch domains — unknown or removed domain, or another organization's
domain_exists 409 Watch domains — you already added this hostname
hostname_not_allowed 422 Watch domains — plycdn's own names or a name that is not public
watch_domain_apex_unsupported 422 Watch domains — a bare domain such as example.com; use a subdomain such as www.example.com or live.example.com (detail.suggestions) and redirect the bare domain to it at your DNS provider
webhook_not_found 404 Webhooks — unknown or deleted endpoint, or another organization's
webhook_delivery_not_found 404 Webhooks — unknown delivery, or another organization's
webhook_url_invalid 400 Webhooks — the endpoint's URL is not printable ASCII, not on port 443, carries credentials, or its name resolves to a private, local or otherwise non-public address; publish it on a public one
webhook_limit_reached 409 Webhooks — the organization already has 10 endpoints; delete one first
playback_unsupported — Video — shown by the plycdn player, never answered by the API: the browser can play the stream in neither form
playback_link_failed — Video — shown by the plycdn player, never answered by the API: three playback-link renewals in a row failed or were refused, or the stream's address could not be reached; check your backend's sign route and the viewer's connection
admin_key_required 403 Sub-organizations, the account audit, and the storage operations listed under "Storage operations that need an admin key" (creating, changing or removing a bucket, a video library, a custom domain, a webhook endpoint or the storage account; rotating a signing key or webhook secret; and the three storage-credential writes, which an admin key then refuses with dashboard_session_required) need an admin key, created in the dashboard
observability_not_enabled 409 Observability — choose a region first: PATCH /observability/settings with a region
observability_region_fixed 409 Observability — the region cannot change once chosen
observability_unavailable 503 Retryable. Observability could not answer or take the data just then. Try the same request again shortly
query_invalid 400 Observability — the statement is not one read-only statement over your own tables, or the SQL has a mistake. The detail says what
query_too_expensive 400 Observability — the statement would read or return too much. Narrow the time range or add filters
query_timeout 400 Observability — the statement ran longer than 30 seconds (or your raised ceiling), or longer than the maxExecutionMs you set. Narrow it, or export
query_busy 429 Retryable. Observability — eight of the organization's statements are already running (a query key's statements count among them). Wait for Retry-After (1 second) and send it again; the Node.js and Python packages do this for you, the .NET package throws and you wait
read_quota_exceeded 429 Retryable. Observability, Starter only — the organization's hourly read allowance (1 TB) is used up. Wait for Retry-After (the seconds until it renews, 1 to 3,600); narrower time ranges and filters read less. Growth and Enterprise have no hourly read limit
trace_not_found 404 Observability — no trace with that id in your data
query_key_not_allowed 403 Observability — a query key reads only (query, validate, reference, export, tail and trace). Use an admin key or the dashboard for anything else
query_key_limit_reached 409 Observability — 200 query keys are active. Revoke one
query_key_not_found 404 Observability — no query key with that id in this organization
tail_busy 429 Retryable. Observability — four tails are already running for the organization. Wait for Retry-After
ingest_key_limit_reached 409 Observability — twenty ingest keys are active. Revoke one first
ingest_key_not_found 404 Observability — unknown ingest key id, or another organization's
ingest_key_invalid 401 Sending data — no ingest key, or one that is unknown or revoked
ingest_wrong_region 403 Sending data — the key belongs to an organization in another region. Send to your region's address
ingest_refused 403 Sending data — this key cannot send right now. Contact support
ingest_invalid 400 Sending data — the body could not be read as what it claims to be. For JSON lines the detail names the line, and nothing in the request was kept
ingest_too_large 413 Sending data — over 5 MB (10 MB for Prometheus remote write), or more than 10,000 JSON-lines records. Send smaller requests
archive_bucket_invalid 400 Observability — the archive bucket must be one of your active file buckets in the same region
not_found 404 The path is not a route of this API. The API at /api/content/v1 answers 404; the dashboard's own routes answer most paths they do not know with 405 method_not_allowed instead
api_key_limit_reached 409 Two keys are already active for that organization, or for the whole account. Deactivate one first
api_key_not_found 404 Unknown key id, or another organization's
api_key_already_active 409 That key is already active
api_key_inactive 409 A deactivated key cannot be rotated. Create a new key
sub_organization_not_found 404 Unknown sub-organization id, or another account's
dashboard_session_required 403 API keys, storage credentials, people, invitations and the organization profile are managed in the dashboard; every API key is refused there (a standard key is stopped earlier, on the storage-credential writes, with admin_key_required)
organization_suspended 403 This organization is suspended. Contact plycdn support. Your API keys, signed-in assistants, dashboard sign-ins, storage credentials, and new upload and playback links are refused with this code. Once it is reactivated, every key and credential works again. Delivery stops as well: public files and video, links you already issued and custom domains are not served while the organization is suspended, and are served again, with your settings as you left them, once it is reactivated (this can take a few minutes to reach every location). Queued processing, connector syncs and notifications pause and resume when it is reactivated. Not retryable
credential_not_found 404 Storage credentials — unknown id, another organization's, or already revoked or expired (on rotate)
credential_limit_reached 409 Storage credentials — 20 are already active (revoked and expired ones do not count), or both Azure key slots are in use. Revoke one first
storage_account_not_found 404 Storage account — none exists yet for this organization. Create it first (also answered when creating an Azure credential)
storage_account_exists 409 Storage account — this organization already has one. Its name cannot be changed
storage_account_name_taken 409 Storage account — account names are unique across plycdn; choose another
rate_limited 429 Your account created more than 10 keys (in the dashboard), or 60 sub-organizations, in an hour, or more than 120 bucket-name checks a minute, 20 bucket creations a day, 60 cache purges (10 whole-bucket purges) or 60 signing-key rotations an hour, or 60 webhook pings, redeliveries and secret rotations (together) an hour. Sending observability data: many attempts from one address with a missing or wrong ingest key (a valid key is never limited by how much it sends). Many passkey sign-in, confirmation or management attempts in a short time (dashboard only). Wait for the Retry-After seconds, then try again
unauthorized 401 A dashboard route under /api was called with neither a session nor a key
passkey_not_recognized 401 Passkeys, dashboard only — a sign-in or confirmation with a passkey was not accepted (unknown, removed or not confirmed on the device). The same answer for every reason. Sign in with the password
passkey_challenge_expired 400 Passkeys — the sign-in or add took longer than 5 minutes, or was already used. Start again
reauth_failed 401 Passkeys — the password or passkey offered to confirm it's you was not accepted
session_ended 401 Dashboard only — the dashboard session has ended: 12 hours after signing in, after Sign out everywhere, or after a password reset. Sign in again
reauth_required 403 Passkeys — adding a passkey needs a confirmation (password or an existing passkey) in the last 5 minutes
passkey_registration_failed 400 Passkeys — the device's answer was refused. Try again or use another device
passkey_already_registered 409 Passkeys — that passkey is already registered
passkey_limit_reached 409 Passkeys — 20 are already on the account. Remove one
passkey_not_found 404 Passkeys — unknown id, or another person's
invalid_organization 400 The organization chosen on a dashboard route under /api (X-Organization-Id or organizationId) is not a UUID
invalid_asset, invalid_job, invalid_connector 400 The id in the path of a dashboard route under /api is not a UUID. Nothing was sent on
invalid_path 400 The path has a segment the gateway will not pass on: . or .. (encoded or not), or a character other than letters, digits, _, ., ~ and -
unsupported_media_type 415 A write whose body is not application/json, or a compressed body (Content-Encoding) where none is accepted. Send JSON, uncompressed
method_not_allowed 405 That route does not take that method
too_many_tool_calls 400 The MCP server for AI assistants (https://mcp.plycdn.com/mcp): one request carried more than 5 tool calls. Nothing ran; send them in requests of 5 or fewer. Connect your AI assistant
sign_in_required 401 The MCP server for AI assistants: an account tool was called with no sign-in and no API key. The assistant signs in (or you give it a key); the docs tools need neither. Connect with sign-in
invalid_token 401 The MCP server: the assistant's sign-in has expired or was ended. Choose Connect in the assistant again
connection_ended 401 An assistant's connection ended (it was disconnected, the assistant signed out, the person who connected it left the organization or chose Sign out everywhere, or it went 90 days unused). Connect it again from the assistant
dashboard_or_api_key_required 403 A signed-in assistant cannot create query keys; do it in the dashboard or with an API key
mcp_request_not_found 404 Connecting an assistant: this sign-in request was not found. Start again from the assistant
mcp_request_expired 410 Connecting an assistant: the sign-in request expired. Start again from the assistant
mcp_request_used 410 Connecting an assistant: the sign-in request was already used. Start again from the assistant
mcp_request_other_user 409 Connecting an assistant: the request belongs to another person. Start again from your own assistant
organization_not_reachable 403 Connecting an assistant: you cannot connect it to that organization. Choose your own or one of its sub-organizations
invalid_scope 400 Connecting an assistant: choose Standard or Admin access
organization_lookup_unavailable 503 Retryable. We could not check which organizations your key covers just then. Nothing about your request is wrong
no_urls, too_many_urls 400 Adding files by address in the dashboard: paste at least one address, and at most 20 at a time
unsupported_format per address Adding files by address: that file is not a format we index (see What can be indexed)
internal_error per address Adding files by address: that one address failed on our side. Try it again
logthread_key_rejected 422 Logthread did not accept the ingest key. Copy a current one from Logthread (Keys → Ingest keys) and connect again
logthread_unreachable 503 Retryable. Logthread could not be reached to check the key or finish connecting, its workspace is suspended or not ready yet, or Connect to Logthread is not available right now (connect with an ingest key instead). Try again in a minute
logthread_connect_failed 422 Connect to Logthread: the request expired (after 10 minutes), was already used, was started by someone else or in another organization, or Logthread refused it. Press Connect to Logthread again
request_log_unavailable 503 Retryable. The storage request log could not answer just now (Request log). Try again in a minute
audit_unavailable 503 Retryable. A dashboard "search as" could not be recorded in the account audit, so it was not run

A failed video's errorCode values are listed under Videos, and a webhook delivery's lastError values under Webhooks; neither comes back from a call.

Why a file failed to index

These never come back from a call. They arrive later, on the job — state: "failed" with the code in errorCode, and on a connector as lastError. Show them to whoever uploads content: every one of them is something only they can fix. (The one exception is adding files by address in the dashboard, which checks each address before registering it and can report source_unavailable, source_temporarily_unavailable, source_dns_unavailable or source_address_forbidden for it at once.)

Code What went wrong
ocr_required A PDF in which no page could be read, neither from its text nor as a scanned page. Send a clearer scan. If only some pages cannot be read, the file indexes and lists those pages in its warnings
text_encoding_must_be_utf8 A .txt, .md or .csv file that is not UTF-8. Save it again as UTF-8
media_duration_limit The recording is longer than we index in one file; maxAudioSeconds in GET /capabilities is the limit
document_empty The file parsed and contained no text at all
encrypted_document Password-protected. We do not ask for the password
malformed_document The file is damaged, or is not the format its extension claims
no_speech_detected The recording contains no speech — silence, or music only
audio_track_missing A video with no audio track. Slide reading may still find text on screen
invalid_media The container or codec could not be read
html_could_not_be_parsed, manifest_could_not_be_parsed The file is not the format its name or manifest claims
document_resource_limit The document needs more memory or time to extract than we allow one file. Usually a very large scan or a deeply nested spreadsheet
range_unavailable Your storage refused a range request while we were reading the file in parts
artifact_expired Our working copy expired mid-job. Retried automatically from your source
extracted_text_limit, document_expansion_limit, media_transfer_limit Beyond a size ceiling. The detail says which and what it is
document_processing_timeout, media_processing_timeout The file took longer than we allow. Usually a very large scan
source_unavailable Your storage refused or returned nothing
source_temporarily_unavailable, source_dns_unavailable Your storage is down or unresolvable. Retried automatically
source_address_forbidden The address resolved somewhere we will not fetch from
source_host_outside_ceiling The host is not one plycdn permits at all
connector_unauthorized The source rejected the connector's access token, without saying why. Issue a new one
connector_credential_missing No credential is stored for that connector
connector_credential_expired The SAS has passed its expiry. Issue a new one — against a stored access policy, so the next extension needs no change here
connector_credential_cannot_list The credential can read single files but not list the container, so we see nothing to index. Needs Read and List
connector_credential_cannot_read The credential can list the container but not download from it
connector_credential_scoped_to_one_blob The SAS is signed for a single file (sr=b) rather than the container. Generate it from the container's own page
connector_credential_is_a_url The whole SAS URL was saved where the token goes. Save only the part after the ?
connector_credential_malformed Not a readable SAS. Copy it again without editing it
connector_unavailable The source could not be reached. Retried on the next run
transcription_failed, ocr_failed Processing failed on our side. Reindex; contact us if it repeats
processing_temporarily_unavailable Retryable. A temporary problem on our side, not in your file. The job is retried automatically (retry_scheduled, with retryAt); nothing needs to change on yours. If it ends failed, reindex, and contact us if it repeats — we are alerted to it. It can also be a connector item's errorCode, a connector's lastError or a per-item /imports result
processing_failed A problem on our side, not in your file, that retrying the same work would not fix, so the job ends failed at once. A job whose processing stopped before finishing several times running ends the same way. Reindex it later, and contact us if it repeats — we are alerted to it. It can also be a connector item's errorCode, a connector's lastError or a per-item /imports result

The connector_credential_* codes are read from the token itself before it is used, so they arrive immediately and name the one thing to change. Only the parameters Azure publishes in the clear are inspected — the signature is never read. A SAS backed by a stored access policy is not second-guessed at all, because the policy carries the permissions and the window.

Anything not listed here is a fault on our side rather than something in your content. Report it with the x-request-id from the response and the time, and we can trace the exact run.

39Practical notes

Retries. These writes require an Idempotency-Key header and refuse without one with idempotency_key_required:

POST  /assets                          POST  /assets/{assetId}/reindex
POST  /imports                         PATCH /assets/{assetId}/transcript
POST  /buckets                         POST  /domains
POST  /libraries                       POST  /libraries/{libraryId}/videos
POST  /webhooks                        POST  /libraries/{libraryId}/live-inputs
POST  /live-inputs/{id}/destinations

Repeating any of them with the same key returns the original result rather than doing the work twice — which is the point on a batch of two thousand files, where a timeout otherwise leaves you unable to tell what registered. Everything else is safe to repeat without one: reads are reads, and cancel and delete are idempotent in effect. A key longer than 200 characters counts as missing; use a new one for each new piece of work. A key is remembered for 30 days: a retry inside that time returns the original result, and after it the same key starts new work. Keys that follow from the work itself (the same externalId and sourceVersion, the same batch number) make a retry safe without storing anything.

When we are the problem. content_service_unavailable and content_service_timeout are returned when plycdn cannot reach the content service or it does not answer in time. Both carry retryable: true. They say nothing about your request — retry with backoff, and if they persist, contact us rather than changing your integration.

Rate limits. Requests are rate limited per API key, by plan: 36,000 requests a minute (600 a second) per key on Starter, 120,000 (2,000 a second) on Growth and 300,000 (5,000 a second) on Enterprise. That one allowance covers every route under /api/content/v1, storage included. Sub-organizations have their parent organization's limits unless we set their own. If your workload needs more, ask us: we raise it for your organization without any change on your side; the limits exist so that one workload cannot slow down another, not to meter you. Separately, each client address may make 72,000 requests a minute that are not served (that fail authentication, or are refused for exceeding a key's limit); requests that are served never count against it. Once an address has sent more than 60 failed credentials in a minute, requests from it with a missing or malformed credential are refused (429) for the rest of that minute, and any one credential that fails 5 times in a minute is refused for the rest of that minute. A key that has used its minute's allowance is refused until the minute ends. A throttled request returns 429 with Retry-After and {"error": "Too many requests, please try again later"} — a plain message rather than a code, because it is refused before reaching the content service. Back off for Retry-After seconds; do not spin.

Versions. A new sourceVersion for the same externalId creates a new revision. The previous one stays searchable until the new one is ready, so re-uploading a corrected file does not create a gap.

Sub-organizations. Send the sub-organization's UUID in X-Organization-Id to register and search within it. Each can hold its own storage hosts and limits, inheriting yours where it sets nothing.

Daily limits. dailyAudioHours caps how many hours of audio/video an organization can start indexing in a day; work above the cap is refused with organization_daily_limit — a protective daily limit, not a reflection of what you owe — rather than silently queued, and it resumes the next day, or when you raise it under settings.

dailyBudgetUsd is deprecated since 1.7.0: accepted and ignored, always returned as 0. What your organization can use is controlled by your plan's quotas — see What you have used.

40Support

Give the operation, the time, the error code and the asset or job id. Never include API keys, storage connection strings, or signed URLs — a signed URL grants access to the file it points at.