generated: '2026-10-20'
method: derived
generator: derive-data-model.py
source:
- openapi/knoxcall-account-api-openapi.yml
- openapi/knoxcall-agents-api-openapi.yml
- openapi/knoxcall-ai-gateway-api-openapi.yml
- openapi/knoxcall-api-keys-api-openapi.yml
- openapi/knoxcall-audit-logs-api-openapi.yml
- openapi/knoxcall-client-tokens-api-openapi.yml
- openapi/knoxcall-clients-api-openapi.yml
- openapi/knoxcall-crypto-keys-api-openapi.yml
- openapi/knoxcall-dynamic-db-credentials-api-openapi.yml
- openapi/knoxcall-encryption-api-openapi.yml
- openapi/knoxcall-environments-api-openapi.yml
- openapi/knoxcall-ephemeral-proxy-api-openapi.yml
notation: has_one = property $ref; has_many = array of $ref; belongs_to = <entity>_id field
summary:
  entities: 126
  entities_in_spec: 126
  relationships: 33
entities:
- name: Account
  fields: 12
  description: Account information and subscription details.
- name: AccountUsage
  fields: 5
  description: Current billing period usage and plan limits.
- name: Agent
  fields: 9
  description: A BYO server agent registration.
- name: AgentCreated
  fields: 7
  description: The newly registered agent, including its one-time secret.
- name: AgentTamperEvent
  fields: 6
  description: A recorded tamper event (unverified build, signature mismatch) for an agent.
- name: AiGateway
  fields: 15
  description: An AI gateway — the top-level container that agents are created under.
- name: AiGatewayAgent
  fields: 48
  description: An agent under a gateway — the addressable unit an AI SDK points at.
- name: AiGatewayDataPlaneError
  fields: 3
  description: AIGW-163 — the ONE error envelope of the AI data plane, served by `/v1/ai/*` and by
- name: AiGatewayFirewallPolicy
  fields: 8
  description: A tenant-scoped prompt-firewall policy, attachable to agents and MCP servers.
- name: AiGatewayFirewallPolicyCreate
  fields: 4
- name: AiGatewayFirewallRule
  fields: 4
  description: One heuristic rule inside a firewall policy.
- name: AiGatewayFirewallTestResult
  fields: 3
- name: AiGatewayMcpAuth
  fields: 2
  description: 'Upstream auth for an MCP server. A secret reference is the only supported path: every header value
    must contain a `{{secret_id:<uuid>}}` (or legacy `{{secret:<name>}}`) placeholder. A literal is refus'
- name: AiGatewayMcpGrant
  fields: 10
  description: One person's delegated-OAuth connection to an MCP server (AIGW-190).
- name: AiGatewayMcpServer
  fields: 24
  description: An MCP server KnoxCall proxies and governs. `connect_url` and `resource`
- name: AiGatewayMcpTool
  fields: 10
  description: A tool metadata row. It does not widen what the server advertises — that is the intersection of `allowed_tools`,
    the upstream's real tools and the token's tool scope.
- name: AiGatewayPhantomToken
  fields: 10
  description: A capability (phantom) token row. The plaintext is never returned here — only at mint time.
- name: AiGatewayPhantomTokenCreated
  fields: 7
  description: The mint result. `token` is the plaintext capability token and is shown exactly once.
- name: AiGatewayPiiPolicy
  fields: 8
  description: A tenant-scoped bundle of PII recognizers plus a default action, attached to an agent
- name: AiGatewayPiiPolicyCreate
  fields: 4
- name: AiGatewayPiiRecognizer
  fields: 11
  description: One tenant-defined PII detector.
- name: AiGatewayPiiRecognizerCreate
  fields: 8
- name: AiGatewayPiiRecognizerTestResult
  fields: 2
- name: AiGatewayPiiRecognizerUpdate
  fields: 8
  description: Partial. The server validates the MERGED state, not the patch — `pattern`, `kind` and
- name: AiGatewayRoutingPolicy
  fields: 9
  description: How this agent retries and spreads load (AIGW-42). An empty object — the default for every agent
    — means one attempt per route and fail-over to `fallback_route_ids` on 5xx only, which is the behaviour
- name: AiGatewayTokenExchangeRequest
  fields: 5
  description: RFC 8693 token-exchange request for `POST /v1/oauth/token`. Sent as
- name: AiGatewayTokenExchangeResponse
  fields: 5
  description: RFC 8693 §2.2.1 response. This is a bare OAuth body, NOT the `{data, meta}` envelope
- name: AiGatewayUsage
  fields: 3
  description: Cost and token rollup by model over the requested period.
- name: AiGatewayUsageByModel
  fields: 7
- name: AiGatewayUsageExport
  fields: 3
  description: FinOps showback/chargeback rollup, aggregated by the requested dimension.
- name: AiGatewayUsageExportRow
  fields: 6
- name: AiGatewayUsageTotals
  fields: 5
- name: ApiKey
  fields: 11
  description: An API key (masked -- full key is only returned at creation time).
- name: ApiKeyCreated
  fields: 9
  description: API key creation response. The `api_key` field contains the full key and is
- name: AuditLog
  fields: 8
  description: An immutable record of an action performed via the API.
- name: CARole
  fields: 9
  description: An issuing role — a named policy constraining what certificates can be issued under a root.
- name: CARoot
  fields: 11
  description: A private certificate-authority root.
- name: CertificateSecretCreated
  fields: 7
  description: Response after creating a certificate secret.
- name: Client
  fields: 10
  description: An authorized client (user or server) with IP-based access control.
- name: ClientCredential
  fields: 11
  description: A credential attached to a client. Secret material (HMAC secrets, private keys) is redacted from
    `data`.
- name: ClientCredentialCreated
  fields: 0
- name: ClientDetail
  fields: 0
  description: Extended client object with route assignments.
- name: ClientFull
  fields: 0
  description: Full client row as returned by create and update operations.
- name: CreateAiGatewayAgentRequest
  fields: 41
- name: CreateAiGatewayMcpServerRequest
  fields: 16
- name: CreateAiGatewayRequest
  fields: 6
- name: CreateApiKeyRequest
  fields: 7
- name: CreateCertificateSecretRequest
  fields: 7
- name: CreateClientCredentialRequest
  fields: 3
- name: CreateClientRequest
  fields: 4
- name: CreateDbConnectionRequest
  fields: 20
- name: CreateEnvironmentRequest
  fields: 5
- name: CreateOAuth2SecretRequest
  fields: 13
- name: CreateOAuthClientRequest
  fields: 8
- name: CreateRouteActionRequest
  fields: 7
- name: CreateRouteRequest
  fields: 10
- name: CreateTransitKeyRequest
  fields: 4
- name: CreateVaultRequest
  fields: 7
- name: CreateWebhookRequest
  fields: 19
- name: CreateWorkflowRequest
  fields: 6
  description: Request body to create or update a workflow.
- name: DbConnection
  fields: 20
  description: A registered database connection. Admin passwords and SSH private keys are never returned.
- name: DbLease
  fields: 8
  description: A credential lease.
- name: DbRole
  fields: 8
  description: A role — the SQL templates KnoxCall runs to create and drop a leased database user.
- name: DeletedResponse
  fields: 2
- name: EgressObservation
  fields: 7
  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
- name: EgressObservationBatch
  fields: 2
  description: POST /wrap/egress-observations request body.
- name: EgressObservationReceipt
  fields: 4
  description: What happened to the batch. `accepted + dropped` equals the number of observations sent.
- name: Environment
  fields: 7
  description: A deployment environment used to scope route configurations.
- name: ErrorResponse
  fields: 1
  description: Standard error response envelope.
- name: InspectResult
  fields: 6
  description: Metadata about a `kc:` ciphertext. When `encrypted` is false the value is not a valid `kc:` ciphertext
    and all other fields are omitted.
- name: InterceptManifest
  fields: 5
  description: GET /wrap/intercept-manifest. Which upstream hosts an intercept-enabled Route covers for one environment
    of this space.
- name: IssuedCertificate
  fields: 6
  description: A leaf certificate issued under a role.
- name: MintAiGatewayTokenRequest
  fields: 5
- name: MintedDbCredential
  fields: 6
  description: A freshly minted short-lived database credential.
- name: OAuthClient
  fields: 17
  description: An OAuth 2.1 client as returned in list responses.
- name: OAuthClientCreated
  fields: 7
  description: The newly created OAuth client, including its one-time secret.
- name: OAuthClientDetail
  fields: 16
  description: Full OAuth client detail.
- name: OAuthDeviceAuthorizationRequest
  fields: 2
  description: OAuth device authorization request (RFC 8628 §3.1). Sent as `application/x-www-form-urlencoded`.
- name: OAuthDeviceAuthorizationResponse
  fields: 6
  description: OAuth device authorization response (RFC 8628 §3.2).
- name: OAuthError
  fields: 3
  description: OAuth 2.1 error response (RFC 6749 §5.2). The OAuth endpoints use this shape rather than the /v1
    `ErrorResponse` envelope.
- name: OAuthIntrospectRequest
  fields: 4
  description: OAuth token introspection request (RFC 7662 §2.1). Sent as `application/x-www-form-urlencoded`.
- name: OAuthIntrospectionResponse
  fields: 9
  description: OAuth token introspection response (RFC 7662 §2.2).
- name: OAuthRevokeRequest
  fields: 4
  description: OAuth token revocation request (RFC 7009 §2.1). Sent as `application/x-www-form-urlencoded`.
- name: OAuthServerMetadata
  fields: 11
  description: OAuth 2.0 authorization server metadata (RFC 8414).
- name: OAuthTokenRequest
  fields: 9
  description: OAuth 2.1 token request (RFC 6749 §4, RFC 8628 §3.4). Sent as `application/x-www-form-urlencoded`.
- name: OAuthTokenResponse
  fields: 7
  description: OAuth 2.1 access token response (RFC 6749 §5.1).
- name: Opportunity
  fields: 12
  description: A promotion suggestion (agent_monitor or gateway_traffic source).
- name: PaginationMeta
  fields: 5
  description: Pagination metadata for list endpoints.
- name: RequestLog
  fields: 23
  description: A record of a proxied API request.
- name: RequestLogProof
  fields: 11
  description: A Merkle inclusion proof for one request log row, or a named reason why
- name: RequestMeta
  fields: 1
  description: Metadata included with every API response.
- name: ResourceUsage
  fields: 2
  description: Usage count and limit for a resource type.
- name: Role
  fields: 6
  description: A named bundle of permission policies. Read-only on `/v1`, and exposed so a machine
- name: Route
  fields: 17
  description: Full route row as returned after create or update operations. Runtime
- name: RouteAction
  fields: 11
  description: A declarative field-level action the proxy applies to a route's traffic on the wire.
- name: RouteDetail
  fields: 17
  description: Route detail as returned by `GET /routes/{id}`. The
- name: RouteEnvironmentConfig
  fields: 18
  description: Environment-specific configuration override for a route.
- name: RouteEnvironmentConfigInput
  fields: 11
  description: Fields for creating or updating an environment override. All fields are optional;
- name: RouteSummary
  fields: 16
  description: Summary representation of a route returned in list responses.
- name: SealingBundle
  fields: 2
  description: Public material a browser needs to seal values client-side. Contains no private material.
- name: Secret
  fields: 10
  description: Secret metadata. Secret values are never returned by the API. Reference
- name: TransitKey
  fields: 12
  description: A transit encryption key. Key material never leaves KnoxCall.
- name: UpdateAiGatewayAgentRequest
  fields: 38
  description: Only the provided fields are changed. Every writable column on an agent appears here — this schema
    is what the typed SDKs are generated and reviewed against, so a field missing from it becomes a field
- name: UpdateAiGatewayMcpServerRequest
  fields: 15
- name: UpdateAiGatewayRequest
  fields: 7
  description: Only the provided fields are changed.
- name: UpdateClientRequest
  fields: 5
  description: All fields are optional. Only provided fields will be updated.
- name: UpdateEnvironmentRequest
  fields: 5
  description: All fields are optional. Only provided fields will be updated.
- name: UpdateOAuthClientRequest
  fields: 9
  description: Any subset of fields may be supplied; at least one is required. Grant types cannot be changed after
    creation.
- name: UpdateRouteRequest
  fields: 21
  description: All fields are optional. Only provided fields will be updated.
- name: UpdateWebhookRequest
  fields: 19
  description: All fields are optional. Only provided fields will be updated.
- name: UpsertAiGatewayMcpToolRequest
  fields: 4
- name: Vault
  fields: 15
  description: A tokenization vault with its own encryption key.
- name: VaultToken
  fields: 9
  description: Token metadata as returned in list responses. The original value is never included.
- name: VaultTokenCreated
  fields: 7
  description: The result of tokenizing a value.
- name: VaultTokenDetail
  fields: 8
  description: A detokenized token — includes the original value.
- name: VaultTokenExpiringEventPayload
  fields: 3
  description: Payload delivered for the `vault.token.expiring` event — Card-Grade
- name: WebhookCreated
  fields: 13
  description: Webhook creation response, including the one-time signing secret.
- name: WebhookDetail
  fields: 22
  description: 'Full webhook object with all configuration fields and delivery statistics. Credential material is
    never returned: `secret_key`, `auth_config` and `request_headers` are all accepted on create/update an'
- name: WebhookEventPayload
  fields: 6
  description: Payload delivered to webhook endpoints when events are triggered.
- name: WebhookEventRequest
  fields: 5
  description: Details of the original proxied request (included based on webhook configuration).
- name: WebhookEventResponse
  fields: 4
  description: Details of the upstream response (included based on webhook configuration).
- name: WebhookLog
  fields: 9
  description: A record of a webhook delivery attempt.
- name: WebhookSummary
  fields: 13
  description: Summary representation of a webhook returned in list responses.
- name: WebhookUpdated
  fields: 9
  description: Webhook update response (no secret or delivery-stat fields).
- name: Workflow
  fields: 13
  description: A workflow — a graph of nodes executed on a trigger.
- name: WorkflowExecution
  fields: 11
  description: A single workflow run.
relationships:
- from: AgentCreated
  to: Agent
  type: belongs_to
  via: agent_id
- from: CreateAiGatewayMcpServerRequest
  to: AiGatewayMcpAuth
  type: has_one
  via: auth
- from: AiGatewayMcpTool
  to: Route
  type: belongs_to
  via: route_id
- from: UpdateAiGatewayAgentRequest
  to: AiGatewayRoutingPolicy
  type: has_one
  via: routing_policy
- from: AiGatewayUsage
  to: AiGatewayUsageByModel
  type: has_many
  via: by_model
- from: AiGatewayUsage
  to: AiGatewayUsageTotals
  type: has_one
  via: totals
- from: AiGatewayUsageExport
  to: AiGatewayUsageExportRow
  type: has_many
  via: rows
- from: AiGatewayAgent
  to: AiGatewayRoutingPolicy
  type: has_one
  via: routing_policy
- from: CreateAiGatewayAgentRequest
  to: AiGatewayRoutingPolicy
  type: has_one
  via: routing_policy
- from: AiGatewayFirewallPolicyCreate
  to: AiGatewayFirewallRule
  type: has_many
  via: heuristics
- from: AiGatewayFirewallPolicy
  to: AiGatewayFirewallRule
  type: has_many
  via: heuristics
- from: UpdateAiGatewayMcpServerRequest
  to: AiGatewayMcpAuth
  type: has_one
  via: auth
- from: ApiKeyCreated
  to: Role
  type: belongs_to
  via: role_ids
- from: CreateApiKeyRequest
  to: Role
  type: belongs_to
  via: role_ids
- from: ClientCredential
  to: Client
  type: belongs_to
  via: client_id
- from: DeletedResponse
  to: RequestMeta
  type: has_one
  via: meta
- from: DbConnection
  to: Agent
  type: belongs_to
  via: agent_id
- from: CreateDbConnectionRequest
  to: Agent
  type: belongs_to
  via: agent_id
- from: OAuthIntrospectRequest
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthDeviceAuthorizationRequest
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthClientCreated
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthTokenResponse
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthClientDetail
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthTokenRequest
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthIntrospectionResponse
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthRevokeRequest
  to: Client
  type: belongs_to
  via: client_id
- from: OAuthClient
  to: Client
  type: belongs_to
  via: client_id
- from: CARole
  to: CARoot
  type: belongs_to
  via: ca_root_id
- from: RequestLog
  to: Route
  type: belongs_to
  via: route_id
- from: RouteAction
  to: Route
  type: belongs_to
  via: route_id
- from: CreateOAuth2SecretRequest
  to: Client
  type: belongs_to
  via: client_id
- from: WorkflowExecution
  to: Workflow
  type: belongs_to
  via: workflow_id
- from: EgressObservationBatch
  to: EgressObservation
  type: has_many
  via: observations