> ## 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.

# Core concepts

> How the Adam Developer API models businesses, AI processing, banking, and financial reporting.

## One business, one secret key

Almost every route is scoped to a **single Tyms business**. You prove which business with the **business API secret** (`tyms_sk_...`) in a header. The API never mixes data across businesses.

The only exception on this base URL is **[Register business](/api-reference/register-business)**, which uses a **partner (distributor) API key** to create a new business. After registration, all other calls for that customer use the **new business’s** `tyms_sk_...` returned when `grant_access` is `admin`.

## AI-assisted creation vs REST updates

**Creates** for invoices, bills, expenses, income, journals, contacts, chart-of-accounts entries, and **bank transactions (upload)** are built around a natural-language **`prompt`** (and optional **attachments**). That mirrors how Adam works in the product: the backend interprets language and files, then writes structured records.

**Reads, updates, and deletes** use conventional REST patterns: list and get with query parameters; **PUT**/**PATCH**/**DELETE** with identifiers in the path. Update/delete paths accept **`uuid`** or **`source_uuid`** where documented in the [API overview](/api-reference/overview#uuid-resolution).

## Attachments and files

Several **POST** bodies accept an **`attachments`** array. Each element must be an **object** with required **`file`** and **`type`** (`base64`, `url`, or `raw`), and optional **`name`**. Base64 payloads must include **`"type": "base64"`** explicitly — the API does not infer encoding from the `file` string alone. This is required for correct handling and for bank-statement extraction.

Full field-level documentation: [Attachments](/api-reference/attachments).

## `process_type`: async vs direct

For AI create endpoints, **`process_type`** controls latency versus completeness:

| Value    | Behavior                                                                                                               |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `async`  | **Default** for the Developer API on most creates. The request returns quickly while work continues in the background. |
| `direct` | Processing runs in the same request; you wait for the AI pipeline to finish.                                           |

Bank transaction upload defaults to **`async`** on the Developer API unless you set `direct`.

## Banking and bank transactions

**Banks** are listed and fetched by UUID. **Bank transactions** can be listed, fetched, updated, and deleted like other resources.

**`POST /bank-transactions/upload`** is **not** a bulk JSON importer for arbitrary transaction arrays. It is the same **AI-assisted** flow as the product: a required **`prompt`** (and optional statement **attachments** and **`bank`** UUID) drives extraction and creation of statement lines.

## Financial reports and the in-app engine

These endpoints return financial reports **consistent with the Adam app** (interactive docs under **API reference** → **Reports**):

* [Income statement](/api-reference/report-income-statement)
* [Balance sheet](/api-reference/report-balance-sheet)
* [Trial balance](/api-reference/report-trial-balance)
* [Cash flow statement](/api-reference/report-cash-flow-statement)

Responses are structured for dashboards and exports (headings, nested `content`, totals). Date ranges and optional journal filters are query parameters on each **GET**.

## Dates, amounts, and timezone

* Dates in your prompts can be natural language; dates in **structured** JSON bodies use **ISO 8601** dates (`YYYY-MM-DD`) unless an endpoint documents a different format (e.g. `date_format` on bank upload).
* Monetary amounts in **structured** JSON should be **numeric** (no currency symbols in the JSON value).
* The API uses **UTC** by default; the validated business profile exposes **`timezone`** for display and business context.

## Error model and limits

Failures return JSON with **`status: "failed"`** and a **`message`**. Rate limit metadata may appear in **`X-RateLimit-*`** headers. Details: [API overview](/api-reference/overview) and [Error handling](/guides/error-handling).