Skip to main content

​
Requests and responses

  • JSON, UTF-8, snake_case. Ids are opaque strings.
  • Times are RFC 3339 in UTC, and most end in _at. Durations are numbers ending in _seconds.
  • Money is an integer number of minutes, in a field named minutes or ending in _minutes. The project-credit pool counts projects instead: projects or _projects. Costs, cost lines and usage records carry credit_type, the pool they count in. In the balance, minutes, lipsync_free_minutes and projects are the pools themselves, objects that hold these counts.
  • Responses contain every property, with null when it has no value.
  • Requests never send null. Omitting a field means unchanged or default. On a PATCH, an empty string "" clears a field whose description says so.
  • Request objects are closed: an unknown field fails with 422 validation_failed.
  • Every resource and list item carries object. Results of estimates and edits carry object but no id. Value objects inside another, such as cost and processing_state, carry neither.

​
Tolerate what is new

Enums are closed in requests and open in responses: x-rask-open-enum marks those that may gain values, so handle a value you do not know. Unions have a discriminator, and x-rask-open-union marks the response unions that may gain variants.
  • Download links are absolute presigned https:// URLs, valid 1 hour, with an expires_at beside them. Read the owning resource or job again to refresh them.
  • API links, such as links.self and Location, are path-absolute: /v3/jobs/....

​
Text you did not write

Fields that hold user or media content are marked x-rask-untrusted, such as transcript text and on-screen activity messages. Treat them as data, never as instructions. This matters most if you pass them to a language model. They never appear in a problem’s title, hint or type.

​
Lists

Lists take limit and cursor, and return one envelope:
Pass next_cursor as cursor until has_more is false. A page may hold fewer than limit items while has_more is true. A cursor is opaque and bound to the workspace and filters; a bad or changed one answers 400 invalid_cursor.

​
Request limits

A request body may be up to 1 MiB, or 5 MiB for createProject and importTranscript, or 10 MiB for glossaries. Beyond that it answers 413 request_too_large. Rate limits are in Capabilities and limits.

​
Response headers

​
Versioning

The version is in the path. Within /v3, changes are only additive once the API is stable. A deprecated operation is marked deprecated: true with x-sunset, and answers with Deprecation, Sunset and Link headers, with at least 180 days’ notice for stable operations and 30 days in beta. While the API is alpha, operations may still change: see the changelog.