openapi: 3.2.0
info:
  title: KnoxCall Client Management Wrap Credentials API
  version: '1.0'
  description: 'The KnoxCall Client Management API provides programmatic access to manage your API gateway

    resources including routes, secrets, clients, environments, webhooks, and API keys. ## Authentication


    All requests must include an OAuth 2.1 access token **or** a legacy API key. The

    recommended path for new integrations is the first-party SDKs, which mint, cache, and

    refresh OAuth tokens for you (start with `knoxcall login` on a developer machine, or

    `KNOXCALL_CLIENT_ID` / `KNOXCALL_CLIENT_SECRET` in CI). You can authenticate using any of:


    - **Authorization header (OAuth 2.1 bearer token — recommended)**: `Authorization: Bearer `

    - **Authorization header (legacy API key)**: `Authorization: Bearer tk_xxx_yyy`

    - **x-api-key header (legacy API key)**: `x-api-key: tk_xxx_yyy`


    OAuth 2.1 access tokens (`kc_` prefix) are minted at the root-host token endpoint

    `https://api.knoxcall.com/oauth/token` (not under `/v1`) using the `client_credentials`

    or `authorization_code` grant. See the `OAuth2` security scheme and the `/oauth/*`

    endpoints. Some resources that are managed exclusively through OAuth reject API-key auth

    with a `403 use_oauth` error. Long-lived API keys remain fully supported. They come in three types:

    - **Standard keys** (`tk_` prefix) are used on the production API (`api.knoxcall.com`). - **Test keys** (`tk_` prefix, type=test) are used on the sandbox API (`sandbox.knoxcall.com`). - **Enterprise Access Keys** (`AKE` prefix) follow the format `AKE[16chars]:[40chars]`. Using a test key on the production API (or vice versa) will return a `403 wrong_key_type` error. ## Request IDs


    Every response — success or error — includes an `X-Request-Id` response header (a UUID). Its value is identical to the `request_id` field in the response body (`meta.request_id`

    on success, `error.request_id` on error). Quote it when contacting support. ## API Versioning


    The API is versioned on two axes:


    - **Major version — the `/v1` path prefix.** Breaking changes ship under a new major

    (`/v2`). `/v1` never receives a breaking change. - **Minor version — the `KnoxCall-Version` header (dated, `YYYY-MM-DD`).** Send

    `KnoxCall-Version: 2026-08-05` to pin the behaviour of a specific dated release. Omit

    the header to get the newest minor version. Every response echoes the resolved version

    back in a `KnoxCall-Version` response header. Within a major version, **additive changes are not breaking** and may appear without a new

    dated version: new endpoints, new optional request fields, new response fields, new

    `error.type` values, and new enum members. Clients must tolerate unknown response fields

    and unknown `error.type` values (see the `ErrorResponse` schema). An **unknown or malformed** `KnoxCall-Version` value returns `400` with

    `error.type: invalid_api_version`. ## Rate Limiting


    API keys can have optional rate limits configured. When a limit is configured, the

    following headers are emitted on **every** response (not only `429`s):

    - `X-RateLimit-Limit` -- maximum requests allowed per window

    - `X-RateLimit-Remaining` -- remaining requests in the current window

    - `X-RateLimit-Reset` -- epoch seconds at which the window resets


    When the limit is exceeded the API returns `429` (`rate_limit_exceeded` / `rate_limited`)

    and additionally sets `Retry-After` (seconds until the window resets). ## DPoP sender-constrained tokens, and the server nonce


    A token minted with a `cnf.jkt` binding (DPoP, RFC 9449) requires a `DPoP` proof header

    on every request, signed over the request''s method and canonical public URL. **Every response to a request that carried a `DPoP` header also carries a

    `DPoP-Nonce` response header** -- mints, refusals and successful calls alike, on

    `POST /oauth/token`, `/v1`, the tenant data plane, the self-hosted proxy and the AI

    gateway. The value is stateless and changes every minute; the server accepts the current

    and the previous minute''s, so a nonce is good for 60-120 seconds.'
  contact:
    name: KnoxCall Support
    url: https://knoxcall.com
    email: support@knoxcall.com
  license:
    name: Proprietary
    url: https://knoxcall.com/terms
servers:
- url: https://api.knoxcall.com/v1
  description: Production
- url: https://sandbox.knoxcall.com/v1
  description: Sandbox (test keys only)
security:
- OAuth2: []
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Wrap Credentials
  description: Escrow a third-party provider key into KnoxCall custody so it leaves your codebase, host-pinned; the ephemeral proxy injects it under X-Knox-Upstream-Auth-Secret.
paths:
  /wrap/credentials:
    post:
      operationId: escrowWrapCredential
      summary: Escrow a provider credential
      tags:
      - Wrap Credentials
      description: 'Move a third-party provider key (e.g. a Stripe `sk_live_…`) into KnoxCall

        custody so it leaves your codebase. The key is stored envelope-encrypted

        (BYOK / rotation apply) and bound to `allowed_hosts`. Afterwards the

        wrapped SDK sends `X-Knox-Upstream-Auth-Secret: ` on `/proxy`

        instead of the key, and KnoxCall injects it as the upstream `Authorization`

        header **only** for a request whose host is in `allowed_hosts` — the

        anti-exfiltration pin.


        The value is accepted once and is never returned by any endpoint.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - provider
              - name
              - value
              - hosts
              properties:
                provider:
                  type: string
                  description: Free-form provider label ('stripe', 'openai', …). Not a security boundary.
                  example: stripe
                name:
                  type: string
                  description: Secret name the escrowed key is stored + referenced under.
                  example: wrap-stripe-live
                value:
                  type: string
                  description: The raw provider credential. Sent once; never returned.
                hosts:
                  type: array
                  minItems: 1
                  items:
                    type: string
                  description: The only upstream DNS hostnames this credential may be injected toward (no scheme/port/path/IP literal).
                  example:
                  - api.stripe.com
      responses:
        '200':
          description: The credential was escrowed. The value is never echoed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      secret_id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      provider:
                        type: string
                      allowed_hosts:
                        type: array
                        items:
                          type: string
                      sandbox:
                        type: boolean
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PlanLimit'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
  /wrap/tokens:
    post:
      operationId: mintWrapToken
      summary: Mint a base-URL gateway token
      tags:
      - Wrap Credentials
      description: 'For third-party SDKs that expose ONLY a base-URL override and no

        `fetch`/HTTP-client hook. Mints a signed **wrap-token** bound to an

        already-escrowed credential (see POST /wrap/credentials) and one upstream

        host, and returns a `base_url` to set as the wrapped SDK''s base URL.


        The SDK then talks to `/`; KnoxCall reconstructs

        the real destination, injects the escrowed secret (host-pinned), and

        forwards it through the same proxy controls as `/proxy` (SSRF pin, PAN

        refusal, plan/rate metering, audit). **Escrow-only** — the SDK''s own key

        becomes a placeholder; the real key never enters your process.


        The wrap-token is a bearer credential embedded in `base_url`; treat it as

        a secret. Each token is individually revocable via `DELETE /wrap/tokens/{id}`

        (or by deleting the escrowed secret). Only its sha256 is stored server-side.


        Needs `secret:read` on the credential. A token issued to a person

        (`knoxcall login`, a device or authorization-code grant) also needs

        `secret:update` on it: minting a new bearer for a live key is an edit.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - secret
              properties:
                secret:
                  type: string
                  description: The escrowed credential (name or id) to inject.
                  example: wrap-stripe-live
                host:
                  type: string
                  description: Upstream host to pin. Optional when the credential allows exactly one host; must be one of its allowed_hosts otherwise.
                  example: api.stripe.com
                ttl_seconds:
                  type: integer
                  minimum: 1
                  description: Optional token TTL in seconds. Omit for a non-expiring token.
                label:
                  type: string
                  description: Optional human label for the token list.
                style:
                  type: string
                  enum:
                  - path
                  - subdomain
                  description: 'Which base_url form to return. `path` (`…/wg/<token>/<host>`) is always available. `subdomain` (`<label>.wrap.knoxcall.com`) is only available when the operator has enabled the wildcard-subdomain gateway; a `400` is returned otherwise. Omitted ⇒ `subdomain` when enabled, else `path`. NOTE: the subdomain label travels in the TLS SNI (plaintext on the wire) — weaker token confidentiality than the path form; prefer a short `ttl_seconds`.'
      responses:
        '200':
          description: A gateway token + base_url was minted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Token id — pass to DELETE /wrap/tokens/{id} to revoke.
                      token:
                        type: string
                        description: Bearer credential; also embedded in the path base_url. Treat as secret.
                      base_url:
                        type: string
                        description: Set this as the wrapped SDK's base URL.
                      base_url_style:
                        type: string
                        enum:
                        - path
                        - subdomain
                        description: Which base_url form was returned.
                      host:
                        type: string
                      secret_id:
                        type: string
                        format: uuid
                      sandbox:
                        type: boolean
                      expires_at:
                        type:
                        - string
                        - 'null'
                        format: date-time
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listWrapTokens
      summary: List base-URL gateway tokens
      tags:
      - Wrap Credentials
      description: List this space's gateway tokens (metadata only — the token itself is never stored or returned).
      responses:
        '200':
          description: The space's gateway tokens.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      tokens:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            secret_id:
                              type: string
                              format: uuid
                            host:
                              type: string
                            label:
                              type:
                              - string
                              - 'null'
                            created_at:
                              type: string
                              format: date-time
                            expires_at:
                              type:
                              - string
                              - 'null'
                              format: date-time
                            revoked_at:
                              type:
                              - string
                              - 'null'
                              format: date-time
                            last_used_at:
                              type:
                              - string
                              - 'null'
                              format: date-time
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /wrap/intercept-manifest:
    get:
      operationId: getInterceptManifest
      summary: Which hosts an intercept-enabled Route covers
      tags:
      - Wrap Credentials
      description: 'The manifest every KnoxCall SDK''s transparent interceptor polls: for

        this space and ONE environment, the upstream hosts that an enabled Route

        with `intercept_enabled` on covers, and the slug to send them under

        (`x-knoxcall-route`). A third-party SDK''s call to a listed host is sent

        through that Route (the Route injects the stored secret); a listed host

        with no Route is sent through the ephemeral proxy; everything else is

        untouched. Routes targeting KnoxCall''s own hosts are never listed.


        `version` is a content hash of the entries and doubles as the `ETag`;

        send it back as `If-None-Match` and a steady-state poll answers `304`

        with no body. Poll at `ttl_seconds`.


        Scope: `routes:read` — this lists which routes exist, which is a routes

        read; it grants nothing a `GET /routes` caller does not already see.'
      parameters:
      - name: environment
        in: query
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
        description: The environment to resolve for. Omitted ⇒ the tenant's default environment, exactly as a data-plane call with no `x-knoxcall-environment` header resolves. A name that does not exist in this space answers `400`.
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
        description: The `ETag` from a previous response; a match answers `304`.
      responses:
        '200':
          description: The manifest for this space and environment.
          headers:
            ETag:
              schema:
                type: string
              description: W/"<version>" — send back as If-None-Match.
            Cache-Control:
              schema:
                type: string
              description: '`private, max-age=<ttl_seconds>`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InterceptManifest'
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '304':
          description: Unchanged since the `If-None-Match` version; no body.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /wrap/egress-observations:
    post:
      operationId: reportEgressObservations
      summary: Report uncovered egress the SDK's interceptor saw
      tags:
      - Wrap Credentials
      description: 'The complement of the intercept manifest. Every KnoxCall SDK''s

        transparent interceptor sees every outbound request its process makes;

        the ones that carried a credential but were NOT intercepted — no Route

        covers the host, or a Route exists with interception off — are reported

        here so the dashboard''s **Uncovered egress** page can show which hosts

        still have credentials leaving the process, and which existing Route

        would cover each one.


        Reporting is **on by default** in every SDK''s `intercept()` and is

        switched off per install with `observe_uncovered: false` (or, per

        process, `KNOXCALL_OBSERVE_UNCOVERED=off`). What is sent is metadata

        only: the host, the first path segment (`/` or `/`), the

        method, the **name** of the header the credential travelled in, and

        counts with first/last-seen timestamps. Credential values, full paths,

        query strings, bodies and client addresses are never captured, and the

        server refuses an entry that carries anything else in those fields.


        Semantics: at most 200 observations per request (`413` beyond). Each

        entry is validated on its own — a bad entry is **dropped and counted**

        under a reason, never a `400` for the batch. Accepted entries are

        merged per (host, first_segment, method, header_name, UTC day of

        `last_seen`): counts add, timestamps merge as min/max. A space may add

        at most 5,000 distinct keys per day; beyond that entries are dropped

        under `daily_cap`. Rows are kept for 30 days. `sandbox` is taken from

        the reporting credential''s mode.


        Scope: `routes:read` — exactly the manifest''s gate. Policy: `route:read`

        on `*`, evaluated before the body is read, so an ungranted credential

        gets `403` whatever it sends.

        A token issued to a person (`knoxcall login`, a device or

        authorization-code grant) also needs `route:create`, checked at the same

        point.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EgressObservationBatch'
      responses:
        '202':
          description: The batch was processed. `accepted + dropped` equals the number of observations sent; `reasons` says why each dropped entry was refused.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EgressObservationReceipt'
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          description: More than 200 observations in one request. Split the batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /wrap/tokens/{id}:
    delete:
      operationId: revokeWrapToken
      summary: Revoke a base-URL gateway token
      tags:
      - Wrap Credentials
      description: 'Revoke a single gateway token by id (from the mint response or the list).

        Immediately invalidates it for all future `/wg` requests. An already-revoked

        or unknown id in this space is a 404.

        Needs `secret:read`; a token issued to a person also needs `secret:update`.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The token was revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      revoked:
                        type: boolean
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: not_found
              message: Route not found.
              request_id: 550e8400-e29b-41d4-a716-446655440000
    ValidationError:
      description: The request failed validation (always `400 validation_error`). A malformed idempotency key returns `400 invalid_idempotency_key`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validation_error:
              summary: Request body failed validation
              value:
                error:
                  type: validation_error
                  message: name and target_base_url are required.
                  request_id: 550e8400-e29b-41d4-a716-446655440000
            invalid_idempotency_key:
              summary: Malformed idempotency key
              value:
                error:
                  type: invalid_idempotency_key
                  message: X-Idempotency-Key must be a non-empty string of at most 255 characters.
                  request_id: 550e8400-e29b-41d4-a716-446655440000
    Conflict:
      description: A resource with the same unique identifier already exists, or the resource is in use.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: conflict
              message: A route with this name already exists.
              request_id: 550e8400-e29b-41d4-a716-446655440000
    InternalError:
      description: An unexpected server error occurred.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: internal_error
              message: An unexpected error occurred.
              request_id: 550e8400-e29b-41d4-a716-446655440000
    PlanLimit:
      description: 'Payment Required. The action exceeds your plan''s limits. Two `error.type` values

        share this status: `plan_limit` when a COUNTED resource quota was reached (routes,

        secrets, AI agents, MCP servers), and `plan_feature` when the CAPABILITY itself is

        not on your tier (custom PII redaction policies, compliance packs, custom

        prompt-firewall policies). Both mean "upgrade to proceed"; branch on `type` only if

        you want to distinguish "you have used your allowance" from "buy a bigger plan".


        Neither ever revokes something you already have: a plan downgrade leaves existing

        agents, policies and installed packs in place and keeps working.

        '
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: plan_limit
              message: Route limit reached (10). Upgrade your plan to add more.
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: 'The key is authenticated but not authorized for this action (missing scope), a plan

        limit was reached, or the resource must be managed via OAuth (`use_oauth`) / is a

        protected system client (`system_client_protected`).

        '
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            forbidden:
              summary: Missing scope
              value:
                error:
                  type: forbidden
                  message: This key is not authorized to list AI gateways.
                  request_id: 550e8400-e29b-41d4-a716-446655440000
            use_oauth:
              summary: Resource is OAuth-only
              value:
                error:
                  type: use_oauth
                  message: This resource must be managed with an OAuth 2.1 access token.
                  request_id: 550e8400-e29b-41d4-a716-446655440000
            system_client_protected:
              summary: Protected system client
              value:
                error:
                  type: system_client_protected
                  message: This client is managed by the platform and cannot be modified.
                  request_id: 550e8400-e29b-41d4-a716-446655440000
    Unauthorized:
      description: Authentication is required or the provided API key is invalid.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        KnoxCall-Version:
          $ref: '#/components/headers/KnoxCall-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_key:
              summary: No API key provided
              value:
                error:
                  type: authentication_required
                  message: 'API key is required. Use Authorization: Bearer <api_key> or x-api-key header.'
                  request_id: 550e8400-e29b-41d4-a716-446655440000
            invalid_key:
              summary: Invalid API key
              value:
                error:
                  type: invalid_api_key
                  message: Invalid API key.
                  request_id: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    EgressObservation:
      type: object
      description: One (host, first path segment, method, credential header NAME) key the SDK's interceptor saw a credential leave for without interception, with how often and when. Never a credential value, a full path, a query string or a body — the server drops an entry carrying any of those.
      required:
      - host
      - first_segment
      - method
      - header_name
      - count
      - first_seen
      - last_seen
      properties:
        host:
          type: string
          maxLength: 253
          description: Bare DNS hostname. The server lower-cases it, strips a trailing dot, converts an IDN to punycode and drops a port — the same normalisation the intercept manifest applies to a Route's target. A scheme, path, query or userinfo is refused (`invalid_host`); an IP literal (`ip_literal`) and any KnoxCall host (`own_host`) are dropped.
          example: a.klaviyo.com
        first_segment:
          type: string
          pattern: ^/[A-Za-z0-9._~!$&'()*+,;=:@%-]{0,255}$
          description: '`/` or `/<one segment>` — no deeper path, no query string.'
          example: /api
        method:
          type: string
          enum:
          - GET
          - HEAD
          - POST
          - PUT
          - PATCH
          - DELETE
          - OPTIONS
          - CONNECT
          - TRACE
          description: Upper-case, exactly.
          example: GET
        header_name:
          type: string
          maxLength: 64
          pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Lower-case NAME of the header the credential travelled in, from the shared allowlist (`authorization`, `proxy-authorization`, `x-api-key`, `api-key`, `apikey`, `x-apikey`, `x-auth-token`, `x-access-token`, `x-token`, `token`, `x-secret`, `x-secret-key`, `x-client-secret`, `ocp-apim-subscription-key`, `x-goog-api-key`, `x-amz-security-token`, `x-shopify-access-token`, `klaviyo-api-key`, `x-hubspot-api-key`) or any name ending in `-api-key`, `-token`, `-secret` or `-auth`. Anything else is dropped (`invalid_header_name`). The value is never sent.
          example: authorization
        count:
          type: integer
          minimum: 1
          maximum: 1000000
          description: Calls observed for this key in the reported interval.
          example: 12
        first_seen:
          type: string
          format: date-time
          description: ISO-8601 with an offset. Older than 7 days is dropped (`stale`).
          example: '2026-09-26T01:00:00Z'
        last_seen:
          type: string
          format: date-time
          description: ISO-8601 with an offset, not before `first_seen`, not more than 5 minutes ahead of the server clock (`future`). Its UTC calendar day is the row the entry merges into.
          example: '2026-09-26T01:03:00Z'
    EgressObservationBatch:
      type: object
      description: POST /wrap/egress-observations request body.
      required:
      - sdk
      - observations
      properties:
        sdk:
          type: string
          maxLength: 64
          pattern: ^[A-Za-z0-9][A-Za-z0-9._+-]*/[A-Za-z0-9][A-Za-z0-9._+-]*$
          description: The reporting SDK and its version, `<name>/<version>`.
          example: python/1.0.0
        observations:
          type: array
          maxItems: 200
          description: At most 200 per request; more is a `413`.
          items:
            $ref: '#/components/schemas/EgressObservation'
    InterceptManifest:
      type: object
      description: GET /wrap/intercept-manifest. Which upstream hosts an intercept-enabled Route covers for one environment of this space.
      required:
      - version
      - ttl_seconds
      - environment
      - sandbox
      - routes
      properties:
        version:
          type: string
          description: Content hash of `routes`; doubles as the ETag.
          example: sha256:9f2c…
        ttl_seconds:
          type: integer
          description: How long the SDK should hold this manifest before polling again.
          example: 60
        environment:
          type: string
          example: production
        sandbox:
          type: boolean
        routes:
          type: array
          description: Sorted by host, then longest `base_path` first, then slug — the order a longest-prefix match reads.
          items:
            type: object
            required:
            - host
            - base_path
            - slug
            - route_id
            - requires_clients
            - allowed_methods
            properties:
              host:
                type: string
                description: Lower-case DNS hostname, no port, trailing dot stripped.
                example: api.hubapi.com
              base_path:
                type: string
                description: Path prefix the route serves under (`/` when its target has none). The SDK forwards the request path with this prefix removed; a request not under any listed prefix for the host is not a route match.
                example: /crm/v3
              slug:
                type: string
                description: Send as `x-knoxcall-route`.
                example: hubspot
              route_id:
                type: string
                format: uuid
              requires_clients:
                type: boolean
                description: The environment requires a registered client (IP, mTLS or signed assertion). A bearer-only SDK call will be refused; the SDK warns at install and never falls back.
              allowed_methods:
                type:
                - array
                - 'null'
                items:
                  type: string
                description: Upper-cased verbs when method restrictions are on for this environment; null otherwise.
              ambiguous:
                type: boolean
                description: Present and true when another entry shares this (host, base_path); the SDK takes the lexically lowest slug and warns.
              updated_at:
                type:
                - string
                - 'null'
                format: date-time
    RequestMeta:
      type: object
      description: Metadata included with every API response.
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for this API request, useful for support and debugging.
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
      - request_id
    EgressObservationReceipt:
      type: object
      description: What happened to the batch. `accepted + dropped` equals the number of observations sent.
      required:
      - accepted
      - dropped
      - reasons
      - redacted
      properties:
        accepted:
          type: integer
          description: Entries merged into the space's observations.
          example: 11
        dropped:
          type: integer
          description: Entries refused, each counted under exactly one reason.
          example: 1
        reasons:
          type: object
          description: Dropped entries per reason. Keys are from the closed set `malformed`, `invalid_host`, `ip_literal`, `own_host`, `invalid_first_segment`, `invalid_method`, `invalid_header_name`, `invalid_count`, `invalid_timestamp`, `stale`, `future`, `daily_cap`; a reason with no drops is omitted.
          additionalProperties:
            type: integer
          example:
            own_host: 1
        redacted:
          type: object
          description: 'Accepted entries that were altered before storage, per reason. The one reason today is `first_segment_looks_like_credential`: a first path segment that looks like it carries a secret (a Telegram `bot<id>:<token>`, a known key prefix, a long or high-entropy token) is stored as `/`, so a credential value never reaches a row. A reason with no redactions is omitted.'
          additionalProperties:
            type: integer
          example:
            first_segment_looks_like_credential: 1
    ErrorResponse:
      type: object
      description: Standard error response envelope.
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: 'Machine-readable error type. The set is OPEN — endpoints define specific types beyond the common ones below, so clients should branch on the types they know and fall back to the HTTP status class for anything unrecognized. Common values: authentication_required, invalid_api_key, wrong_key_type, subscription_inactive, rate_limit_exceeded, validation_error, forbidden, not_found, method_not_allowed (405, carries Allow), conflict, in_use, plan_limit, plan_feature, internal_error, dependency_unavailable (503, carries Retry-After), invalid_request, invalid_definition, not_cancellable, invalid_idempotency_key, idempotency_key_reuse, request_in_progress, system_client_protected, use_oauth, use_dpop_nonce (401 on /v1 and the data plane, 400 on POST /oauth/token; see "DPoP sender-constrained tokens").'
              example: validation_error
            message:
              type: string
              description: Human-readable error message.
              example: name and target_base_url are required.
            request_id:
              type: string
              format: uuid
              description: Unique identifier for this request.
              example: 550e8400-e29b-41d4-a716-446655440000
          required:
          - type
          - message
          - request_id
      required:
      - error
  parameters:
    IdempotencyKeyParam:
      name: X-Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: 'Optional idempotency key so a retried mutating request is executed at most once.

        The standard `Idempotency-Key` spelling is also accepted. Replaying a completed

        request with the same key returns the original stored response with an

        `X-Idempotent-Replay: true` header. A key still in progress returns

        `409 request_in_progress`; the same key with a different body returns

        `422 idempotency_key_reuse`; a malformed key returns `400 invalid_idempotency_key`.

        '
      example: 3f6c9b2e-1a4d-4c8e-9b0a-7d2e5f1c3a8b
  headers:
    KnoxCall-Version:
      description: 'The dated API version (`YYYY-MM-DD`) that served this response. Equals the value

        of the `KnoxCall-Version` request header when supplied, otherwise the newest version.

        '
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
      example: '2026-08-05'
    X-Request-Id:
      description: 'Unique identifier for this request (UUID). Present on **every** response and equal

        to the `request_id` field in the response body. Quote it when contacting support.

        '
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'OAuth 2.1 authentication — recommended for new integrations. Access tokens

        (`kc_` prefix) are minted at the root-host token endpoint

        `https://api.knoxcall.com/oauth/token` and passed as `Authorization: Bearer <access_token>`.

        Public clients must use PKCE with the `authorization_code` grant; confidential

        clients may use `client_credentials`. The first-party SDKs and the

        `knoxcall login` CLI handle token minting, caching, refresh, and DPoP for you.

        '
      flows:
        clientCredentials:
          tokenUrl: https://api.knoxcall.com/oauth/token
          refreshUrl: https://api.knoxcall.com/oauth/token
          scopes:
            routes:read: Read routes.
            routes:write: Create, update, and delete routes.
            secrets:read: Read secret metadata. Does NOT include retrieving a live OAuth2 access token.
            secrets:oauth_token: Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.
            secrets:write: Create, update, and delete secrets.
            vaults:detokenize: Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.
            transit:decrypt: Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.
            proxy:invoke: Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.
            clients:read: Read clients.
            clients:write: Manage clients.
            webhooks:write: Manage webhooks.
            workflows:write: Manage and execute workflows.
            '*:*': Full access (all scopes).
        authorizationCode:
          authorizationUrl: https://api.knoxcall.com/oauth/authorize
          tokenUrl: https://api.knoxcall.com/oauth/token
          refreshUrl: https://api.knoxcall.com/oauth/token
          scopes:
            routes:read: Read routes.
            routes:write: Create, update, and delete routes.
            secrets:read: Read secret metadata. Does NOT include retrieving a live OAuth2 access token.
            secrets:oauth_token: Retrieve a live upstream OAuth2 access token (GET /v1/secrets/{id}/oauth2/token). Distinct from secrets:read because the call refreshes the credential at the provider.
            secrets:write: Create, update, and delete secrets.
            vaults:detokenize: Turn a vault token back into its original value. Required by GET /v1/vaults/{vault}/tokens/{token}, by a token template reference in a /v1/proxy body, and by creating a `detokenize` route action. Distinct from vaults:read, which lists vaults and token metadata and never returns a value.
            transit:decrypt: Open a portable `kc:` ciphertext with a tenant transit key. Required by creating a `decrypt` route action, which stores a standing instruction to open every matching field on every later request through that route. It is the same capability name the policy engine uses for POST /v1/decrypt. No routes scope satisfies it — managing a route is not permission to open the data flowing through it.
            proxy:invoke: Call the one-shot ephemeral proxy (any method on /v1/proxy). Required for EVERY verb — the proxy is one capability behind one handler, and a bodyless GET spends an escrowed credential exactly as a POST does. Neither proxy:read nor proxy:write satisfies it.
            clients:read: Read clients.
            clients:write: Manage clients.
            webhooks:write: Manage webhooks.
            workflows:write: Manage and execute workflows.
            '*:*': Full access (all scopes).
    PhantomToken:
      type: http
      scheme: bearer
      description: "The AI **data plane** credential — a `kp_`-prefixed capability token, not a\nManagement API credential. It is minted per agent (or per MCP resource) at\n`POST /v1/ai-gateway/agents/{agentId}/tokens`, or exchanged from a CI workload's\nOIDC token at `POST /v1/oauth/token`, and it is the ONLY credential `/v1/ai/*`\naccepts: an OAuth `kc_` access token or a `tk_` API key is refused there, and a\n`kp_` token is refused on `api.knoxcall.com`.\n\nThree header spellings are accepted, so an existing provider SDK can be pointed at\nthe agent URL without rewriting its auth:\n\n    Authorization: Bearer kp_live_a_...\n    x-api-key: kp_live_a_...\n    x-knox-ai-key: kp_live_a_...\n\n`kp_live_` is refused on the sandbox host and `kp_test_` on the Live host — the env\nsegment is enforced, not cosmetic. DPoP-bound tokens additionally require a valid\n`DPoP` proof header on every request, signed over the canonical public URL rather\nthan a rewritten `Host`.\n\nA rejected credential answers `401`/`403` in the data-plane error envelope with the\ncause in `code` and in the `X-Auth-Failure` response header.\n"
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Legacy long-lived API key authentication via the Authorization header.

        Pass your API key as: `Authorization: Bearer tk_xxx_yyy`.


        Standard keys (`tk_` prefix) are accepted on `api.knoxcall.com`.

        Test keys (type=test) are accepted on `sandbox.knoxcall.com`.

        Enterprise Access Keys (`AKE` prefix) are accepted on both.


        Fully supported, but prefer the `OAuth2` scheme (or the SDKs, which handle

        OAuth for you) for new integrations.

        '
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Legacy API key authentication via the `x-api-key` header.

        This is an alternative to Bearer token authentication for clients that cannot

        set the `Authorization` header. Prefer the `OAuth2` scheme for new integrations.

        '
    CapabilityTokenAuth:
      type: http
      scheme: bearer
      description: 'Single-use client capability token (`kct_` prefix), passed as

        `Authorization: Bearer kct_...`. Minted server-side via

        `POST /client-tokens` and bound either to one exact payload + action

        (`decrypt`, `detokenize`) or to one vault + a closed set of page

        origins (`tokenize`). This is NOT an API key — it authenticates only

        the `POST /client/decrypt`, `POST /client/detokenize` and

        `POST /client/tokenize` consume endpoints and is invalidated after its

        first use.

        '