KnoxCall Agents API

openapi: 3.2.0
info:
  title: KnoxCall Client Management Agents 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: Agents
  description: Manage BYO server agents (self-hosted data-plane / tunnel agents).
paths:
  /agents:
    get:
      operationId: listAgents
      summary: List agents
      description: Returns all agent registrations for the account, newest first (not paginated).
      tags:
      - Agents
      responses:
        '200':
          description: List of agents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createAgent
      summary: Register an agent
      description: 'Registers a new BYO server agent and returns its `agent_secret` —

        **shown exactly once**; the agent uses it to authenticate its

        sessions. Requires a Pro plan or higher; maximum 10 active agents per

        data space (Live and Test are counted separately). The agent is

        created in the data space of the key that calls this: a `tk_test_` key

        on the sandbox host registers a Test agent, whose session bundle

        resolves to Test routes and Test secrets only.


        **Requires an explicit `agent:create` policy grant.** A wildcard

        (`*:*`) rule does not satisfy it — including the `legacy_admin` policy

        that every key created before 2026-06-30 still carries. The seeded key

        roles that name the action literally (Key - Infrastructure, Key -

        Editor) are unaffected and keep working. Without the grant the call

        returns `403 forbidden` and no agent is created.


        An `agent_secret` is the largest single reveal in the API: it redeems

        at `POST /agent/v1/session` for every secret in the data space,

        decrypted. Every successful call therefore also emails the account''s

        owners, out of band.


        **A scope-narrowed OAuth token cannot register an agent** and gets

        `403 privilege_escalation`: an agent credential authenticates intercepted

        requests on the data plane without consulting any scope, so it would exceed

        the token''s own grant. Register agents with an API key, or with an OAuth

        token whose scope is not narrowed.'
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 100
                  description: Human-readable agent name.
                  example: prod-vpc-tunnel
      responses:
        '200':
          description: Agent registered. Store `agent_secret` now — it is never shown again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentCreated'
                  meta:
                    type: object
                    description: This endpoint's meta carries only the one-time-secret flag (no request_id).
                    properties:
                      secret_shown_once:
                        type: boolean
                        example: true
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PlanLimit'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The agent registration UUID.
    delete:
      operationId: revokeAgent
      summary: Revoke an agent
      description: Revokes an agent registration. The agent's sessions stop being honoured immediately.
      tags:
      - Agents
      responses:
        '200':
          description: Agent revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      revoked:
                        type: boolean
                        example: true
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /agents/{id}/tamper-events:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The agent registration UUID.
    get:
      operationId: listAgentTamperEvents
      summary: List agent tamper events
      description: Returns the most recent 50 tamper events recorded for the agent (unverified builds, signature mismatches).
      tags:
      - Agents
      responses:
        '200':
          description: List of tamper events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentTamperEvent'
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '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
    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:
    Agent:
      type: object
      description: A BYO server agent registration.
      properties:
        id:
          type: string
          format: uuid
          example: 6d4a1b2c-3e5f-4a6b-8c7d-9e0f1a2b3c4d
        name:
          type: string
          example: prod-vpc-tunnel
        agent_id:
          type: string
          description: Public agent identifier (`kc_agent_` prefix) the agent presents when opening sessions.
          example: kc_agent_3f9a1b2c4d5e
        status:
          type: string
          enum:
          - active
          - revoked
        require_verified_build:
          type: boolean
          description: Whether sessions are refused for unverified agent builds.
        last_seen_at:
          type:
          - string
          - 'null'
          format: date-time
        last_session_issued_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
          example: '2025-03-15T10:30:00.000Z'
        has_tamper_events:
          type: boolean
          description: Whether any tamper events have been recorded for this agent.
    AgentCreated:
      type: object
      description: The newly registered agent, including its one-time secret.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: prod-vpc-tunnel
        agent_id:
          type: string
          example: kc_agent_3f9a1b2c4d5e
        status:
          type: string
          enum:
          - active
          - revoked
          example: active
        require_verified_build:
          type: boolean
        created_at:
          type: string
          format: date-time
        agent_secret:
          type: string
          description: '**Shown exactly once** — only a hash is stored, so it can never be retrieved again. 64 hex characters.'
    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
    AgentTamperEvent:
      type: object
      description: A recorded tamper event (unverified build, signature mismatch) for an agent.
      properties:
        id:
          type: string
          format: uuid
        version_reported:
          type:
          - string
          - 'null'
          description: Agent version string reported at session time.
        build_sig_reported:
          type:
          - string
          - 'null'
          description: Build signature the agent reported.
        src_ip:
          type:
          - string
          - 'null'
          description: Source IP of the offending session attempt.
        action_taken:
          type:
          - string
          - 'null'
          description: What KnoxCall did in response (e.g. session refused).
        detected_at:
          type: string
          format: date-time
          example: '2025-03-15T10:30:00.000Z'
    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
  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.

        '