Subtitle Feed Token API

POST /api/v1/auth/tasks/{taskId}/subtitle-feed-token

Description

Exchange for a short-lived access Token for the floating-subtitle feed. The Floating Subtitle SSE (Floating Subtitle SSE) subscribes read-only to the transcript of an in-progress recording over an independent connection. Because the browser's native EventSource does not support custom HTTP headers, a Token mechanism is used: first exchange an API Key for a feed_token bound to the recording, then connect to the SSE with that Token.

Authentication

Header: X-API-Key (see Authentication). Only the owner of the recording can exchange for a token.

Request Parameters

Request Example

curl -X POST "https://vas-poc.vurbo.ai/api/v1/auth/tasks/3f9a.../subtitle-feed-token" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

Success Response

HTTP 200

{
  "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl",
  "expires_in": 900
}

Response Fields

Token Characteristics

Race Handling

Immediately after recording starts, the backend may not have finished creating the recording. In that case the exchange returns 425 Too Early, and the client should retry after a short delay.

Specific Error Codes

Note: These three endpoints return errors as {"error": "<code>"} — the field name is error, not data.error_code as on other endpoints.

Audience Sharing

Besides the recording owner, the floating subtitle can also be shared with other on-site audience members. After the owner enables sharing, they receive a share secret to embed in a share link or QR code; an audience member exchanges that secret for a read-only audience Token and connects to the Floating Subtitle SSE.

• Audience access is read-only, requires no login and no API Key, and is not charged separately.
• The number of audience members per recording is capped (server-configured, default 10, excluding the owner). The current count and limit are available via the viewers event of the Floating Subtitle SSE (see Floating Subtitle SSE). Use the event's max field rather than hardcoding a value.
• Sharing ends automatically when the recording ends.

POST /api/v1/auth/tasks/{taskId}/subtitle-share

Enable (or reset) audience sharing and return a share secret. Only the owner of the recording may call this.

Authentication: Header X-API-Key.

Success Response (HTTP 200)

{
  "share_secret": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl",
  "expires_in": 43200
}

The share_secret is returned only once, at the moment of enabling; keep it in the share link.

DELETE /api/v1/auth/tasks/{taskId}/subtitle-share

Stop sharing and invalidate the share link. After stopping, no new audience members are admitted; existing audience connections end no later than their Token expiry or when the recording ends. Only the owner of the recording may call this.

Authentication: Header X-API-Key.

Success Response (HTTP 200)

{ "revoked": true }

POST /api/v1/public/tasks/{taskId}/subtitle-feed-token

An audience member exchanges a share secret for a read-only audience Token, then connects to the Floating Subtitle SSE with that Token. No login and no API Key required.

Request Example

curl -X POST "https://vas-poc.vurbo.ai/api/v1/public/tasks/3f9a.../subtitle-feed-token" \
  -H "Content-Type: application/json" \
  -d '{"share_secret":"aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl"}'

Success Response (HTTP 200)

{
  "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl",
  "expires_in": 900
}

The response fields are the same as the owner Token above; the returned Token likewise connects to the Floating Subtitle SSE via the feed_token query parameter. If the audience limit has been reached, the connection returns 429 (see Floating Subtitle SSE).

Rate Limits

• Up to 30 requests per minute for the same recording (all viewers combined, including requests with an invalid share link).
• When a limit is exceeded, HTTP 429 is returned with a Retry-After header (the number of seconds to wait). This error uses the standard error format (data.error_code is too_many_requests), unlike the {"error": ...} format of this endpoint's other errors.

Version: V1.24.1 Last Updated: 2026-10-05