Command+K / docs

AI Runtime API — prepaid inference for your own features

The AI Runtime is an OpenAI-compatible endpoint your backend calls to power your product's own AI features — no provider account needed. CMD+K runs inference on managed keys, attributes every call to the end user you name, meters cost, and feeds the same dashboards and billing destinations as your assistant. You prepay credits; your end users keep paying you on your own gateway.

Quickstart

  1. Enable the Monetize add-on and buy credits (Billing → Monetize).
  2. Create an access token with the ai:invoke scope.
  3. Call the endpoint from your backend:
bash
curl -N https://commandplusk.com/api/public/v1/chat/completions \
  -H "Authorization: Bearer ck_pat_..." \
  -H "X-CmdK-End-User: user_42" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4-5",
    "stream": true,
    "messages": [{ "role": "user", "content": "Summarize this ticket…" }]
  }'

Any OpenAI SDK works — set base_url to https://commandplusk.com/api/public/v1 and add the end-user header per request.

Request headers

  • Authorization — Bearer ck_pat_… — a Command+K access token with the ai:invoke scope. Server-side only; never ship it to a browser.
  • X-CmdK-End-User — required — the stable id of YOUR end user (the same sub you use in widget JWTs). Drives attribution, limits and rebilling.
  • X-CmdK-End-User-Tier — optional — matches a plan's tier key so per-plan monthly limits and rate limits apply to this call.
  • X-CmdK-Request-Id — optional — your idempotency id; retries with the same id never double-debit credits.

Error codes

  • 401 invalid_api_key — missing/invalid token.
  • 403 insufficient_scope / monetize_required — token lacks ai:invoke, or the add-on is off.
  • 400 end_user_required — the end-user header is missing.
  • 402 insufficient_credits — prepaid balance is empty; top up to resume.
  • 404 model_not_found — not in GET /v1/models.
  • 429 end_user_rate_limited / quota_exceeded / cost_cap_exceeded — this end user hit their plan's per-minute rate, monthly allowance, or cost cap.
  • 502 provider_unavailable — upstream model provider error; retry with backoff.

How billing works

  • Each call's token usage is priced from the model catalog and debited from your prepaid balance (your configured AI markup included) — the same cost engine as your assistant.
  • Usage appears per end user on the Audience and Revenue dashboards alongside widget chat.
  • With a billing destination connected, the same meter events forward to your Stripe/Paddle so you can rebill your users. CMD+K never holds your end-users' money.

Next steps

Enable the Monetize module
Connect your billing destination
Per-user spending caps

FAQ

Why is the end-user header required?
Attribution is the product: it drives per-user usage/cost dashboards, plan limits, cost caps, and rebilling to your billing destination. Calls without an end user are rejected (400).
Which models are available?
GET /v1/models lists the live catalog (Anthropic, OpenAI, Google chat models). Pricing follows the catalog; your configured AI markup is applied to the cost we debit.
What happens at zero balance?
The next call returns 402 insufficient_credits. One in-flight call can dip the balance slightly negative; top-ups clear it. We nudge you when the balance drops under $5.
Do you execute tools?
No. tools / tool_choice are passed to the model and tool_calls come back in the response — execution stays in your backend.
Does this bill my end users automatically?
If you have a billing destination connected, every AI Runtime call forwards the same meter events as widget chat — Stripe in near-real-time, Paddle via monthly accrual. You stay the merchant of record.
← Previous
Per-user spending caps
Next →
Logs, retries & DLQ