Organizze API (CLI scripts)

Use the organizze-skill repository to read and write Organizze personal finance data through the official REST API. JSON is printed to stdout; errors go to stderr and the process exits non-zero on failure.

Before running anything

Check whether the required credentials are available:

[[ -n "${ORGANIZZE_TOKEN:-}" && -n "${ORGANIZZE_EMAIL:-}" && -n "${ORGANIZZE_USER_AGENT:-}" ]] && echo "READY" || echo "MISSING"

• If the output is MISSING: stop and guide the user through setup below. Do NOT proceed until all variables are set.
• If the output is READY: proceed.

Setup guidance (show this when MISSING)

Tell the user they have two options:

Option 1 (recommended) — OpenClaw UI: Open the OpenClaw UI, go to Skills → organizze, enter the API token in the API key field, and click Save key. Then set ORGANIZZE_EMAIL and ORGANIZZE_USER_AGENT as environment variables in the skill's env section.

Option 2 — Edit ~/.openclaw/openclaw.json directly (for CLI users):

{
  "skills": {
    "entries": {
      "organizze": {
        "enabled": true,
        "apiKey": "<your-organizze-token>",
        "env": {
          "ORGANIZZE_EMAIL": "your@email.com",
          "ORGANIZZE_USER_AGENT": "my-organizze-skill"
        }
      }
    }
  }
}

The gateway picks up the change automatically — no restart needed.

The user can get their API token from the Organizze web app under Configurações → Integrações → Token de API.

Working directory

Before every node command, set the shell working directory to the repository root — the directory that contains package.json.

Prerequisites

• Node.js 18 or newer
• From the repository root: npm install
• A .env file (copy from .env.example) with:
  • ORGANIZZE_EMAIL
  • ORGANIZZE_TOKEN
  • ORGANIZZE_USER_AGENT (required by the API; any short string identifying your integration)

Do not print or log credential values. Mask PII when summarizing API output for the user.

How to run

node src/routes/<resource>.js <action> [args]

<resource> is one of: accounts, categories, transactions, credit-cards, transfers.

Run a script with no arguments to see its full usage on stderr.

Output: pretty-printed JSON on stdout. Errors: message on stderr, exit 1.

Conventions

• amount_cents: integer cents. R$ 50.00 = 5000. Expenses are negative.
• Dates: YYYY-MM-DD.
• JSON arguments: pass as a single quoted shell argument.
• transactions list --group-by-tag: local grouping after the API response (not a native API feature). Returns [{ tag, total_cents, transactions }]. Transactions with multiple tags appear in each group; untagged ones go into "untagged".
• transfers list: returns two entries per transfer (debit and credit sides), not one merged object.

For field names and payloads not listed here, see: https://github.com/organizze/api-doc

accounts

node src/routes/accounts.js list
node src/routes/accounts.js get 12345

categories

delete accepts optional JSON with replacement_id to migrate existing references before removal.

node src/routes/categories.js list
node src/routes/categories.js delete 42 '{"replacement_id":18}'

transactions

delete accepts optional JSON for recurring/installment behavior: '{"update_future":true}' or '{"update_all":true}'.

node src/routes/transactions.js list --start-date=2025-04-01 --end-date=2025-04-30
node src/routes/transactions.js list --account-id=1 --group-by-tag
node src/routes/transactions.js delete 888 '{"update_future":true}'

credit-cards

node src/routes/credit-cards.js list
node src/routes/credit-cards.js list-invoices 3 --start-date=2025-01-01 --end-date=2025-12-31
node src/routes/credit-cards.js get-payments 3 1001

transfers

Typical create fields: credit_account_id, debit_account_id, amount_cents, date, paid. Confirm exact shape via the API doc or by inspecting existing transfers.

node src/routes/transfers.js list --start-date=2025-04-01 --end-date=2025-04-30
node src/routes/transfers.js get 55

End-to-end workflows

Balances

node src/routes/accounts.js list

Transactions for a period, filtered by account

# 1. get account id
node src/routes/accounts.js list

# 2. list transactions
node src/routes/transactions.js list --start-date=2025-04-01 --end-date=2025-04-30 --account-id=1

Create an expense

node src/routes/transactions.js create \
  '{"description":"Coffee","amount_cents":-1500,"date":"2025-04-03","category_id":10,"account_id":1}'

Use negative amount_cents. Get category_id and account_id from prior list calls. Adjust fields to match the API.

Spending by tag

node src/routes/transactions.js list --start-date=2025-04-01 --end-date=2025-04-30 --group-by-tag

Each group in the result has tag and total_cents.