HTTP API

The library is the product; this is one adapter over it. Responses use Plaid's wire format, so a client that already consumes Plaid consumes this: /crypto/sync returns added/modified/removed with a cursor, and every amount is a tagged decimal string.

Two credentials, both yours to issue: a server key (adk_live_…) your backend holds, and a short-lived user token minted from it for one end user. See Authentication & keys.

A route appears here only if its capability is bound: POST /batch/holdings exists only when a holdings provider is injected. Download openapi.json.

`POST /auth/revoke`

Revoke User Token

Revoke one jti. Idempotent; an unowned token is one plain 401.

Request body

tokenrequired, string

Token

Response fields (200)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X POST 'https://api.example.com/auth/revoke' \
  -H 'Authorization: Bearer <token>'

`POST /auth/token`

Mint User Token

Mint one short-lived user JWT. Body is exactly {"token"}.

Request body

external_user_idrequired, string

External User Id

scopesoptional, object

Scopes

Response fields (200)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X POST 'https://api.example.com/auth/token' \
  -H 'Authorization: Bearer <token>'

`POST /batch/holdings`

Batch Holdings

Allium's union: partial success, one quota unit per item.

Request body

itemsrequired, array

Items

Response fields (200)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X POST 'https://api.example.com/batch/holdings' \
  -H 'Authorization: Bearer <token>'

`GET /connections`

List Connections

This user's connections in creation order; never anyone else's.

Response fields (200)

Shape depends on the route.

Example

curl -X GET 'https://api.example.com/connections' \
  -H 'Authorization: Bearer <token>'

`POST /connections`

Create Connection

Create one connection and emit exactly one event.

Request body

kindrequired, string

What a Connection watches: an address, an xpub, an exchange key (SPEC §3.1).

descriptorrequired, string

Descriptor

Response fields (201)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X POST 'https://api.example.com/connections' \
  -H 'Authorization: Bearer <token>'

`GET /connections/{connection_id}`

Read Connection

One connection the caller owns; 404 for every other id.

Request fields

connection_idrequired, string (in path)

none

Response fields (200)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X GET 'https://api.example.com/connections/{connection_id}' \
  -H 'Authorization: Bearer <token>'

`GET /coverage`

Coverage

Generated from the registry and the bound capabilities only.

Response fields (200)

Shape depends on the route.

Example

curl -X GET 'https://api.example.com/coverage' \
  -H 'Authorization: Bearer <token>'

`GET /crypto/sync`

Crypto Sync

One page of Plaid's envelope for the calling end user.

Request fields

cursoroptional, string (in query)

none

limitoptional, string (in query)

none

Response fields (200)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X GET 'https://api.example.com/crypto/sync' \
  -H 'Authorization: Bearer <token>'

`GET /users`

List Users

This project's users in creation order, never another's.

Response fields (200)

Shape depends on the route.

Example

curl -X GET 'https://api.example.com/users' \
  -H 'Authorization: Bearer <token>'

`GET /users/me`

Read Current User

The caller's own user record, created on first sight (§7.1).

Response fields (200)

Shape depends on the route.

Example

curl -X GET 'https://api.example.com/users/me' \
  -H 'Authorization: Bearer <token>'

`GET /webhooks/dead_letter`

Dead Letter

The operator view: deliveries that burned all six attempts.

Response fields (200)

Shape depends on the route.

Example

curl -X GET 'https://api.example.com/webhooks/dead_letter' \
  -H 'Authorization: Bearer <token>'

`GET /webhooks/deliveries`

List Deliveries

Every delivery in creation order, optionally filtered by status.

Request fields

statusoptional, string (in query)

none

Response fields (200)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X GET 'https://api.example.com/webhooks/deliveries' \
  -H 'Authorization: Bearer <token>'

`POST /webhooks/deliveries/{delivery_id}/replay`

Replay Delivery

Re-arm one delivery; the original row is never mutated.

Request fields

delivery_idrequired, string (in path)

none

Response fields (202)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X POST 'https://api.example.com/webhooks/deliveries/{delivery_id}/replay' \
  -H 'Authorization: Bearer <token>'

`GET /webhooks/endpoints`

List Endpoints

This project's endpoints, in registration order, secretless.

Response fields (200)

Shape depends on the route.

Example

curl -X GET 'https://api.example.com/webhooks/endpoints' \
  -H 'Authorization: Bearer <token>'

`POST /webhooks/endpoints`

Register Endpoint

Self-serve registration; the secret is returned exactly once.

Request body

urlrequired, string

Url

eventsoptional, object

Events

Response fields (201)

Shape depends on the route.

Response fields (422)

detailoptional, array

Detail

Example

curl -X POST 'https://api.example.com/webhooks/endpoints' \
  -H 'Authorization: Bearer <token>'