canonical: https://jentic.com/apis/ezbookkeeping.mayswind.net/ezbookkeeping

# Ezbookkeeping Mayswind ezBookkeeping API

Jentic publishes the only available OpenAPI specification for ezBookkeeping API, keeping it validated and agent-ready. ezBookkeeping is a self-hosted, open-source personal-finance and bookkeeping app, and the API exposes the full set of operations needed to manage transactions, accounts, categories, tags, and authorisation tokens against a user's deployment. Because it is self-hosted, the host portion of the base URL is supplied per-deployment and bearer tokens are issued by the local /api/authorize.json endpoint.

## For AI agents

Manage personal-finance transactions, accounts, categories, tags and tokens on a self-hosted ezBookkeeping deployment via 39 JSON endpoints with bearer-token auth.

## Scope

Does not handle bank-feed aggregation, tax filing, or multi-tenant SaaS billing - use for self-hosted personal-finance ledger management only.

## Capabilities

- Authorise a user and obtain a bearer token via /api/authorize.json with optional 2FA
- List, add, modify and inspect financial accounts through /api/accounts/list.json and /api/accounts/add.json
- Manage personal profile and registration via /api/users/profile/get.json and /api/users/register.json
- Revoke individual or all active tokens through /api/tokens/revoke.json and /api/tokens/revoke_all.json
- Handle two-factor recovery codes through /api/2fa/recovery.json
- Sign in via OAuth2 callback at /api/oauth2/callback.json

## Use cases

### Self-Hosted Personal Finance Automation

Drive a self-hosted ezBookkeeping deployment from scripts and agents, including login, account management, and token lifecycle. Authorise via /api/authorize.json, optionally exchange a 2FA code through /api/2fa/authorize.json, and use the resulting bearer token to call account, profile and token endpoints. Because hosting is per-user, the {host} placeholder in the base URL must be filled with the deployment's hostname.

Example prompt: POST credentials to https://my-ezbk.example.com/api/authorize.json, then call GET /api/accounts/list.json with the returned bearer token to enumerate accounts.

### Account Onboarding Flow

Programmatically register a new ezBookkeeping user, retrieve their profile, and seed the deployment with initial accounts. Use /api/users/register.json to create the user, /api/authorize.json to obtain a token, and /api/accounts/add.json for each starting account. Suitable for households or small teams setting up a shared ezBookkeeping instance from a configuration file.

Example prompt: Call /api/users/register.json with the new user payload, /api/authorize.json to obtain a token, then loop /api/accounts/add.json for each account in the configuration.

### Token Hygiene and 2FA Recovery

Maintain account security by listing active tokens, revoking individual stale ones, or rotating all tokens at once with /api/tokens/revoke_all.json. The /api/2fa/recovery.json endpoint supports recovery-code submission when the second factor is unavailable. Useful for households operating shared deployments who need to expire access for departed users.

Example prompt: Call GET /api/tokens/list.json, identify stale tokens, then call /api/tokens/revoke.json for each to revoke them in turn.

### Agent-Driven Bookkeeping via Jentic

An AI agent configured for a household's self-hosted ezBookkeeping deployment can use Jentic to discover and call the right endpoints rather than embedding the full client. Bearer tokens issued by /api/authorize.json live in your Jentic One instance, so the agent can list and modify accounts without ever holding the user's password.

Example prompt: Through Jentic, search 'list ezBookkeeping accounts', load /api/accounts/list.json, and execute it against the household deployment's host.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /api/authorize.json | Authorise a user and return a bearer token |
| POST | /api/2fa/authorize.json | Submit a 2FA code to complete login |
| GET | /api/tokens/list.json | List the active tokens for the current user |
| POST | /api/tokens/revoke_all.json | Revoke all tokens for the current user |
| GET | /api/accounts/list.json | List financial accounts |
| POST | /api/accounts/add.json | Add a new financial account |
| POST | /api/accounts/modify.json | Modify an existing financial account |
| POST | /api/users/register.json | Register a new ezBookkeeping user |

## Key resources

- **Authorisation** — Login, 2FA, OAuth2 callback and recovery flows
- **Tokens** — List, revoke individual and revoke-all bearer tokens
- **Users** — Profile read, profile update, and registration
- **Accounts** — List, get, add and modify financial accounts

## Why Jentic

- **Setup:** Wiring the ezBookkeeping API by hand means authorizing through /api/authorize.json, handling its optional 2FA step, pointing at your self-hosted host, and following its .json URL conventions yourself. Through Jentic you install once, import the ezBookkeeping API from the API Directory, store the bearer token once, and your agent calls it.
- **Permission scoping:** ezBookkeeping carries its targets in the request body rather than resource ids in the path, so you limit the agent to the operations it needs, such as listing or adding accounts. You choose those operations, so token-revocation or user-registration calls are not included unless you add them.
- **Credential handling:** Your ezBookkeeping bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. The user's password and 2FA secret never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list ezBookkeeping accounts' or 'add a ledger account', and Jentic returns the corresponding /api/accounts operation with its input schema so the agent calls the right endpoint without memorising the .json URL conventions.

## Related APIs

- **Ezus API** — Travel-agency project, client and invoice management - useful when bookkeeping needs to mirror invoices issued from a separate operations system.
- **Exude API Service** — Light text preprocessing - useful when bookkeeping descriptions need cleanup before search indexing.

## FAQ

### Why is there no official OpenAPI spec for ezBookkeeping API?

ezBookkeeping does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ezBookkeeping API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ezBookkeeping API use?

The spec declares an HTTP bearer token scheme. Obtain the token by POSTing credentials to /api/authorize.json (and following up with /api/2fa/authorize.json when 2FA is enabled) and supply it as the Authorization header on subsequent calls; through Jentic the token is held in the vault.

### Can I add a new account through the ezBookkeeping API?

Yes. POST the account payload to /api/accounts/add.json with a valid bearer token; you can later modify the same account via /api/accounts/modify.json or list everything with /api/accounts/list.json.

### How do I revoke an old token?

Call GET /api/tokens/list.json to find the token id, then POST to /api/tokens/revoke.json with that id; use /api/tokens/revoke_all.json to wipe every active token at once.

### How do I list my accounts through Jentic?

Run pip install jentic, search 'list ezBookkeeping accounts', load /api/accounts/list.json, and execute it against your self-hosted host; the bearer token from /api/authorize.json is injected from the vault automatically.

### Is the ezBookkeeping API free?

ezBookkeeping is a free, open-source self-hosted project, so the API itself has no licence fee; running costs are limited to whatever infrastructure you choose to host it on.

### Can I limit what my agent is allowed to do with the ezBookkeeping API?

Yes. Because you run Jentic One yourself, your own rules decide which ezBookkeeping operations and credentials the agent can use. You can allow just the calls the task needs, such as listing accounts with /api/accounts/list.json or adding one with /api/accounts/add.json, while withholding sensitive operations like token revocation via /api/tokens/revoke_all.json or user registration via /api/users/register.json. Since ezBookkeeping carries its targets in the request body rather than as path resource ids, scoping at the operation level is enough to keep the agent inside those boundaries.