Endpoint reference
All under https://api.kotoba.cloud. auth: pat = the connection-token bearer; cookie = the browser session (same-origin POST); public = none. Wires that are not served (/v1/messages, /v1/responses, Gemini) answer 405.
| method | path | auth | Body and answer |
|---|---|---|---|
| GET |
/v1/models
|
public | The model catalog (team, route, availability). |
| POST |
/v1/chat/completions
|
pat / cookie | OpenAI-compatible completion. tools, stream (emulated), max_tokens ≤ 32768. Answer carries billing / receiptId (+ usage, chargedMicroUSD). |
| GET |
/v1/research/status
|
pat / cookie | {status: eligible|pending, reason, freeTier, trust, scopes}. |
| POST |
/v1/research/jobs
|
pat / cookie | Create a job. Header idempotency-key (uuid v4). Strict body {model, task, scopeId, max_tokens, messages}. 202 queued. |
| GET |
/v1/research/job?jobId=
|
pat / cookie | {jobId, status, billing, model, receiptId, pollAfterMs, content?, toolCalls?, finishReason?}. 202 while queued/running. |
| POST |
/v1/research/applications
|
pat / cookie | Researcher application {verificationMode, policyVersion, consent, authorizedResearch, purpose, scope}. 202. |
| POST |
/v1/research/ekyc/start
|
pat / cookie | Start verification {scopeId, tasks} → a Stripe URL. |
| GET |
/v1/research/ekyc/status
|
pat / cookie | Verification state. |
| GET |
/v1/billing/catalog
|
public | Plans, rates, checkoutEnabled, purchasable. |
| GET |
/v1/billing/status
|
pat / cookie | {status, plan, balances[{scope, grantedMicroUSD, spentMicroUSD, reservedMicroUSD, availableMicroUSD}]}. |
| POST |
/v1/billing/checkout
|
cookie | {sku, requestId} → a Stripe Checkout URL. 403 with a PAT. |
| POST |
/v1/billing/portal
|
cookie | The Customer Portal URL (invoices, cancellation). |
| GET |
/v1/secure
|
public | Guardrail / firewall / compliance versions and rules. |
| GET |
/v1/session
|
cookie | {valid, username, principalId}. |
| POST |
/v1/account/api-token
|
cookie | Issue a connection token (shown once). |
| GET |
/v1/account/api-tokens
|
cookie | Issued tokens (id, label). |
| POST |
/v1/account/api-token/revoke
|
cookie | Revoke one token. |
| GET |
/v1/security/services
|
public | The public security-services catalog. |
| GET |
/v1/control-plane
|
public | The service-discovery profile. |
Common to all: errors are {"error":{"code":…}} (see Errors). POST bodies are capped at 2 MiB and must be application/json.