View as Markdown

API reference · v3

v3 is not a parallel rewrite of v2 — it is a partial rename plus a small set of additions. In early 2026 the asset family of endpoints was relabelled to instrument and moved to a new URL prefix. The instrument-holdings endpoint (lot-level holdings) was renamed at the same time, and the time-series families were consolidated under instrument sub-paths and direct series addressing. Custodian integration (auth flows and authorities) also lives only on v3 — v2 never exposed top-level custodian endpoints. Everything else stayed on v2. Both prefixes are served by the same legacy backend on the same host.

Base URL

Every path on v3 is relative to https://platform.aleta.io. Versioning is by URL prefix only — there is no version header. Each endpoint is pinned to either v2 or v3 based on which family it belongs to.

Base URL

https://platform.aleta.io

Call a v3 endpoint

GET/api/v3/instrument-holdings/reporting-entities/{id}
curl https://platform.aleta.io/api/v3/instrument-holdings/reporting-entities/{id} \
  -H "Authorization: Bearer {access_token}"

Authentication

v3 uses the same OAuth 2.0 JWT-Bearer flow as v2 — the same access tokens authenticate both tracks. See v2 → Authentication for the full handshake. The same access tokens also work on v1.

JSON:API conventions

v3 follows the JSON:API specification. Every request and response uses the application/vnd.api+json media type, every resource is wrapped in a top-level data envelope with type, id, attributes, and relationships, and every error response uses the JSON:API errors array. Attribute names are camelCase. The error envelope is identical to v2 — see v2 → JSON:API conventions.

Pagination

Same model as v2 — list endpoints return every matching row in a single response, capped server-side. See v2 → Pagination.

Rate limits

Same model as v2 — 1,000 requests per minute per tenant with a 300-call burst, 429 Too Many Requests plus Retry-After: <seconds> over budget. See v2 → Rate limits.

Idempotency

Same model as v2 — no Idempotency-Key header at the protocol level; retry-safety is per-endpoint. See v2 → Idempotency.

What lives on v3

The v3 prefix covers three families:

  • Instruments and their time-series. The instrument catalog plus the price, NAV, interest-rate, index-factor, and private-instrument families that hang off it. Renamed from the v2 asset family in early 2026.
  • Lot-level holdings. Per-lot detail rather than the aggregate shape v2 returns, plus the consolidated holdings projection at the reporting-entity level.
  • Custodian integration. Auth flows and authorities. v2 never exposed top-level custodian endpoints — these are v3-only.

Anything else lives at /api/v2/... — see the v2 reference.

v3 endpoint paths

/api/v3/instruments
/api/v3/instruments/{id}
/api/v3/instruments/{reportingEntityId}/private-instruments
/api/v3/instrument-classes/{id}
/api/v3/instrument-classes-detailed/{id}

Resource groups

  • Name
    Custodian integration
    Description

    Auth flows and authorities. How wealth data lands on the platform — every account is linked to a custodian via an authority granted through an auth flow. v3 exposes the read side; the write side of the lifecycle is currently driven through workspace admin.

  • Name
    Instruments
    Description

    Everything you can hold — listed securities, private assets, derivatives, cash positions. The catalog, the classification taxonomy, and the time-series that hang off each instrument.

  • Name
    Holdings
    Description

    Consolidated and lot-level positions for a reporting entity, plus the historical-data uploads for backfilling instrument holdings.

For everything else — clients, users, legal entities, reporting entities, transactions, performance, limits, and webhooks — see the v2 reference.

Stability

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