How to connect a script or an AI agent through the API and MCP

What the API and MCP are and why you need an access key

The API and MCP are for cases when another program has to read or add data in Tetri: a script, a spreadsheet, an automation service or an AI agent. The program sends a token instead of a login and password. The token belongs to an access key: you can limit the key's permissions and lifetime, and revoke the key at any time.

REST (requests over HTTP to addresses like /api/v1/programmatic/…) fits scripts and spreadsheets. MCP (Model Context Protocol) fits AI agents and other MCP clients: they call Tetri's tools.

How to create an access key and get a token

1. In settings, open "API & MCP" and click "Create credential".
2. In the "Create credential" window, enter a name, pick a client and set the lifetime in days.
3. In the same window, confirm your identity with any of the listed methods: a password, an authenticator code, or Google or Apple, and turn on the capabilities you need.
4. Copy the token from the "Copy this token now" window and store it in a secrets manager.
5. Send the token in every request in the Authorization: Bearer header.

The token is shown once, and the "Credentials" list keeps only its beginning. You cannot view a lost token again, so create a new key.

How to choose the client, capabilities and lifetime of a key

Client

You choose the client when you create the key: a REST key works only with the REST API, and an MCP key works only with MCP, so a second client needs its own key. An MCP key cannot create imports and templates; those are available in REST only.

Capabilities

A capability gives a key access to one group of data: wallets, transactions, budgets, recurring transactions, goals, reports or imports. Pick at least one. You turn on creating transactions, templates and imports separately, and only if the user's role allows that action.

Lifetime

A key lasts from 1 to 90 days, 30 by default. When the lifetime ends, access closes automatically.

Number of keys

One user can have at most 5 active keys. To create a sixth, revoke one of the earlier keys.

How to get transactions into a script or spreadsheet

Exporting takes a GET /api/v1/programmatic/transactions request and a key with the capability to read transactions. The start and end parameters set the period in YYYY-MM-DD format. The type parameter filters by type, and the query parameter searches the description. A response holds 25 transactions by default and 100 at most. Request the next page with the page or the after parameter, but not both together.

GET /api/v1/programmatic/transactions?start=2026-10-01&end=2026-10-31&limit=100

How to create a transaction from a script without duplicates

Creating takes a POST /api/v1/programmatic/transactions request with the type withdrawal, deposit or transfer: an expense needs source_account_id, an income needs destination_account_id, and a transfer needs both. Write the amount as a string in quotes, such as "3.00". The API calls a wallet an account, so take the IDs of wallets, categories and currencies from GET /api/v1/programmatic/accounts, GET /api/v1/programmatic/categories and GET /api/v1/programmatic/currencies.

The Idempotency-Key header is required: 16 to 128 Latin letters, digits, hyphens and underscores. Your program makes up the value for each new transaction, and it does not depend on the access key.

After a dropped connection, send the request again with the same Idempotency-Key value, and only one transaction is created. A request with the same value and a different body gets a 409 response.

POST /api/v1/programmatic/transactions
Idempotency-Key: coffee_20261012_0001

How to send a phrase and get a draft

A phrase like "taxi 4.50 euros today" goes in the text field of POST /api/v1/programmatic/transactions/parse, and the capability to read transactions is enough for it. The optional locale, timezone and reference_date set the language, the time zone and the reference date for the words "today" and "yesterday". The response is a draft with the amount, currency, date, wallet and category, plus a list of the missing fields. No transaction is saved: send a checked draft with the normal create request.

POST /api/v1/programmatic/transactions/parse
{ "text": "taxi 4.50 euros today", "locale": "en" }

How to connect an MCP client or an AI agent

An MCP client or an AI agent needs the /mcp address and the token of an MCP key in the Authorization: Bearer header. Any MCP client that calls a remote MCP server over HTTP and can send this header works: there is no other way to sign in to MCP. There are no sessions: each request stands alone, and GET and DELETE on this address get a 405 response.

The agent sees only the tools the key has capabilities for: without budget read there is no get_budget_status, and without creating transactions there is no create_transaction. So that a repeated call does not create a duplicate, create_transaction takes an idempotency_key argument.

How to check the request log and revoke a key

The summary for 7, 30 or 90 days on the "API & MCP" page shows requests, the successful ones, the denied and failed ones, and the average latency.

Each request in the log has a time, key, action, transport, status (OK, Denied or Error) and duration, and request bodies are not stored. The log shows requests made with keys you created.

The "Revoke" button in the key list closes access at once, and the next request with that token is rejected. Changing the password or the email address revokes all tokens.

What to do when a request is rejected

Response 401: the token is wrong, expired or revoked. Create a new key.

Response 403: the key lacks the needed capability, belongs to another client, or the user's role does not allow the action.

Response 409: the Idempotency-Key value was already used with a different body.

Response 429 means you went over the per-minute request limit, which depends on the request type. Retry the request later. Denials based on key capabilities show in the log with the status "Denied".