> ## 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.

# API overview

> What the REST API does and where to start.

The Allocait API lets an agent or script read a portfolio's rules and holdings, check them against those rules, preview a rebalance, set holdings to the share counts you hold now, and record deposits and withdrawals. Every request is scoped to the API key owner's own portfolios.

Allocait cannot approve, stop or place an order. A read returns a result computed from your rules and the prices you supply. A write sets the state you send, such as a share count. A cash movement records a deposit or withdrawal you already made. Nothing is sent to a broker.

New to the API? The [API quickstart](https://docs.allocait.app/api/quickstart.md) takes you from a key to a first check in four calls.

## Base URL

```
https://allocait.app/api/v1
```

Every endpoint in this reference is relative to this base URL.

## Versioning

The major version is the `/v1` at the end of the base URL. Send nothing else to pick a version.

A request to a path with no version, or to a version that doesn't exist, gets a `404` with `error_code` `NOT_FOUND`.

Changes within `/v1` are meant to be additive: a new route, a new response field, a new optional parameter, or a new value in a response enum. Ignore fields you don't know, and handle an `error_code` you don't know by its HTTP status.

A breaking change would ship as `/v2` beside `/v1`. The docs would announce the old version, along with `Deprecation` and `Sunset` response headers, before it is removed.

## What you can do

* Read a portfolio's holdings, allocation bands, position size ranges, and scenario rules
* Check compliance against those rules, using prices you supply
* Check a proposed change before you make it elsewhere (`POST /trades/check`; see [Check a change](https://docs.allocait.app/guides/check-before-you-trade.md))
* Work out the pro rata amounts that close a gap to the portfolio's targets
* Set holdings to the share counts you hold now, and record deposits and withdrawals
* Read and edit scenarios, asset classes and rules, or exchange them as rules text (see [Rules text](https://docs.allocait.app/concepts/rules-text.md))
* Export a setup file of your research definitions, or preview and apply one (see [ALLOCAIT.md](https://docs.allocait.app/concepts/setup-file.md))
* Read and write watchlists, Inputs, playbooks, monitors and charts
* Read the record of position and cash changes
* File support requests and feedback
* Subscribe to webhooks for compliance events (needs **Read and change** access)

A **Read only** key or connection can call every read and every check. Routes that write need **Read and change** access. See [Access levels](https://docs.allocait.app/concepts/access-levels.md).

To find the route for a job, use [Endpoints by task](https://docs.allocait.app/api/endpoints-by-task.md).

## Prices are always yours

Allocait's own stored market data is never returned by this API, and nothing computed from it is either: not a value, a compliance status, a trade, or a monitor reading. The pattern is two calls: fetch a portfolio snapshot to see what symbols need a price, then call again with a `prices` map for those symbols. See [Prices](https://docs.allocait.app/concepts/prices.md) for the full flow.

## Next steps

> [card] [API quickstart](https://docs.allocait.app/api/quickstart.md)
>
> A key, a first read, a first check and error handling.

> [card] [Authentication](https://docs.allocait.app/api/authentication.md)
>
> How to get and use an API key.

> [card] [Endpoints by task](https://docs.allocait.app/api/endpoints-by-task.md)
>
> The route and the MCP tool for each job.

> [card] [Conventions](https://docs.allocait.app/api/conventions.md)
>
> Lists, paging, ids and request format.

> [card] [Errors](https://docs.allocait.app/api/errors.md)
>
> The error envelope and status codes.

> [card] [Docs for agents](https://docs.allocait.app/docs-for-agents.md)
>
> Point an agent at these docs.

The MCP route to the same reads and checks is in [Connect an agent](https://docs.allocait.app/connect-an-agent.md).


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