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

Agent Skill (planned)

A separate Kakeibo Agent Skill is planned for using the product from an agent. It is not available to install yet. For current integrations, use the Public API directly or the read-only MCP server above. Do not give an agent an API key unless you trust its access to your account.

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: [email protected].