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

# Conventions

> Ids, field types, Content-Type and body parsing.

Send JSON, send ids as UUIDs, and keep a body under 1,000,000 bytes. A request that breaks one of these gets a `400` or `413` with the [standard error envelope](https://docs.allocait.app/api/errors.md).

## Version in the path

Every route sits under `/v1`. A path without a version, or with a version that doesn't exist, gets a `404` that names the supported version.

## Lists and paging

* A list route returns `{ "data": [...], "has_more": false }`.
* A route that pages takes `limit` (default 100, up to 500) and `cursor` (a row offset, default 0).
* A route that doesn't page returns its whole result with `has_more` set to `false`.
* While `has_more` is `true`, call again with `cursor` set to the previous `cursor` plus `limit`.
* A bulk array accepts up to 500 items.

## Ids and field types

Send each id as a UUID and each field as the type the reference gives.

| Case | Response |
| - | - |
| An id in the query or body that isn't a UUID | `400` with a message that names it (`portfolio_id must be a UUID`) |
| In the path, an id made of 36 hex digits and dashes that isn't a valid UUID | `400` (`The id in the path must be a UUID`) |
| In the path, any other shape | No route matches, so `404` |
| A field of the wrong type | `400` (`initial_cash must be a number`), and nothing is created or changed |

On a create, `null` counts as not sent.

A list scoped to an id answers `404` when the id isn't yours, so an empty `data` means the list is empty.

## Content-Type and body parsing

* A request with a `Content-Type` header that is present and isn't `application/json` gets `400` with `Content-Type must be application/json`, before any other validation runs.
* A request with no `Content-Type` at all is still parsed as JSON.
* A body that is present but doesn't parse as valid JSON gets its own `400` (`Request body is not valid JSON`), distinct from the "field is required" error an empty body produces.
* A body larger than 1,000,000 bytes gets `413` with `error_code: INVALID_INPUT`.

## Related

* [API errors](https://docs.allocait.app/api/errors.md): the envelope and status codes.
* [Error codes](https://docs.allocait.app/api/error-codes.md): every code and its common causes.
* [Rate limits](https://docs.allocait.app/api/rate-limits.md): request budgets.


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