Developer Platform

Developer API

The same Multi-Agent Orchestration Pipeline that runs in the interface runs in your code. Send a prompt. Get back a specification built to hold up across models, runs, and contexts.

Get an API Key →

Why the API?

Base URL

https://promptkaizen.com/api/v1

Authentication

Every request carries your key as a Bearer token. Generate keys from your account — the raw key is shown once at creation, so store it somewhere safe.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Quickstart

One authenticated POST turns a rough prompt into a contract-grade one.

POST https://promptkaizen.com/api/v1/optimize
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "prompt": "write a function to parse user CSVs",
  "mode": "coding",
  "integrity": false
}

Response:

{
  "optimizationId": 42,
  "optimizedPrompt": "...",
  "promptStrength": {
    "overall": 96,
    "input_quality_score": 8,
    "output_improvement_score": 88,
    "clarity": 91,
    "structure": 94,
    "specificity": 89,
    "redundancy": 78
  }
}

Each optimize call costs 1 credit. The call is synchronous — finished specification arrives in the response.

Prism Modes

Supported values for the mode parameter: general, coding, creative, enterprise, educational.

POST /api/v1/optimize — Request Fields

• prompt (Required) — Any non-empty string
• mode (Required) — general · coding · creative · enterprise · educational
• integrity (Optional) — true / false — runs the verification circuit (5 credits vs 1)
• targetModel (Optional) — Hint for the model you'll run the result against (default: general)
• sandbox (Optional) — true returns a canned $0 response — no model call, no credit, no concurrency slot. Use it to wire up your integration.

POST /api/v1/optimize — Response Fields

• optimizationId — Unique ID for this optimization run.
• optimizedPrompt — The finished specification.
• promptStrength.overall — Output quality score (0–100).
• promptStrength.input_quality_score — Input quality score before optimization (0–100). Optional.
• promptStrength.output_improvement_score — Improvement magnitude score (0–100). Optional.
• promptStrength.clarity / .structure / .specificity / .redundancy — Per-dimension scores (0–100 each).
• pipelineFailure — Only on a soft failure (still HTTP 200): { reasons, details }. optimizedPrompt is empty, promptStrength is null, and no credit is charged.
• integrity — Only present when an integrity run executed. A versioned object — see the Integrity response table below.

Credit balances after the call are returned in the X-Api-* response headers — not in the response body. See the Response Headers section for the full list.

Integrity Engine

Set integrity: true and the engine inspects the finished output, flagging fabricated facts, figures, and citations before they reach you. Any API key can run integrity — costs 5 credits per call. Response includes a verdict (pass | findings_detected | review_recommended), findings, and fabricationAlerts.

GET /api/v1/ping

Check connectivity and your remaining balance without spending a credit.

GET https://promptkaizen.com/api/v1/ping
Authorization: Bearer YOUR_API_KEY

Error Codes

Every error response is JSON with an error field. Branch your error handling on that field, not on the HTTP status alone.

• 400 invalid_body — Request body failed schema validation. A details array lists each failing field.
• 401 missing_token — Authorization header is absent entirely. Authentication failures carry no balance headers.
• 401 invalid_key — Key prefix not found or HMAC mismatch.
• 401 revoked — Key exists but has been revoked. Generate a new key from your account settings.
• 402 insufficient_credits — Your free grant is used up and no paid credits remain. The body includes runType and your free/paid balances.
• 429 concurrency_exceeded — Too many simultaneous in-flight requests for this key. X-Concurrency-* headers show your position; the reserved run is refunded.
• 500 pipeline_error / internal_error — Server-side failure during optimization. The reserved run is refunded so you are not charged.
• 503 free_tier_paused — The global daily free-tier limit was reached. Paid credits still work immediately; free runs resume after the UTC daily reset (see the Retry-After header).

Response Headers

• X-Api-Free-Standard-Remaining — Free standard runs left in your one-time free grant.
• X-Api-Free-Integrity-Remaining — Free integrity runs left in your one-time free grant.
• X-Api-Paid-Credits — Purchased (card-on-file) credits remaining.
• X-Api-Balance — Which balance funded this response: free, paid, sandbox, or none (nothing charged).
• X-Concurrency-Limit — Max simultaneous in-flight requests allowed for your key.
• X-Concurrency-InFlight — Slots in use at the moment this response was sent.

Rate Limits

Usage is credit-based. Standard optimization runs cost 1 credit; integrity runs cost 5 credits. The API credit balance is separate from the web app’s monthly allowance — runs draw from your one-time free grant first, then from purchased credits. Credits are deducted atomically — two concurrent requests racing the last credit can’t both win. Track your balance via the X-Api-* response headers without a separate API call.

Command-Line Tool (pk-kaizen)

The same API, from your terminal. pk-kaizen is a zero-dependency client — Node 18+, nothing else to install.

npm install -g pk-kaizen

Authenticate:

export PK_API_KEY=your_api_key

pk optimize flags

• -p, --prompt <text> — Inline prompt text.
• --file <path> — Read the prompt from a file.
• --mode <mode> — general · coding · creative · enterprise · educational (default: general)
• --json — Print the full JSON response to stdout instead of the prompt string. Useful for piping.
• --show-score — Print the before/after strength score to stderr.
• --integrity — Run the Integrity Engine on the output; report is printed to stderr. Costs 5 credits (vs 1 for a standard run).
• --base-url <url> — Override the API base URL (default: promptkaizen.com).
• --timeout <secs> — Request timeout in seconds (default: 60).
• -h, --help — Show command help.

pk ping flags

• --json — Print the raw JSON response to stdout.
• --base-url <url> — Override the API base URL.
• -h, --help — Show command help.

pk configure flags

• --key <value> — Save the key non-interactively (appears in shell history — prefer the interactive prompt for security).
• -h, --help — Show command help.

CLI Examples

# check balance before a run (costs nothing)
pk ping

# optimize a prompt, pipe result to a file
pk -p "draft an onboarding email" > spec.txt

# read from a file, use coding mode, show score
pk optimize --file ./myprompt.txt --mode coding --show-score

# run with the Integrity Engine; findings go to stderr
pk -p "summarise the Q3 earnings report" --integrity

# get the full JSON response (useful in scripts)
pk -p "your prompt" --json | jq '.promptStrength.overall'

Ready to build?

Not a better sentence — a proven specification.

Get an API Key →