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

curl https://api.setaside.money/v1/me \
  -H "Authorization: Bearer $SETASIDE_API_KEY"

{
  "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

curl "https://api.setaside.money/v1/transactions?limit=5" \
  -H "Authorization: Bearer $SETASIDE_API_KEY"

In JavaScript:

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:

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.

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 for when to retry.

Next

• Authentication for scopes, expiry, and revoking a key.
• Pagination for reading more than one page of transactions.
• Transactions for the full set of filters.