# kakak.ai Platform

Programmatic document evaluation API. Upload rubrics, build evaluation workflows, run
at scale — billed in pro credits from your existing kakak.ai account.

## Getting Started
1. Sign in to the developer portal at https://platform.kakak.ai/portal with your kakak.ai account
2. Create an API key at POST /v1/keys (authenticate with your Supabase session)
3. Upload reference documents: POST /v1/reference-documents for an upload_url, PUT your file bytes to it, then POST /v1/reference-documents/{id}/complete
4. Build a workflow at POST /v1/workflows
5. Run evaluations at POST /v1/workflows/{id}/runs

## API Reference
- OpenAPI 3.1: https://api.kakak.dev/v1/openapi.yaml
- Base URL: https://api.kakak.dev/v1
- Previous host https://api.platform.kakak.ai/v1 is still served (same deployment, no redirect) — existing integrations need no change
- Auth: Bearer kk_live_<token> (production) or kk_test_<token> (test/sandbox)

## Key Concepts
- **Workflow** (wf_*): A saved evaluation configuration (prompt + reference docs + output format)
- **Run** (run_*): A single execution of a workflow over input documents
- **Reference Document** (ref_*): Reusable evaluation criteria uploaded once
- **Document** (doc_*): Ephemeral per-run input upload (30-day retention)
- **API Key** (kk_live_*, kk_test_*): Authentication token with scoped permissions

## Pricing
- Test mode: Free (stubbed output, no real LLM call)
- Live mode: 2 pro credits / 1K input tokens + 8 pro credits / 1K output tokens
- No separate billing — same pro credit pool as kakak.ai chat and studio

## Rate Limits
- 60 requests/minute per API key
- 300 requests/minute per user (across all keys)
- Max 10 in-flight async runs per user

## Resources

### Workflows
- GET /v1/workflows — List workflows
- POST /v1/workflows — Create workflow
- GET /v1/workflows/{id} — Get workflow
- PATCH /v1/workflows/{id} — Update workflow
- DELETE /v1/workflows/{id} — Delete workflow

### Runs
- POST /v1/workflows/{id}/runs — Create run (multipart, async)
- GET /v1/runs — List runs (paginated, filterable)
- GET /v1/runs/{id} — Get run detail
- POST /v1/runs/{id}/cancel — Cancel queued run (full refund)
- GET /v1/runs/{id}/output — Get signed download URL (docx/xlsx/csv)

### Reference Documents
- GET /v1/reference-documents — List reference documents
- POST /v1/reference-documents — Request presigned upload URL (JSON: name, filename, mime_type, size_bytes)
- POST /v1/reference-documents/{id}/complete — Confirm upload finished, trigger indexing
- GET /v1/reference-documents/{id} — Get
- DELETE /v1/reference-documents/{id} — Delete pointer

### Documents
- POST /v1/documents — Request presigned upload URL
- POST /v1/documents/{id}/complete — Complete upload + extract text

### Prompt Templates
- GET /v1/prompt-templates — List curated templates
- POST /v1/prompt-templates/generate — AI-generate evaluation prompt

### Products
- GET /v1/products — List available products
- GET /v1/products/{code} — Get product detail

### Usage
- GET /v1/usage — Query API usage (date range, group by workflow)
- GET /v1/usage/balance — Get pro-credit balance

### Webhooks
- GET /v1/webhook-endpoints — List
- POST /v1/webhook-endpoints — Create (secret shown once)
- GET /v1/webhook-endpoints/{id} — Get
- DELETE /v1/webhook-endpoints/{id} — Delete

### API Keys
- GET /v1/keys — List keys
- POST /v1/keys — Create key (token shown once)
- DELETE /v1/keys/{id} — Revoke key

## Idempotency
All unsafe POST requests support Idempotency-Key header (client-generated UUID).
Same key + same body → replayed response. Same key + different body → 409 conflict.
Keys retained 24h.

## Webhooks
Configure endpoints to receive run.succeeded, run.failed, run.canceled, or
reference_document.ready events. Payloads are HMAC-SHA256 signed (Stripe-style).
Retries with exponential backoff up to ~24h.

## Billing
- Credits reserved atomically before work (FOR UPDATE on usercredits)
- Two-phase: quote up front, true-up after completion
- Over-charge refunded, under-charge deducted (may push balance negative)
- Hard suspend at −1000 pro credits
- All charges tracked in CDR with channel='api'
- Failed runs fully refunded
- Canceled queued runs fully refunded

## Errors
Standard error envelope: {"error": {"code": "...", "message": "..."}}
Codes: unauthorized, forbidden, not_found, validation_error, rate_limited,
       insufficient_pro_credits, negative_balance_locked, idempotency_conflict,
       use_async, unprocessable_document, quota_exceeded, payload_too_large,
       output_not_ready, internal_error

## Support
- Email: halo@kakak.ai
- Portal (sign-in, API keys, usage): https://platform.kakak.ai/portal
- Docs: https://kakak.dev/docs
- OpenAPI: https://api.kakak.dev/v1/openapi.yaml
- MCP Server: `https://api.kakak.dev/mcp` (Model Context Protocol)

## MCP (Claude Desktop / Claude Code)
Connect directly from Claude:
```json
{
  "mcpServers": {
    "kakak-platform": {
      "type": "http",
      "url": "https://api.kakak.dev/mcp",
      "headers": { "Authorization": "Bearer kk_live_YOUR_KEY" }
    }
  }
}
```
Tools: evaluate_document, get_run, list_workflows, get_workflow, list_runs,
list_reference_documents, get_balance.

## SDKs (coming soon)
Node.js (`@kakakai/platform`) and Python (`kakakai-platform`) SDKs are planned
for Phase 4. In the meantime, use the OpenAPI spec with your preferred codegen
tool, or call the REST endpoints directly with curl / fetch / requests.