Third-party API: working in five minutes

These APIs are for your backend. Do not sign in to the WebUI to copy cookies, and never give a long-lived API token to a browser, packaged app, or player.

Prepare the AKStream.Next HTTPS base URL and an administrator-issued ak_pat_ API token.

sequenceDiagram
    participant Backend as Business backend
    participant API as AKStream.Next API
    participant Media as MediaServer
    participant Player as Browser or player
    Backend->>API: Query resources with Bearer API Token
    Backend->>API: Request a resource-bound short URL
    API-->>Backend: Playback URL with ak_ticket
    Backend-->>Player: Return only the short URL
    Player->>Media: Play HLS/FLV/fMP4
    Media->>API: Validate ticket and resource through OnPlay
    API-->>Media: Allow or deny

Step 1: verify the token

export AK_BASE='https://ak.example.com'
export AK_TOKEN='ak_pat_<complete-token>'

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H 'Accept: application/json' \
  "$AK_BASE/api/v2/third-party/capabilities"

A successful response lists the token's current effective permissions and supported integration categories. A 401 means the token is invalid, expired, revoked, outside its allowed IP range, or is a WebUI session token instead of an API token.

Step 2: list a channel and play it

List channels first:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $AK_TOKEN" \
  "$AK_BASE/api/v2/third-party/channels?page=1&pageSize=50"

If a regular RTSP/ONVIF channel is offline and the token has channels.manage, start it:

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $AK_TOKEN" \
  "$AK_BASE/api/v2/third-party/channels/camera-001/start"

An accepted start command is not proof that media is ready. Query /api/v2/third-party/streams until state is Online, then create a playback lease whose URLs stay stable:

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"protocols":["http-flv","http-fmp4","hls"],"leaseSeconds":120,"absoluteLifetimeSeconds":43200}' \
  "$AK_BASE/api/v2/third-party/channels/camera-001/playback-lease"

Each sources[].url may be returned to the current user's player. At renewAfter, renew the lease without changing the URL:

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"leaseSeconds":120}' \
  "$AK_BASE/api/v2/third-party/playback-leases/<leaseId>/renew"

Renewal changes only the timestamps; the player does not reset its source. Create a new lease after absoluteExpiresAt, expiry, revocation, or loss of the original API-token grant. The original /playback endpoint remains available for simple non-renewable links.

Step 3: grant permissions by task

Do not grant * to routine integrations. Give every system its own named token, owner, expiry, and allowed IP range. Deploy the replacement token before revoking the old one.

Continue by task

• Live playback: regular channels, GB28181, HLS, HTTP-FLV, HTTP-fMP4, and ticket renewal.
• Recordings, clips, and deletion: search, play, download, clip/merge, soft-delete, restore, and hard-delete.
• RTC integration: business subject tickets, RTC tokens, WHIP/WHEP, active playback, and meeting archives.
• Third-party API reference by task: endpoints, permissions, main input, and completion checks.
• GB28181 APIs / ONVIF APIs: discovery, catalog, PTZ, presets, snapshot URIs, alarms, and talkback.
• Async commands and events / Outbound Webhooks: final-state polling, event deduplication, signing, retries, and replay.
• OpenAPI, Postman, and SDKs: exact fields, models, and importable test assets for the deployed version.

For every non-2xx response, preserve the HTTP status, code, message, and traceId. Never log a complete token or a URL containing ak_ticket.