klanex API guide

Everything you need to run agent tool calls through klanex. Base URL: https://api.klanexai.com · auth header: X-API-Key · machine-readable spec: openapi.yaml

Sandbox: https://api.sandbox.klanexai.com runs the same code with Stripe in test mode — sign up there with a test card and integrate without touching production. Accounts, API keys, and data are separate per environment, and sandbox data carries no durability promise. Create a sandbox account →

Quickstart

1. Sign up — verify your email, put a card on file, and save the api_key and webhook_secret shown once.
2. Submit your first execution:

curl -s https://api.klanexai.com/v1/executions \
  -H "X-API-Key: klx_…" -H "Content-Type: application/json" \
  -d '{
    "target":  { "url": "https://httpbingo.org/post", "method": "POST" },
    "payload": { "amount": 42 },
    "payload_schema": { "type": "object",
                        "properties": { "amount": { "type": "number" } },
                        "required": ["amount"] },
    "idempotency_key": "demo-1"
  }'
# → 202 {"execution_id": "exe_…", "status": "QUEUED"}

3. Poll GET /v1/executions/{id} (or receive a signed webhook) and watch it in the dashboard.

Execution lifecycle

klanex answers in milliseconds and executes asynchronously. Statuses:

PENDING_APPROVAL → QUEUED → RUNNING → RETRYING (loops) → SUCCEEDED | FAILED

Retryable target failures (429, 5xx, timeouts) are absorbed with exponential backoff and per-host circuit breakers. Permanent rejections (4xx) fail fast with a correction hint for your agent.

Submit an execution

POST /v1/executions

Read & list

GET /v1/executions/{id} — full state; credentials always redacted.

GET /v1/executions?status=&since=&until=&limit=&cursor= — newest first, cursor-paginated.

Human-in-the-loop approvals

POST /v1/executions/{id}/approve · POST /v1/executions/{id}/reject (optional {"reason": "…"})

Executions submitted with requires_approval wait in PENDING_APPROVAL. Rejection is terminal (APPROVAL_REJECTED). Replays of gated executions pause again — approvals never carry over. With Slack connected, approvals are one button click.

Replay

POST /v1/executions/{id}/replay — re-run a terminal execution with its byte-exact original payload and sealed credentials; the clone records replay_of for audit.

POST /v1/replays {"since": "…", "until": "…"} — bulk-replay failures after an outage; permanently rejected payloads are skipped.

Webhooks

On terminal state klanex POSTs to your callback_url:

{
  "event": "execution.completed",   // or "execution.failed"
  "execution_id": "exe_…",
  "status": "SUCCEEDED",
  "attempts": 2,
  "result": { "status_code": 200, "body": "{…}" },
  "error": null
}

Respond 2xx; 5xx responses are retried 3 times with backoff. Both SDKs ship a verifyWebhook / verify_webhook helper.

Error codes

Codes are part of the contract — feed llm_hint back to your agent so it can self-correct.

Token vault (connections)

Store credentials once, reference them by ID — agents never see raw secrets, and OAuth tokens refresh automatically.

POST   /v1/connections                    create
GET    /v1/connections                    list (never returns secrets)
DELETE /v1/connections/{id}               remove
GET    /v1/connections/{id}/authorize     begin OAuth consent (browser)

• static_bearer — bring your own long-lived token.
• oauth2_client_credentials — machine-to-machine; klanex fetches and refreshes.
• oauth2_authorization_code — browser consent; presets for GitHub, Google, Slack, HubSpot, Salesforce, Stripe.

Then submit with "target": {"url": "…", "connection_id": "con_…"} — the worker injects a fresh token at execution time.

Slack & Jira integrations

Slack — approval buttons + failure alerts

1. Create a Slack app (api.slack.com/apps → From scratch).
2. Incoming Webhooks → activate → add to a channel → copy the hooks.slack.com URL.
3. Basic Information → copy the Signing Secret.
4. Interactivity & Shortcuts → ON → Request URL: https://api.klanexai.com/integrations/slack/actions

curl -X PUT https://api.klanexai.com/v1/integrations/slack \
  -H "X-API-Key: klx_…" -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://hooks.slack.com/services/…",
       "signing_secret":"…","notify_on_failure":true}'

Gated executions post Approve/Reject buttons; clicks are verified with Slack's request signature and recorded in the audit trail. Payload contents never appear in Slack.

Jira — auto-file issues on failures

curl -X PUT https://api.klanexai.com/v1/integrations/jira \
  -H "X-API-Key: klx_…" -H "Content-Type: application/json" \
  -d '{"base_url":"https://yourco.atlassian.net","email":"you@yourco.com",
       "api_token":"…","project_key":"OPS","issue_type":"Task"}'

Every terminally failed execution files an issue with the error and replay instructions — never the payload. Check state with GET /v1/integrations; remove with DELETE /v1/integrations/slack or …/jira.

Credential rotation

POST /v1/api-key/rotate — new key returned once; the old key stops working immediately.

POST /v1/webhook-secret/rotate — callbacks after rotation are signed with the new secret; update your verifier.

Both are also one click in the dashboard under Credentials.

MCP server

Agents can drive klanex over the Model Context Protocol instead of raw REST. The /mcp endpoint (Streamable HTTP) lives on the same hosts as the API:

Authenticate with the same API key, sent as either an X-API-Key header or Authorization: Bearer klx_… (for clients that can only set an Authorization header). Add it to Claude Code:

claude mcp add --transport http klanex https://api.klanexai.com/mcp \
  --header "X-API-Key: klx_live_…"

For stdio-only clients (e.g. Claude Desktop), use the npm shim — it proxies to the hosted endpoint and routes klx_test_… keys to the sandbox automatically:

{
  "mcpServers": {
    "klanex": {
      "command": "npx",
      "args": ["-y", "klanex-mcp"],
      "env": { "KLANEX_API_KEY": "klx_live_…" }
    }
  }
}

Six tools are exposed. They proxy to the REST endpoints above in-process, so validation, the schema gate, quota, rate limits, idempotency, and credential sealing behave identically — and errors surface as tool errors carrying the same llm_hint, so the agent self-corrects.

SDKs

• TypeScript / Node — github.com/chrassy/klanex-js: zero-dep client, webhook verification, key rotation.
• Python — github.com/chrassy/klanex-python: sync + async clients, webhook verification, plus klanex.adapters for LangChain, CrewAI, and Google ADK.

Or plain HTTP from anything else — the whole surface is in openapi.yaml.