API reference · v3

v3 is the current track. Every integration going live today builds against these endpoints — they're stable, fully documented, and the default behaviour returned when no version header is supplied.

Base URL

https://api.aleta.io

Every path below is relative to this origin. Pin to v3 explicitly by sending the Aleta-Version header on every request; omit the header and the account's default version kicks in.

curl https://api.aleta.io/v3/instrument-holdings/reporting-entities/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Aleta-Version: v3"

How v2 and v3 relate

v2 and v3 are two overlapping URL tracks rather than full replacements. Some resources only exist on v2 (/v2/clients, /v2/legal-entities); others on both; a few newer shapes ship v3-only (/v3/instrument-holdings with per-lot detail, the /v3/instruments/{id}/prices time-series family). The version switcher above scopes the sidebar to whichever track you're currently reading.

The rule of thumb: reach for v3 unless you're maintaining an integration already running on v2.

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 through legal entities or reporting entities.

• Clients own the data. A single Aleta workspace has one or more clients (a family office might split operating entities from a family trust). Inside a client, the legal entity structure captures ownership; the reporting entity structure captures how the client wants to view it.
• Custodian integration is how wealth data lands on the platform. Every account is linked to a custodian via a custodian authority that's granted through an auth flow (OAuth, file drop, read-only credentials). The platform maintains the consent lifecycle.
• Data endpoints (holdings, transactions, performance) are what integrators typically read out. They operate against reporting entities — the consolidated views the client has configured.
• Instruments describe everything you can hold — listed securities, private assets, derivatives, cash positions. Time-series data (prices, NAVs, interest rates, index factors) hangs off each instrument.
• Platform concerns sit on top: limits (investment policy enforcement), webhooks (event delivery).

Stability

v3 is stable. Additive changes (new optional fields, new endpoints) roll into v3 without a new version. Breaking changes ship as a new track (v4, when it arrives) and run in parallel for at least 12 months before an older track is sunset.