Skip to main content
Base URL: https://api.useadam.io/v1/adam All paths below are relative to that prefix. Example: GET /auth/validate → https://api.useadam.io/v1/adam/auth/validate.

​
Try the API

On each page under API reference, you can:
  • See the full https://api.useadam.io/v1/adam/... URL for the operation
  • Use the interactive request panel to set query, path, and body fields and send a request
  • Copy sample code (cURL, Python, JavaScript); many endpoints include example request bodies you can adjust and run
  • Authenticate with your X-API-Key: business key tyms_sk_... for most routes, or a partner key only for Register business
Use Attachments for the attachments object shape (file + type required, including "type": "base64" for Base64 files).

​
Authentication summary

CredentialHeader(s)Used on
Business secret tyms_sk_...X-API-Key, api-key, or skAll routes except POST /register-business
Partner secret (e.g. adam_partner_sk_...)Same headersPOST /register-business only
Conceptual guide: Authentication.

​
Subscription gate

For business-scoped routes, the account must meet Adam’s Developer API subscription requirements. Otherwise the API returns 403 Forbidden.

​
Success envelope (typical)

Successful responses use a consistent JSON shape (see USEADAM_DEVELOPER_API.md in this repo for the full narrative): 
{
  "status": "success",
  "message": "…",
  "data": {}
}
  • Lists usually return data as an array and often include meta for pagination (page, limit, total).
  • Financial reports add meta.from and meta.to (and cash flow may include meta.previous_period_end).
  • AI creates with process_type: async (the default on most routes) typically return job-style fields inside data; use direct when you need the created resource in the same response.
Where we document them, success responses include example payloads so you see realistic JSON—not a bare OK.

​
Error responses

Failures use a consistent JSON shape: 
{
  "status": "failed",
  "message": "Error description"
}

​
Common HTTP status codes

CodeMeaning
200Success
201Created (when applicable)
400Invalid parameters or body (e.g. missing required prompt on bank upload)
401Invalid or missing API key
403Forbidden (e.g. Developer API not allowed for this business)
404Resource not found
500Server error
Chart-of-accounts delete may return 400 when the account is default, in use, or blocked by cashbook rules — the message explains why.

​
Rate limiting

Rate limits may apply. Check response headers:
  • X-RateLimit-Limit — max requests per window
  • X-RateLimit-Remaining — remaining in the current window
  • X-RateLimit-Reset — when the window resets
Implement backoff if you receive 429 Too Many Requests.

​
UUID resolution

For update and delete operations, path identifiers may be either:
  • the record uuid, or
  • the record source_uuid
The API resolves both to the same row when present. Example: if uuid is abc-123 and source_uuid is xyz-789, either value may appear in the path segment {uuid}. Get endpoints for specific records also accept whichever identifier your integration stores, where documented per resource.

​
Pagination and ordering

List endpoints commonly support:
  • page — page number
  • limit — page size
  • date_order — asc or desc (default desc where documented)
Some lists support extra filters (e.g. schema, search, bank, status). See each resource page.

​
AI create body pattern

Typical fields on POST creates:
FieldRequiredDescription
promptYes (for AI creates)Natural-language instructions
attachmentsNoArray of objects (file + type required on each) — Attachments
text_attachmentNoExtra plain text merged into AI context
process_typeNoasync (default on most routes) or direct
Exception: POST /bank-transactions/upload always requires prompt; see Create bank transactions (AI) in the API reference tab.

​
Support