> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.rask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions: requests, responses and lists

> How the Rask API v3 shapes data: JSON rules, nulls, open enums, pagination, untrusted text, request limits and versioning.

## 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](https://docs.api.rask.ai/operations/getBalance.md), `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`](https://docs.api.rask.ai/errors/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.

## Links

* 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:

```json theme={null}
{ "object": "list", "data": [], "next_cursor": null, "has_more": false }
```

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`](https://docs.api.rask.ai/errors/invalid_cursor).

| List | Default `limit` | Most |
| - | - | - |
| Most lists | 20 | 100 |
| Segments, version segments, voices | 100 | 500 |
| Voice clones | 50 | 100 |

## Request limits

A request body may be up to 1 MiB, or 5 MiB for [createProject](https://docs.api.rask.ai/operations/createProject.md) and [importTranscript](https://docs.api.rask.ai/operations/importTranscript.md), or 10 MiB for glossaries. Beyond that it answers 413
[`request_too_large`](https://docs.api.rask.ai/errors/request_too_large). Rate limits are in [Capabilities and limits](https://docs.api.rask.ai/v3/concepts/capabilities.md#rate-limits).

## Response headers

| Header | When |
| - | - |
| `X-Request-Id` | Always. Quote it to support; it is also in a problem's `instance` |
| `RateLimit-Policy`, `RateLimit` | On authenticated responses. These follow an IETF draft and are provisional. `RateLimit` is an estimate: [request limits are approximate](https://docs.api.rask.ai/v3/concepts/capabilities.md#rate-limits) |
| `Retry-After` | On every 429 and 503, on some 409s that ask you to wait, such as [`idempotency_key_in_use`](https://docs.api.rask.ai/errors/idempotency_key_in_use) and [`transcript_busy`](https://docs.api.rask.ai/errors/transcript_busy), and while a job is not terminal: on its reads, and on a `202` that starts that one job |
| `ETag` | On reads of a resource that has one |
| `Location` | On every `201`, with the path of the new resource, and on `202` responses that start one job |
| `Idempotent-Replayed: true` | On a replayed response |

## 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](https://docs.api.rask.ai/changelog.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.