API overview — AccountantOS Docs

What the API is

A read-only REST API, scoped to one client per credential: a client’s own systems (or yours, acting for them) can read that client’s profile, tasks, bills and deadlines — and nothing else. There is no practice-wide key and no write access in v1; both are deliberate, and the roadmap note below says what’s coming.

Base URL and versioning

Base URL

https://app.accountantos.co.uk/api/v1

The path is the version. Additive changes — new fields, new endpoints — ship into v1 and are non-breaking; removals or renames only ever happen in a future /api/v2, with v1 kept alive through an announced deprecation window. Build against the fields you use and ignore ones you don’t recognise.

Authentication

Credentials are per client, found in Settings → API access with that client selected (the Settings reference covers who can generate and reveal them). A credential is a public client ID (aos_ci_…, stable across rotation — safe in logs and support threads) and a secret (aos_sk_…) sent as a bearer token:

Every request

curl https://app.accountantos.co.uk/api/v1/ping \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Rotating the secret (Settings → API access → Rotate) invalidates the old one immediately — no grace window — and keeps the client ID. The API is server-to-server only: no CORS headers are sent, because a bearer secret has no business in browser JavaScript.

Rate limits

Limit	Scope	Window	On excess
120 requests	per credential	1 minute	`429` with `Retry-After`
30 failed auth attempts	per IP	1 minute	`429` with `Retry-After`

Errors

Every error is the same envelope — code is machine-readable and frozen; message is prose and may be reworded:

Error envelope

{
  "error": {
    "code": "invalid_status",
    "message": "status must be one of: todo, in-progress, review, done, stuck"
  }
}

Status	Meaning
400	The request is malformed — a parameter failed validation
401	We don't know who you are — missing, malformed or wrong secret (revoked secrets answer identically)
403	We know who you are, and the answer is no — e.g. the client is archived
404	No such resource for this client — ids never resolve across clients
429	Over a rate limit — honour Retry-After
500	Our fault; safe to retry with backoff

What's coming

PlannedWrite endpoints (create tasks, upload bills), more resources (financials summaries, files metadata), and outbound webhooks are on the roadmap. No dates promised in documentation — additions will appear in the endpoint reference as they ship.