Kakeibo Developer API

Overview

The Developer API is a self-contained, versioned surface (/api/public/v1) separate from the app’s internal API. It is contract-tested and stable: response shapes will not change underneath your integration without a new version.

Every endpoint operates on your own data only and enforces exactly the same business rules (quotas, validation, team permissions) as the Kakeibo apps — there is no separate, weaker code path.

Plan requirement

The Developer API is available on the Solo and Family plans. Requests authenticated by a Free-plan account receive a 402 Payment Required response with an upgrade hint. Upgrade from Settings → Billing in the dashboard.

Base URL

https://api.kakei.io/api/public/v1

All requests must be made over HTTPS. All paths below are relative to this base.

Authentication

The Developer API uses API keys sent as a bearer token. Cookie / session authentication is rejected on this surface.

Authorization: Bearer kak_xxxxxxxxxxxxxxxxxxxxxxxx

Creating a key

Create and revoke keys in the dashboard at Settings → Developer. A key’s secret is shown once at creation time — store it securely; it cannot be retrieved again.

• Each key carries full access to your account’s resources.
• Keys expire after a configurable number of days — default 30, maximum 365.
• Revoking a key takes effect immediately.
• Treat a key like a password. Never embed it in client-side code.

MCP setup

The Kakeibo MCP server lets MCP-compatible AI clients inspect your Kakeibo data through the same Public Developer API. It is read-only in the current release: it can answer questions about profile, usage, accounts, categories, tags, transactions and reports, but it cannot create, update, void, delete or upload anything.

Requirements

• Node.js 20 or newer.
• A Kakeibo Solo or Family account.
• A Public API key from Settings → Developer.
• An MCP-compatible client that can launch local stdio servers.

Client configuration

Add the server to your MCP client configuration. The API base value is the API origin only; the MCP server adds /api/public/v1 internally.

{
  "mcpServers": {
    "kakeibo": {
      "command": "npx",
      "args": ["-y", "kakeibo-mcp-server"],
      "env": {
        "KAKEIBO_API_BASE_URL": "https://api.kakei.io",
        "KAKEIBO_API_KEY": "kak_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart your MCP client after changing its configuration.

Available tools

Example prompts

• Show my spending by category this month.
• Find my largest expenses this year.
• List my recent transactions for the default account.
• How close am I to my plan limits?

Troubleshooting

Personal & team scope

Every resource is reachable under two mirrored hierarchies:

• /me/... — your personal data
• /teams/{team}/... — data for a team you belong to (team permissions still apply; non-members get 403)

GET https://api.kakei.io/api/public/v1/me/transactions
GET https://api.kakei.io/api/public/v1/teams/01J.../transactions

Rate limits

Limits are applied per API key, with separate buckets for reads and writes — writes are intentionally stricter.

Exceeding a limit returns 429 Too Many Requests. Use the standard Retry-After response header to back off.

Resources

Billing, team management, invitations and authentication are intentionally not part of the Developer API.

Quick start

List your most recent transactions:

curl https://api.kakei.io/api/public/v1/me/transactions \
  -H "Authorization: Bearer $KAKEIBO_API_KEY" \
  -H "Accept: application/json"

Create a transaction:

curl -X POST https://api.kakei.io/api/public/v1/me/transactions \
  -H "Authorization: Bearer $KAKEIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "account_id": "01J...",
    "category_id": "01J...",
    "flow_type": "expense",
    "amount": 12.50,
    "currency_code": "USD",
    "description": "Coffee",
    "transaction_at": "2026-05-19T09:00:00Z"
  }'

Response format

Every response is wrapped in a consistent envelope:

{
  "meta": { "code": 200, "message": "Success" },
  "data": { ... }
}

The payload you care about is always under data. List endpoints return a paginated collection; pass ?page= to page through results.

Errors

Errors use standard HTTP status codes; meta.message describes the problem.

Full reference

The complete, always-current endpoint reference — every path, parameter and response schema — is generated from the API’s OpenAPI specification and rendered with an interactive explorer:

Open the API reference →

Questions or integration support: support@kakei.io.