> ## Documentation Index
> Fetch the complete documentation index at: https://developer.usetyms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Base URL, conventions, errors, rate limits, and identifier rules for the Adam v1 Developer API.

**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](/api-reference/attachments) for the `attachments` object shape (`file` + **`type`** required, including `"type": "base64"` for Base64 files).

## Authentication summary

| Credential                                    | Header(s)                                     | Used on                                                                                      |
| --------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Business secret `tyms_sk_...`                 | `X-API-Key`, `api-key`, or `sk`               | All routes **except** `POST /register-business` and OAuth steps that document their own auth |
| Partner secret (e.g. `adam_partner_sk_...`)   | Same headers                                  | **`POST /register-business` only**                                                           |
| OAuth (app `tyms_sk_...` + user Bearer token) | `X-API-Key` **and** `Authorization: Bearer …` | Business-scoped routes after [OAuth authorization](/oauth)                                   |

Conceptual guides: [Authentication](/authentication), [OAuth 2.0](/oauth).

## 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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "status": "failed",
  "message": "Error description"
}
```

### Common HTTP status codes

| Code  | Meaning                                                                    |
| ----- | -------------------------------------------------------------------------- |
| `200` | Success                                                                    |
| `201` | Created (when applicable)                                                  |
| `400` | Invalid parameters or body (e.g. missing required `prompt` on bank upload) |
| `401` | Invalid or missing API key                                                 |
| `403` | Forbidden (e.g. Developer API not allowed for this business)               |
| `404` | Resource not found                                                         |
| `500` | Server 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:

| Field             | Required             | Description                                                                                         |
| ----------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
| `prompt`          | Yes (for AI creates) | Natural-language instructions                                                                       |
| `attachments`     | No                   | Array of objects (`file` + **`type`** required on each) — [Attachments](/api-reference/attachments) |
| `text_attachment` | No                   | Extra plain text merged into AI context                                                             |
| `process_type`    | No                   | `async` (default on most routes) or `direct`                                                        |

**Exception:** `POST /bank-transactions/upload` always requires `prompt`; see [Create bank transactions (AI)](/api-reference/bank-transactions-upload) in the **API reference** tab.

## Support

* Email: [developer@useadam.io](mailto:developer@useadam.io)