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

# API Overview

> Access your Kualia data programmatically with the public REST API

The Kualia API is a REST API that gives you full read and write access to your budget — transactions, accounts, merchants, categories, and monthly envelope assignments. Use it to build scripts, sync data into spreadsheets, or connect Kualia to your own tools.

**Base URL**

```text theme={null}
https://api.kualia.com/v1
```

## Quick start

**1. Create an API key.** In the web app, go to **Settings → API Keys** and click **Create Key**. Copy the key when it's shown — it's only displayed once.

**2. Find your workspace id.**

```bash theme={null}
curl https://api.kualia.com/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**3. Fetch your transactions.**

```bash theme={null}
curl "https://api.kualia.com/v1/workspaces/WORKSPACE_ID/transactions?since_date=2026-07-01" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response format

Every successful response wraps its payload in a `data` object:

```json theme={null}
{
  "data": {
    "currency": "USD",
    "transactions": [
      {
        "id": "k1730s...",
        "date": "2026-07-05",
        "amount": "-12.34",
        "account_id": "k4859a...",
        "account_name": "Chase Checking",
        "merchant_id": "k9921m...",
        "merchant_name": "Starbucks",
        "category_id": "k5511c...",
        "category_name": "Dining Out",
        "status": "cleared",
        "review_status": "reviewed",
        "type": "regular",
        "notes": null,
        "splits": null,
        "deleted": false
      }
    ],
    "next_cursor": null
  }
}
```

Errors return a matching `error` object — see [Errors](/api/errors).

## Conventions

| Convention | Detail                                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Amounts    | Decimal strings in the workspace currency, e.g. `"-12.34"`. Negative = money out, positive = money in. No milliunits, no cents-as-integers. |
| Dates      | `YYYY-MM-DD` strings. Budget months are `YYYY-MM`.                                                                                          |
| Ids        | Opaque strings returned by the API. Pass them back exactly as received.                                                                     |
| Field case | All request and response fields are `snake_case`.                                                                                           |
| Writes     | `POST` creates, `PATCH` partially updates (send only the fields you want to change), `DELETE` deletes.                                      |
| Currency   | Workspace-scoped responses include a top-level `currency` code so you always know what unit amounts are in.                                 |

## Endpoints at a glance

| Resource                                             | Operations                                                            |
| ---------------------------------------------------- | --------------------------------------------------------------------- |
| [`/user`](/api/workspaces)                           | Get the authenticated user                                            |
| [`/workspaces`](/api/workspaces)                     | List and get workspaces                                               |
| [`/workspaces/{id}/accounts`](/api/accounts)         | List, get, create, update, close, delete accounts                     |
| [`/workspaces/{id}/transactions`](/api/transactions) | List, get, create (incl. transfers & splits), update, delete, restore |
| [`/workspaces/{id}/merchants`](/api/merchants)       | List, get, create, rename, delete (with optional merge)               |
| [`/workspaces/{id}/categories`](/api/categories)     | List, get, create, update, archive, delete; manage groups             |
| [`/workspaces/{id}/months/{month}`](/api/months)     | Read a budget month; set assigned amounts per category                |

<Note>
  Prefer talking to your budget from an AI assistant instead of code? Kualia also ships a hosted [MCP
  server](/mcp/overview) with OAuth — no API keys needed.
</Note>