# API

The Whisper Money API lets your own scripts and apps read your data and change it over HTTP: accounts, transactions, categories, budgets and the rest of what you see in the app.

## What it is

A REST API that answers JSON. It reaches your own data, the same data you see
in the app, and nobody else's. It is meant for automating your finances: a
script that exports your transactions to a spreadsheet every night, a home
dashboard, or an app you build for yourself.

If what you want is to ask an assistant like Claude or ChatGPT about your money,
you do not need the API: the [AI Connector](https://whisper.money/documentation/ai-connector) does
that without writing any code.

The API is part of the paid plan. When a subscription ends, its tokens stay but
every request answers `403` until you subscribe again.

## Base URL

Every endpoint lives under:

```text
https://whisper.money/api/v1
```

The API only speaks HTTPS and JSON. Send `Accept: application/json`, and
`Content-Type: application/json` with any request that has a body.

## Your first request

1. Open **Settings → API** and create a token. Copy it: it is shown only once.
2. List your spaces with it:

```bash
curl https://whisper.money/api/v1/spaces \
  -H "Authorization: Bearer wm_api_your_token_here"
```

The answer is your spaces, wrapped in `data`:

```json
{
    "data": [
        {
            "id": "0199a3f2-6c1e-7b4d-9a8e-2f5c1d3b4a60",
            "name": "Personal",
            "personal": true,
            "owned": true,
            "created_at": "2026-01-15T09:30:00+00:00"
        }
    ]
}
```

The rest of the examples in these pages read the token from an environment
variable, so set it once in your shell:

```bash
export WHISPER_MONEY_TOKEN=wm_api_your_token_here
```

## How it behaves

These pages describe what every endpoint has in common. Read them once before
writing a client:

- [Authentication](https://whisper.money/documentation/api/authentication): personal tokens, OAuth
  apps and the scopes each one carries.
- [Amounts and currencies](https://whisper.money/documentation/api/amounts-and-currencies): amounts
  are integers in each currency's smallest unit.
- [Spaces](https://whisper.money/documentation/api/spaces): the `space` parameter.
- [Pagination](https://whisper.money/documentation/api/pagination): how lists are paged.
- [Errors](https://whisper.money/documentation/api/errors): the shape of every error.
- [Rate limits](https://whisper.money/documentation/api/rate-limits): 60 requests a minute.
- [Idempotency](https://whisper.money/documentation/api/idempotency): retrying a create safely.
- [Changelog](https://whisper.money/documentation/api/changelog): what changed, and when.

The [API reference](https://whisper.money/documentation/api/reference) lists every endpoint, with
its parameters, an example request and an example response.

## OpenAPI spec

The whole API is described as an OpenAPI 3.1 document at
[https://whisper.money/api/v1/openapi.json](https://whisper.money/api/v1/openapi.json).
It needs no token, so you can load it into Postman, Insomnia or a code
generator, or hand it to an AI agent that writes the client for you.

---

Pages inside this one:

- [Authentication](https://whisper.money/documentation/api/authentication.md?lang=en): Every request carries a bearer token: a personal token you create in Settings, or an OAuth access token an app gets when you approve it.
- [Amounts and currencies](https://whisper.money/documentation/api/amounts-and-currencies.md?lang=en): Every amount is an integer in the smallest unit of its own currency, next to the currency it is in.
- [Spaces](https://whisper.money/documentation/api/spaces.md?lang=en): Your data is organised in spaces: your personal space and any space someone shared with you. Endpoints that work on one take an optional `space` parameter.
- [Pagination](https://whisper.money/documentation/api/pagination.md?lang=en): Lists that can grow long come back a page at a time, and you walk them with a cursor: the id of the last object you received.
- [Errors](https://whisper.money/documentation/api/errors.md?lang=en): The API answers with standard HTTP status codes, and every error body has the same shape: a message for you and a code for your program.
- [Rate limits](https://whisper.money/documentation/api/rate-limits.md?lang=en): Each user can make 60 requests a minute, across all of their tokens and connected apps.
- [Idempotency](https://whisper.money/documentation/api/idempotency.md?lang=en): Send an `Idempotency-Key` header with a `POST` and you can retry it after a timeout without creating the same thing twice.
- [API reference](https://whisper.money/documentation/api/reference.md?lang=en): Every endpoint of the Whisper Money API, grouped by resource. The base URL is `https://whisper.money/api/v1`, and the full OpenAPI spec is at [https://whisper.money/api/v1/openapi.json](https://whisper.money/api/v1/openapi.json).
- [Changelog](https://whisper.money/documentation/api/changelog.md?lang=en): Every change to the API that could affect your code, newest first.

Full documentation index: https://whisper.money/documentation.md?lang=en