API Overview

Base URLs

The kurnl API has two separate surfaces:

Surface	Base URL	Purpose
Partner API	`https://middleware.bso-projects.com/partner`	Subscriber provisioning, plan discovery, checkout, reports. Authenticated with `X-API-Key`.
Internal API	`https://middleware.bso-projects.com/api/v1`	Dashboard endpoints authenticated with a dashboard JWT. A few provider-facing operations pages (user management, port devices, wholesale reconciliation, audit logs) live here — see the “Provider Operations (Internal API)” section.

All partner integration work uses the /partner base. Examples in this reference use that base unless the page is explicitly marked as internal (/api/v1). (The split is organisational rather than physical: the partner routers are also mounted under /api/v1, so /api/v1/external-checkout/* etc. are live duplicates with identical auth — prefer /partner anyway.) All endpoints are HTTPS only. The partner API operates on your live account; there is no separate sandbox API key. For safe exploration, use the in-dashboard sandbox.

Authentication

See Authentication for the full guide. Quick reference:

Header	Used for
`X-API-Key: krnl_...`	Plan queries, provider-initiated + bulk provisioning, reports. Keys carry scopes — a call outside the key’s scopes returns `403` naming the missing scope.
`X-Webhook-Secret: ...`	CKO-03 external checkout callbacks

Rate limits

Limits are fixed per endpoint:

Endpoint	Limit
`POST /provisioning/provider-initiated`	120 / minute
`POST /provisioning/bulk`	10 / minute
`GET /provisioning/bulk/{batch_id}`	300 / minute
`GET /reports/billing`	30 / minute
`POST /external-checkout/complete`	120 / minute
`POST /external-checkout/anonymous-complete`	120 / minute
`POST /external-checkout/subscription-status`	120 / minute
`POST /subscriptions/{id}/change-plan`	120 / minute
`POST` / `GET` / `PATCH /external-checkout/sessions…`	120 / minute
`GET /external-checkout/sessions/{id}/status` (public)	60 / minute
`POST /serviceability/check`	120 / minute
`GET /serviceability/autocomplete`	300 / minute
`GET /serviceability/units`	300 / minute
`GET /outages/buildings`	60 / minute

Requests are bucketed per API key (key prefix) when an X-API-Key header is present, otherwise per client IP — callers behind a shared NAT share one IP bucket. When the limit is exceeded, kurnl returns 429 Too Many Requests. No X-RateLimit-* headers are emitted — back off and retry with your own timer.

Response format

All responses are JSON. Successful responses vary by endpoint. Error responses always follow this structure:

{
  "detail": "Location not found for location_hash"
}

Validation errors return an array (Pydantic v2 shape):

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "subscriber", "email"],
      "msg": "value is not a valid email address: An email address must have an @-sign.",
      "input": "not-an-email"
    }
  ]
}

Exception: the 410 Gone responses for expired/cancelled checkout sessions nest an object inside detail:

{
  "detail": { "detail": "Session expired", "expired_at": "2026-07-01T12:30:00Z" }
}

The cancelled variant carries no expired_at: {"detail": {"detail": "Session cancelled"}}.

Common HTTP status codes

Status	Meaning
`200`	Success
`201`	Created
`202`	Accepted (async operation queued)
`204`	No content (e.g. successful delete)
`400`	Bad request — invalid input
`401`	Unauthorized — missing or invalid credentials
`403`	Forbidden — valid credentials but insufficient permissions
`404`	Not found
`409`	Conflict — e.g. `Unit already has a pending or active subscription`, or restoring a subscription that is not `SUSPENDED`
`422`	Unprocessable entity — validation failure
`429`	Rate limit exceeded
`500`	Server error — safe to retry

Idempotency

All provisioning endpoints are idempotent by design:

POST /external-checkout/complete — the same session_id returns the existing subscription
POST /external-checkout/anonymous-complete — the same external_subscription_id (or an already-completed session_id) returns the existing subscription, flagged idempotent_replay: true
POST /provisioning/provider-initiated, POST /provisioning/bulk, and the explicit-fields (no-session) POST /external-checkout/complete — idempotent per (subscriber email, plan version, location): a retry returns the existing subscription with the message "Subscription already exists (idempotent replay)" or "Provisioning already in progress" (job_id may be empty on replay)

Retrying after a 5xx is therefore safe on all of these paths — kurnl also rolls back partial state automatically on server failures.

Pagination

The partner API currently has no paginated list endpoints.

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Base URLs

Authentication

Rate limits

Response format

Common HTTP status codes

Idempotency

​Base URLs

​Authentication

​Rate limits

​Response format

​Common HTTP status codes

​Idempotency

​Pagination

Base URLs

Authentication

Rate limits

Response format

Common HTTP status codes

Idempotency

Pagination