generated: '2026-07-19'
method: derived
source: openapi/kernel-openapi-original.yml + https://kernel.sh/docs/
summary: >-
  Cross-cutting request/response semantics for the Kernel API, derived from the
  OpenAPI and the developer docs. Kernel is browser infrastructure for AI agents;
  resources are addressable by id or by name.
authentication:
  style: bearer
  header: Authorization
  scheme: Bearer
  credential: Kernel API key (org- or project-scoped)
  see: authentication/kernel-authentication.yml
  docs: https://kernel.sh/docs/info/api-keys.md
resource_addressing:
  pattern: id-or-name
  note: >-
    Most resources (browsers, profiles, credentials, extensions, browser pools)
    accept either their opaque id or a human-assigned name in the path
    ({id_or_name}).
project_scoping:
  header_or_flag: KERNEL_PROJECT
  query: project_id / --project
  note: API keys and requests can be scoped to a project or left org-wide.
idempotency:
  supported: false
  note: >-
    No Idempotency-Key header or idempotent-retry contract is documented in the
    OpenAPI or docs as of this capture. Creates are not idempotent by key.
pagination:
  style: limit-offset
  params: [limit, offset]
  note: List endpoints (audit logs, browsers, etc.) page with limit + offset.
streaming:
  style: server-sent-events
  note: >-
    Live event surfaces (invocation events, deployment events, browser logs,
    telemetry, process stdout, auth-connection events, filesystem watch events)
    stream via SSE endpoints (text/event-stream), not webhooks.
  endpoints:
    - GET /invocations/{id}/events
    - GET /deployments/{id}/events
    - GET /browsers/{id}/logs/stream
    - GET /browsers/{id}/telemetry/stream
    - GET /auth/connections/{id}/events
    - GET /browsers/{id}/process/{process_id}/stdout/stream
error_envelope:
  shape: custom-json
  content_type: application/json
  fields: [code, message, "details[]", inner_error]
  format: not-rfc9457
  see: errors/kernel-problem-types.yml
rate_limiting:
  signal: 429
  headers: [Retry-After]
  note: Rate-limited responses return HTTP 429 with a Retry-After header (RFC 6585 / 7231).
versioning:
  scheme: continuous
  api_version: "0.1.0"
  sdk_version: "0.80.0"
  cadence: weekly changelog
  see: [lifecycle/kernel-lifecycle.yml, changelog/kernel-changelog.yml]