# Taka Public API

Taka (https://taka.ai) is an AI marketing system for small businesses. This
API lets a Taka user drive their own account programmatically: read and
create posts, generate and revise content with AI, schedule, approve,
publish, and read performance.

## Base URL

https://api.taka.ai/v1/public

## Auth

Business API keys, created by a business Owner/Admin (POST /v1/api-keys
with an app session; an in-app settings page is on the way). Send as:

    Authorization: Bearer taka_live_...

Keys are scoped (account:read, content:read, content:write, generate,
publish, brand:read, brand:write, analytics:read). A key acts as the member
who created it, inside one business.

## MCP

An MCP server (Streamable HTTP, stateless, no SSE) lives at:

    https://api.taka.ai/mcp

Point any MCP client at that URL with the same Bearer key. Discovery
(initialize, tools/list, prompts/list, resources/list) is keyless;
tools/call and resources/read require the key. ~36 tools mirror the REST
surface 1:1 (same scopes, same rate buckets), 4 prompts package common
workflows (plan_my_week, review_and_approve, ship_this_post,
fix_my_brand_voice), and resources carry ambient context; read
taka://service-contract first. Media uploads are REST-only (multipart);
MCP cannot carry binaries.

Example client config:

    {
      "mcpServers": {
        "taka": {
          "type": "http",
          "url": "https://api.taka.ai/mcp",
          "headers": { "Authorization": "Bearer taka_live_..." }
        }
      }
    }

## Spec and docs

- Developer guide: https://taka.ai/developers
- OpenAPI: https://api.taka.ai/openapi.json
- Interactive docs: https://api.taka.ai/docs

## Contract notes

- Errors: {"error": {"code", "message", "requestId"}} with stable machine
  codes (APPROVAL_REQUIRED, CHANNEL_NOT_CONNECTED, INSUFFICIENT_CREDITS,
  RATE_LIMITED, SCOPE_MISSING, ...).
- Long-running verbs return 202 {jobId}; poll GET /v1/public/jobs/{id}.
  Stranded jobs are failed automatically (code 'timeout').
- Media URLs are signed and expire after ~6 hours. Never cache them.
- Rate limits per key: 600 requests/hour general, 60/hour for AI
  generation, 20/hour for outward writes to connected accounts (publish,
  approve, schedule). Headers: x-ratelimit-limit / -remaining / -reset.
- Scheduling requires the publish scope: for a business not in review
  mode, a schedule ships the post at its slot with no further gate.
- AI generation draws from the business's credit balance; charges happen
  on success only.
- Two flows need a browser and cannot be done over the API: connecting a
  social channel (OAuth) and billing/checkout. Endpoints return app links
  for both.
- Live metrics exist for Instagram only today, for roughly the account's
  25 most recent posts. Unavailability is stated with a machine reason,
  never fabricated.