API reference · v2

v2 covers the bulk of Aleta's legacy API: clients, users, legal entities, accounts, depositories, reporting entities, portfolios, transactions, performance, limits, and webhook signing keys. In early 2026 the asset family of endpoints was relabelled to instrument and moved to a new v3 prefix; custodian integration (auth flows and authorities) also lives on v3 only. v2 and v3 share the same backend on the same host.

Base URL

https://platform.aleta.io

curl https://platform.aleta.io/api/v2/clients \
  -H "Authorization: Bearer {access_token}"

Authentication

curl -X POST https://auth.aleta.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion={signed_jwt}"

curl https://platform.aleta.io/api/v2/clients \
  -H "Authorization: Bearer {access_token}"

JSON:API conventions

{
  "data": {
    "type": "client",
    "id": "6710efbc34673a0a646a45de",
    "attributes": {
      "name": "Andersen Family Office"
    },
    "relationships": {
      "legalEntities": { "data": [...] },
      "reportingEntities": { "data": [...] }
    }
  }
}

{
  "errors": [
    {
      "status": "404",
      "code": "client_not_found",
      "title": "Client not found",
      "detail": "No client matched the supplied id."
    }
  ]
}

Pagination

v2 and v3 list endpoints return every matching row in a single response. There is no cursor parameter on these tracks — the platform applies a server-side row cap on large responses, so constrain queries with the documented filter parameters (e.g. accountId plus fromDate/toDate on transactions) to keep responses bounded.

Cursor pagination lands on v1 — every list endpoint there takes a cursor and a limit and returns the next cursor in the response.

Rate limits

Every request is counted against a per-tenant budget keyed off the access token's sub claim. The default budget is 1,000 requests per minute with a 300-call burst, isolated per tenant. Over-budget responses are 429 Too Many Requests with a Retry-After: <seconds> header carrying the wait window before the next token replenishes.

The same budget applies on v1, v2, and v3 — one access token, one shared rate-limit bucket.

Idempotency

v2 and v3 do not accept an Idempotency-Key request header. Retry-safety on POST is per-endpoint:

• Historical-upload endpoints keyed on a natural identifier — (account, date) for account-holdings, (depository, instrument, date) for instrument-holdings — overwrite the existing row on re-post, so retrying is safe.
• DELETE is naturally idempotent: deleting an already-deleted resource returns 404, not 200, so client-side retry loops stay simple.
• Other POST and PATCH endpoints are not retry-safe by default. If a request times out, fetch the resulting resource before retrying to avoid duplicates.

How v2 and v3 split

/v2/asset*           →  /v3/instrument*
/v2/asset-holdings   →  /v3/instrument-holdings

Resource groups

The reference is organised around Aleta's domain model rather than generic CRUD slices. Start with Clients — every other resource is scoped to a client.

What's different on v1

v1 is a clean rewrite, not an incremental bump. Highlights for anyone planning to migrate.

Stability

v2 is frozen. No new endpoints, no new optional fields, no new behaviour — only security fixes. New capabilities land on v1 instead.