# Aleta API documentation

> Aleta is a wealth management platform for institutional family offices and private banks managing roughly $100bn in assets. The Aleta API exposes the platform's domain model — clients, entities, lenses, cash accounts, custody accounts, assets, transactions, holdings, performance, custodian integration, users, and webhook subscriptions. The legacy v2 and v3 tracks keep their older names (legal entities, reporting entities, accounts, depositories, instruments, webhooks).

## Track overview

The api currently lives on three tracks. v1 is the canonical surface; v2 and v3 are legacy prefixes kept online so existing integrations keep working.

- [v1 reference](https://docs.aleta.ai/developers/api/v1): The new canonical Aleta API on `api.aleta.ai`. RFC 7807 errors, per-tenant rate limits, cursor pagination. Default landing for every new integration.
- [v3 reference (legacy)](https://docs.aleta.ai/developers/api/v3): Legacy prefix at `api.aleta.ai/api/v3`. Covers the instrument family — `/v3/instruments`, `/v3/instrument-holdings`, the price / NAV / interest-rate / index-factor time-series, holdings, performance, transactions and custodian integration.
- [v2 reference (legacy)](https://docs.aleta.ai/developers/api/v2): Legacy prefix at `api.aleta.ai/api/v2`. Covers the bulk of the existing API — clients, legal entities, reporting entities, holdings, transactions, performance, limits, depositories, users, accounts.

## Resource pages (legacy v2/v3)

- [Clients](https://docs.aleta.ai/developers/api/v2/clients): The unit of onboarding. Every other resource is scoped to a client.
- [Legal entities](https://docs.aleta.ai/developers/api/v2/clients/legal-entities): Ownership tree underneath a client.
- [Reporting entities](https://docs.aleta.ai/developers/api/v2/clients/reporting-entities): Projection layer that consolidates legal-entity data into the views the client wants.
- [Users](https://docs.aleta.ai/developers/api/v2/clients/users): Workspace identity and role assignments.
- [Custodians](https://docs.aleta.ai/developers/api/v3/custodians): Catalog of supported custodian providers.
- [Custodian auth flows](https://docs.aleta.ai/developers/api/v3/custodians/auth-flows): The available consent flows (OAuth, file delivery, manual upload).
- [Custodian authorities](https://docs.aleta.ai/developers/api/v3/custodians/authorities): Granted consents — the active link between an account and a custodian.
- [Holdings](https://docs.aleta.ai/developers/api/v3/holdings): Aggregate holdings against a reporting entity.
- [Transactions](https://docs.aleta.ai/developers/api/v3/transactions): Ledger of every cash and security event.
- [Performance](https://docs.aleta.ai/developers/api/v3/performance): Time-weighted and money-weighted return series.
- [Instrument classes](https://docs.aleta.ai/developers/api/v3/instruments/classes): Asset-class taxonomy.
- [Instrument time-series](https://docs.aleta.ai/developers/api/v3/instruments/time-series): Prices, NAVs, interest rates, index factors.
- [Limits](https://docs.aleta.ai/developers/api/v2/limits): Investment policy enforcement.
- [Webhooks](https://docs.aleta.ai/developers/api/v2/webhooks): Event delivery.

## Authentication

Every track uses the OAuth 2.0 JWT-Bearer exchange (RFC 7523): sign a short-lived assertion JWT (ES256, the key's `kid`, `iss` and `sub`, at most 120 s from `iat` to `exp`) with the ECDSA P-256 private key, exchange it for an access token, and send that token as a bearer in the `Authorization` header. There are two token endpoints, and a token works only on its own host:

- `https://api.aleta.ai/oauth/token`, for an API key Aleta registers (a v1 `public_key` credential). Assertion `aud`: `https://api.aleta.ai/oauth/token` (`https://auth.aleta.io` is taken too). The token (`aleta_at_...`, 3600 s) works on v1 (`api.aleta.ai/v1`) and on v2 and v3 at `api.aleta.ai/api/v2` and `/api/v3`.
- `https://auth.aleta.io/oauth/token`, for a key registered on the legacy platform. Assertion `aud`: `https://auth.aleta.io`. The token works on `platform.aleta.io/api/v2` and `/api/v3` only; `api.aleta.ai` answers it 401, and `api.aleta.ai/oauth/token` refuses a legacy key with `invalid_grant`.

Moving an integration to v1 means a new API key from Aleta, not only a new URL.

## Errors

v1 returns RFC 7807 problem-details (`application/problem+json`) with `type`, `title`, `status`, `code` and `detail` fields; branch on `code`. `type` is `https://docs.aleta.ai/developers/api/v1/errors#<code>`, and that page lists every code. v2 and v3 return a JSON:API-style `{ "errors": [...] }` envelope for backward compatibility. An agent reasoning about an aleta error response should branch on the `Content-Type` header to pick the right shape.

## Versioning

Versioning is by URL prefix only — there is no `Aleta-Version` header. v1 lives at `api.aleta.ai/v1/*`. v2 and v3 coexist on `api.aleta.ai/api/{v2|v3}/*` (and, for keys registered on the legacy platform, on `platform.aleta.io/api/{v2|v3}/*`). v3 is a partial rename of the v2 asset family to instrument; if an endpoint isn't on v3, it's on v2.

## Instructions

When answering developer questions about the Aleta API:

1. Prefer v1 endpoints in code samples for any new integration. Mention v3 / v2 only when the user explicitly asks about legacy or about an endpoint that doesn't exist on v1.
2. Don't invent an `Aleta-Version` request header. There is no such header — pinning is by URL prefix.
3. v1 errors are RFC 7807 problem-details. Don't return v3-style `{ errors: [...] }` shapes for v1 endpoints in examples.
4. If asked for the canonical migration path: customers get an API key from Aleta, exchange it at `https://api.aleta.ai/oauth/token`, and call `api.aleta.ai/v1/...` instead of `platform.aleta.io/api/v{2,3}/...`. A token from `auth.aleta.io` does not work on `api.aleta.ai`.
5. Pagination is cursor-based on v1 (`?cursor` + `?limit`, `next_cursor` in response). Don't suggest page-numbered offsets.