AnyTV Provider API

Connect your own management system to AnyTV. Everything you do by hand in the provider console, your system can do automatically: look at a customer's device, activate AnyTV Pro on it with your credits, send the customer their playlist, update it, move it to a new host, and remove it when the subscription ends.

The API is plain HTTPS and JSON. There is no SDK to install. Every example on this site is available in cURL, Node.js, PHP and Python. Pick your language once, in any code box, and the whole site follows.

Base URL

• All requests use HTTPS. Plain HTTP is refused with 400 https_required.
• Request and response bodies are JSON. Send Content-Type: application/json with every body. Bodies are limited to 16 KB.
• The API is for servers only. An API key must never be placed in a web page or an app.
• Field names are snake_case. Timestamps are UTC in ISO 8601. Money never appears here; credits do, see Credits and units.

Quickstart

From nothing to a customer watching, in five steps.

1. Create an API key. Sign in to the provider console, open API keys, then Create a key. Confirm with your password. The key is shown once, so copy it straight into your server's secrets. See Authentication.
2. Check that it works. Call GET /v1/me. You get your provider name, your caps and what your account may do right now.
3. Ask the customer for the code. On the TV they open AnyTV and choose Send to this TV. The screen shows a short code and a QR code. The code lasts a few minutes.
4. Look at the device. Send the code to POST /v1/devices/preview. You get a device_ref that is yours to keep for this device, and whether it can be activated.
5. Send the playlist, or activate Pro. POST /v1/deliveries sends a playlist for free. POST /v1/activations unlocks AnyTV Pro on the device for a year or two with your credits, and you can send the playlist in the same breath with POST /v1/activations/{id}/deliveries.

How it works

1. The customer shows a code. AnyTV on the TV mints a short lived code tied to that installation. Nothing about the customer leaves the device: you never see an account, an email or an address.
2. You preview. The code resolves to a device_ref, an identifier that is specific to your provider account. The same TV has a different device_ref for every provider. Save it next to your customer; it does not expire.
3. You deliver or activate. A delivery waits with status pending until the app picks it up on its next check in, usually within a minute, and becomes delivered. An activation reserves your credits, AnyTV's billing confirms it, and the device has Pro. In the rare case billing is slow you get 202 processing and the activation finishes on its own.
4. The customer stays in charge. They can remove your provider from their device at any time. Your playlists leave, the activation ends as released, and further calls for that device answer 409 device_blocked_provider until they allow you again.

A client you can copy

You do not need a library, but you do want four things in one place: your key, a timeout, retries, and clean errors. The helper on the right does all four in about thirty lines. Copy it into your project and the rest of your code becomes one line per call.

• It reads the key from the ANYTV_API_KEY environment variable.
• It retries only what is temporary: network failures, 5xx, 409 request_in_progress and short 429 waits. It never sits out a daily cap.
• It refuses an activation write without an Idempotency-Key, because only the key makes a retry safe.
• It never logs anything. Keep it that way: the key and your customers' playlist passwords pass through it.
• It turns error responses into exceptions that carry the error code, so you can branch on device_not_found and friends.

Authentication

Every request carries your API key in the Authorization header as a bearer token. There are no sessions, no cookies and no login call.

Creating a key

1. Sign in to the provider console as an owner or admin and open API keys.
2. Choose Create a key. Give it a name you will recognise later, for example "Billing system".
3. Choose its scopes. A key can only hold scopes your own role has. See Scopes.
4. Optionally restrict the key to your servers' IP addresses: exact addresses, up to 20.
5. Optionally set an expiry, 1 to 730 days. We recommend a year, with a reminder to replace the key before then.
6. Confirm with your password. Copy the key. It is shown once. AnyTV stores only a one way hash and cannot show it to you again. If you lose it, revoke it and create a new one.

Replacing a key without downtime

Your account can hold more than one active key (the number is one of your caps, see GET /v1/me). Create the second key, switch your system to it, confirm that it works, then revoke the first.

A missing, malformed, unknown, revoked or expired key always gets the same answer: 401 invalid_api_key. A key used from an address outside its allowlist gets 403 ip_not_allowed.

Scopes

Each key carries one or more scopes. Give a key only what it needs. A reporting tool, for example, needs devices:read and credits:read and nothing else.

Calling an endpoint without its scope returns 403 insufficient_scope. GET /v1/me needs no scope.

Keeping keys safe

A key is a password for your customers' devices and your credits. Treat it like one.

• Server only. Keep it in an environment variable or a secrets manager. Never in a web page, a mobile app, a spreadsheet or a chat message.
• Never in source control. Keys start with atv_live_ so that secret scanners can spot one that was committed by mistake.
• One key per system. If two systems talk to AnyTV, give each its own key, so you can revoke one without stopping the other.
• Watch the last used column. The console shows when each key was last used. A time you cannot explain means the key should be revoked now.
• Lock it to your IP if you can. If your server has fixed IP addresses, list them when you create the key.
• Revoking is instant. The very next request with a revoked key fails. AnyTV staff can also revoke a key for you in an emergency.
• Never log it. Keep the Authorization header, request bodies and playlist URLs out of your logs and error reports. They contain the key and your customers' playlist passwords.
• No personal data in references. external_ref, playlist names and Idempotency-Keys are stored as plain text. Use an order or customer number, never a person's name or a password.
• On 401 invalid_api_key, stop. Do not retry. Alert a person: the key was revoked, has expired or is wrong.

Errors

AnyTV uses normal HTTP status codes. 2xx means it worked. 4xx means the request needs to change before it can work. 5xx means something went wrong on our side and the same request can be retried.

Every error body carries error, which is stable, and usually message, which is for people and may be reworded. When waiting helps, retry_after (seconds) is in the body and in the Retry-After header. When your standing is the cause, reason names the step that unblocks it, the same word the console shows. Write your code against error.

Every route

Endpoint specific errors, such as device_not_found or insufficient_credits, are listed with each endpoint.

What to retry

• Retry: network failures, timeouts, 429 with a short wait, 409 request_in_progress and any 5xx. Wait longer each time, and send the same Idempotency-Key.
• Do not retry unchanged: every other 4xx. The request itself has to change.

Safe retries

Networks fail. When a request times out, you cannot know whether AnyTV received it. Sending it again could spend credits twice. The Idempotency-Key header solves this.

The header is required on every call that can spend or return credits: activate, extend, move, undo and revoke. It is accepted on sending, updating and removing a playlist. Use a value that is unique to the operation: your own order number works well, order-1001-activate, order-1001-playlist.

• If the first request succeeded, the retry returns the very same response, marked with the header Idempotent-Replayed: true. Nothing is done twice. An activation replay answers 200 instead of 201.
• If the first request failed, the retry runs normally.
• Same key, different request returns 422 idempotency_key_reused. This catches bugs where two operations share a key.
• First request still running returns 409 request_in_progress. Wait a moment and retry.
• An activation that answered 202 processing finishes on its own. Retrying with the same key returns its current state; a new key would start a new activation and be refused with 409 already_activated_by_you once the first one is active.

Keys are 8 to 128 characters, made of letters, digits and _ - : . They are remembered for 24 hours and are private to your account.

Rate limits and caps

When you are over a limit you receive 429 with the seconds to wait in retry_after and in the Retry-After header. A minute limit answers rate_limited; a daily cap answers new_device_cap_reached or activation_cap_reached with a wait of up to an hour. Do not sleep through a daily cap inside a request. Give up and try tomorrow.

Pagination

Lists are paged with a cursor. Ask for up to limit rows (1 to 100, 50 by default); the response carries next_cursor, which is null on the last page. Send it back as cursor for the next page. A cursor is opaque and private to your account; a reused or edited cursor answers 400 invalid_cursor.

Credits and units

You buy credits in the console. The API counts them in units: ten units are one credit, so a balance of 184 units is 18.4 credits. Every balance also carries available_credits as text, for display.

An activation reserves the units first and commits them when AnyTV's billing confirms, which is usually inside the same request. A failed activation releases them. An undo within 72 hours refunds them. Your ledger shows every move.

Your standing

Whether a call is allowed depends on your account's standing, which GET /v1/me reports as capabilities. Reads, removals, undo and revoke always work, in every state. New work needs the capability:

A blocked capability carries a reason, and a refused call carries the same word:

Preview a device

Resolves the code on the customer's TV to a device_ref and tells you what you can do with the device. Call it before activating: it is free, and it tells you about a Pro the customer already has or an activation by another provider before you spend anything.

Body

Returns

Errors

404 device_not_found when the code is unknown or expired. 400 invalid_target when no code was sent.

Retrieve a device

The same preview, by the device_ref you saved. Use it to check a device before an extension or a new playlist, without asking the customer for a code.

Errors

404 device_not_found if the reference is not yours.

The activation object

An activation is AnyTV Pro on one device, paid with your credits, for a term you chose.

Activate Pro

Unlocks AnyTV Pro on the customer's device for the term, with your credits. Idempotency-Key required.

Body

Returns

201 with the activation, status active. 200 on a replay. 202 with { "status": "processing", "activation": … } when billing is slow: the activation is reserved and completes on its own; read it again in a minute.

Errors

List activations

Your activations, newest first.

Query parameters

Returns

An activations array and next_cursor.

Retrieve an activation

One activation with its terms. Poll this, no more than once a minute, after a 202 processing.

Errors

404 activation_not_found if it is not yours.

Extend

Adds a term to an active activation. The new term starts when the current one ends, so extending early loses nothing. Idempotency-Key required.

Body

Returns

200 with the activation and its new expires_at, or 202 processing.

Errors

404 activation_not_found, 409 activation_not_active, 409 extension_in_progress, 402 insufficient_credits, plus the standing errors.

Move to a new device

The customer got a new TV. The remaining term moves to the new device as a new activation; the old one ends as transferred. Idempotency-Key required.

Two moves per activation chain in any 365 days are counted. A move is free when the old device is gone: the customer removed your provider there, the device was removed from their account, or it has not been seen for 30 days.

Body

Returns

200 with the new activation and previous_activation_id, or 202 processing.

Errors

409 transfer_limit_reached with resets_at; 409 same_device; 409 activation_not_transferable; 409 device_has_live_activation when the new device belongs to another provider; the device and standing errors.

Undo

A wrong code, a customer who changed their mind: within 72 hours of the activation committing, undo it and the credits come back as refunded_units. The customer's Pro ends. Idempotency-Key required. No body.

An activation that was moved cannot be undone, a device can be undone once, and a provider who undoes a large share of its activations over 30 days is asked to stop (409 undo_cap_reached).

Errors

409 undo_window_closed, 409 activation_transferred, 409 device_already_undone, 409 undo_cap_reached, 404 activation_not_found.

Revoke

Ends an activation early. The customer's Pro stops; no credits come back. Use undo within 72 hours instead when that applies. Idempotency-Key required. DELETE /v1/activations/{id} does the same.

Body

Errors

404 activation_not_found, 409 activation_not_active.

The delivery object

A delivery is one playlist you sent to one device. The device holds it; you see its state.

Send a playlist

Sends a playlist to a device. Free, no activation needed. The app adds it on its next check in. Sending a second playlist with the same host and name updates the first in place.

Body

Returns

201 with the delivery, status pending.

Errors

Send for an activation

The same as Send a playlist, addressed by an active activation of yours instead of a device. The delivery is linked to the activation: it moves with a transfer and goes with a revoke.

Body

playlist, name, profile_hint as above. No code or device_ref.

Errors

404 activation_not_found, 409 activation_not_active, and the send errors.

Update a playlist

Changes a live playlist in place: a new password, a new server, a new name. The device replaces the old entry without the customer doing anything. The answer is the new delivery, with replaces_delivery_id pointing at the old one, which becomes superseded.

Body

Errors

404 delivery_not_found, 409 delivery_not_live, 409 replacement_pending (the previous update has not reached the device yet), 409 type_change_needs_remove_and_add, 400 invalid_playlist, 400 invalid_name.

Remove a playlist

Takes the playlist off the device. A pending one is cancelled; a delivered one becomes removal_pending and the app removes it on its next check in. Works in every account state.

Errors

404 delivery_not_found, 409 already_removed. On a lost response, already_removed means the first attempt worked.

Move playlists to a new host

Your server moved. Every live playlist of yours that points at the old host gets an update pointing at the new one, 50 at a time. Preview first with dry_run: true and send the count back as expected_count; a count that changed in between is refused, so you never move more than you looked at.

Body

Returns

{ matched, updated, skipped, remaining }. 200 for a dry run or when nothing moved, 202 when updates were queued. With remaining above zero, run the dry run again a minute later for the next chunk; moved playlists no longer match.

Errors

400 invalid_from_host, 400 invalid_to_host, 400 same_host, 404 nothing_matched, 409 count_mismatch, 429 rate_limited (one a minute).

List playlists

Query parameters

Returns

A deliveries array and next_cursor.

Retrieve a playlist

One delivery. To wait for delivered, check again no more than once a minute. There are no webhooks yet.

Errors

404 delivery_not_found.

Check your key

Which provider and key you are using, the key's scopes and expiry, your caps, and your capabilities right now. It needs no scope, so it is the right first call when you set up, and a good health check for monitoring.

Credit balance

available_units you can spend now, reserved_units held by activations still confirming, credit_limit_units a credit line AnyTV may have granted, and available_credits as text.

Credit ledger

Every move of your credits, newest first, paged. Each entry has a kind: purchase, reserve, commit, release, refund_undo, adjustment, forfeit, purchase_refund, transfer_in, transfer_out; units and reserved_units as signed deltas; and the activation_id or purchase_id it belongs to.

Subscription lifecycle

What to call when something happens in your billing system.

Go live checklist

• The key is stored in a secrets manager or environment variable, not in code.
• The key has only the scopes your system uses.
• Every activation write sends an Idempotency-Key built from your own order or operation number.
• Requests have a timeout, 20 seconds is a good value.
• Network failures, 5xx, 409 request_in_progress and short 429 waits are retried with growing waits. Daily caps and other 4xx are not, and 401 alerts a person.
• 202 processing is handled: you read the activation again later instead of activating twice.
• The key, the Authorization header and customer playlist passwords never appear in your logs.
• You store device_ref, activation ids and delivery ids with each customer.
• device_not_found leads to a message for the customer, not to a retry loop.
• Your code branches on error, never on message, and ignores response fields it does not know.
• Someone on your team knows where to revoke a key, and reads the audit trail now and then.

Versioning and changes

This is version 1, under /v1.

• We may add new endpoints, new optional request fields, new response fields, new statuses and new error codes. Build your code to ignore what it does not know.
• We will not remove or rename fields, change their types, or change the meaning of an error code inside v1.
• A change that would break you gets a new version, and v1 keeps working alongside it.

Changelog

A machine readable description of the API is available as an OpenAPI file. You can import it into Postman or Insomnia to try every call.