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). 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
`X-Webhook-Secret: ...`	CKO-03 external checkout callbacks

Rate limits

Limit	Value
External checkout endpoints	120 requests / minute per IP
All other authenticated endpoints	300 requests / minute per API key

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714000060

When the limit is exceeded, kurnl returns 429 Too Many Requests. Retry after the X-RateLimit-Reset timestamp.

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:

{
  "detail": [
    {
      "loc": ["body", "subscriber", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

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. duplicate subscription for a unit
`422`	Unprocessable entity — validation failure
`429`	Rate limit exceeded
`500`	Server error — safe to retry

Idempotency

Several endpoints are idempotent by design:

POST /external-checkout/complete — the same session_id (or email + plan_version_id in the explicit-fields flow) returns the existing subscription
POST /external-checkout/anonymous-complete — the same external_subscription_id (or session_id) returns the existing subscription
POST /provisioning/bulk — resubmitting the same subscriber email returns the existing subscription
POST /provisioning/provider-initiated — same as above

On 5xx errors, retry the full request. kurnl rolls back partial state automatically on server failures.

Pagination

List endpoints support cursor-based pagination:

GET /provider/subscribers?page=2&page_size=50

Response includes total, page, page_size, and has_more fields alongside the results array.

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