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

# API quickstart

> Quickstart: Set Aside Money developer API reference.

This gets you from nothing to a working request in about two minutes.

## 1. Create a key

In the Set Aside Money web app, open **Settings**, find **Developer API**, and choose **API keys**.
Then **Create key**:

* Give it a name you will recognise later, like `Nightly export`.
* Choose **Read only** unless you already know you need to write.
* Pick an expiry. A year is the default.

The key is shown **once**. Copy it then, because it cannot be recovered afterwards. If you lose it,
revoke it and create another.

Keys look like this:

```
sam_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## 2. Check it works

Every key can call `/v1/me`, which tells you which account the key belongs to and what it is allowed
to do. It is the cheapest way to confirm your setup.

> **GET** `/v1/me` · Required scope: `data.read`

```bash theme={null}
curl https://api.setaside.money/v1/me \
  -H "Authorization: Bearer $SETASIDE_API_KEY"
```

```json theme={null}
{
  "account_id": "9f2c1b7e-4a3d-4c58-9e01-6b8d2f4a7c33",
  "scopes": ["data.read"],
  "key": { "id": "b3969e6a-8060-48eb-979c-dc15ab022a20", "expires_at": "2027-08-08T06:34:56.246Z" },
  "rate_limit": { "minute_limit": 60, "minute_remaining": 59, "hour_limit": 500, "hour_remaining": 499 }
}
```

## 3. Read something real

```bash theme={null}
curl "https://api.setaside.money/v1/transactions?limit=5" \
  -H "Authorization: Bearer $SETASIDE_API_KEY"
```

In JavaScript:

```js theme={null}
const response = await fetch("https://api.setaside.money/v1/transactions?limit=5", {
  headers: { Authorization: `Bearer ${process.env.SETASIDE_API_KEY}` },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const { data } = await response.json();
for (const transaction of data) {
  // Amounts are integer cents.
  console.log(transaction.booked_at, transaction.concept, transaction.amount / 100);
}
```

In Python:

```python theme={null}
import os
import requests

response = requests.get(
    "https://api.setaside.money/v1/transactions",
    headers={"Authorization": f"Bearer {os.environ['SETASIDE_API_KEY']}"},
    params={"limit": 5},
    timeout=30,
)
response.raise_for_status()

for transaction in response.json()["data"]:
    print(transaction["booked_at"], transaction["concept"], transaction["amount"] / 100)
```

Read the key from an environment variable or a secret manager rather than putting it in your
source. A key in a committed file is a key you will have to revoke.

## 4. Write something, if you need to

Writes need a key with the **Read and write** access. A read-only key gets a `403` with the code
`insufficient_scope`, which is a scope problem and not something a retry will fix.

```bash theme={null}
curl -X POST https://api.setaside.money/v1/transactions \
  -H "Authorization: Bearer $SETASIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-2026-08-08-001" \
  -d '{
    "account_id": "3f9a1c22-88b1-4a0e-9d77-2c5e6b0f1a44",
    "amount": -1250,
    "concept": "Coffee",
    "booked_at": "2026-08-08"
  }'
```

Note the negative amount: spending is negative, income is positive. And note the `Idempotency-Key`,
which means retrying this exact request will not create a second transaction. See
[errors](/api-reference/errors) for when to retry.

## Next

* [Authentication](/api-reference/authentication) for scopes, expiry, and revoking a key.
* [Pagination](/api-reference/pagination) for reading more than one page of transactions.
* [Transactions](/api-reference/transactions) for the full set of filters.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.