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

# Quickstart

> Record your first expense from a script in a few minutes.

> [!TIP]
>
> Prefer the terminal? The [`visor` CLI](https://docs.visorfinance.app/cli) does these steps with `visor auth login` and `visor tx add`.

**1. Create a token**

Open [Settings > Connected apps](https://dashboard.visorfinance.app/settings/connected_apps) in Visor and find the **Personal API** card.

1. Give the token a name you will recognize, such as `Spending spreadsheet`.
2. Choose what the token can do. Choose **Read and record transactions**, because this quickstart records an expense.
3. Choose how long it is valid: 30, 90 (default), or 365 days. **Never expires** is also available, but a token with an expiry is safer.
4. Select **Create token** and copy the value that starts with `visor_pat_`.

> [!WARNING]
>
> Visor shows the token only once. Store it in a password manager or a secret store. If you lose it, revoke it and create a new one.

**2. Store the token in an environment variable**

```bash theme={null}
export VISOR_TOKEN="visor_pat_..."
```

Keep the token out of source code, URLs, and logs.

**3. List your spaces**

```bash theme={null}
curl https://api.visorfinance.app/v1/spaces \
  --header "Authorization: Bearer $VISOR_TOKEN" \
  --header "Accept: application/json"
```

The response lists every space you own or were invited to:

```json theme={null}
{
  "data": [
    {
      "id": "6f1c2a9e-1d7b-4c55-9a3e-2b8f0c4d5e61",
      "name": "Pessoal",
      "type": "personal",
      "default": true,
      "role": "owner"
    }
  ]
}
```

Use a space `id` to scope later requests to that space.

**4. Find an account and a category**

Replace `SPACE_ID` with an `id` from the previous step:

```bash theme={null}
curl https://api.visorfinance.app/v1/spaces/SPACE_ID/accounts \
  --header "Authorization: Bearer $VISOR_TOKEN"

curl https://api.visorfinance.app/v1/spaces/SPACE_ID/categories \
  --header "Authorization: Bearer $VISOR_TOKEN"
```

Copy the `id` of the account that paid the expense, and the `id` of its category. A system category has a stable `key`, such as `category.food_and_drinks`, so a script can find it by key. See [Spaces and reference data](https://docs.visorfinance.app/reference-data.md).

**5. Record an expense**

```bash theme={null}
curl https://api.visorfinance.app/v1/spaces/SPACE_ID/transactions \
  --request POST \
  --header "Authorization: Bearer $VISOR_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 2026-10-01-padaria" \
  --data '{
    "account_id": "ACCOUNT_ID",
    "category_id": "CATEGORY_ID",
    "description": "Padaria",
    "amount": "42.90",
    "type": "debit",
    "transacted_at": "2026-10-01T08:30:00-03:00"
  }'
```

The response is `201 Created` with the new transaction. The amount is a decimal string, and the transaction takes the currency of its account:

```json theme={null}
{
  "data": {
    "id": "9c1e4b2a-7d3f-4e8a-b6c5-1a2b3c4d5e6f",
    "account_id": "ACCOUNT_ID",
    "category_id": "CATEGORY_ID",
    "tag_ids": [],
    "amount": "42.90",
    "type": "debit",
    "currency_code": "BRL",
    "source": "manual",
    "status": "posted",
    "ignored": false,
    "description": "Padaria",
    "merchant_name": null,
    "notes": null,
    "transacted_at": "2026-10-01T11:30:00Z",
    "created_at": "2026-10-01T11:31:02Z",
    "updated_at": "2026-10-01T11:31:02Z"
  }
}
```

**6. Retry safely**

Send the same request again with the same `Idempotency-Key`. Visor does not record a second expense: it returns the expense it already has, with the header `idempotent-replayed: true`. Your script can retry a timeout without creating duplicates. See [Idempotency](https://docs.visorfinance.app/idempotency.md).

**7. See it in Visor**

Open [Transactions](https://dashboard.visorfinance.app/transactions) in Visor. The expense is in the account and the space you chose.

## Next steps

* Export your history and edit transactions in [Transactions](https://docs.visorfinance.app/transactions.md).
* Find categories and tags in [Spaces and reference data](https://docs.visorfinance.app/reference-data.md).
* Read how [authentication and scopes](https://docs.visorfinance.app/authentication.md) work.
* Handle [errors](https://docs.visorfinance.app/errors.md) and [rate limits](https://docs.visorfinance.app/rate-limits.md) in your client.


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