{
  "openapi": "3.1.0",
  "info": {
    "title": "Kastra public API",
    "version": "2026-09-22",
    "description": "Reviewed runtime endpoints and selected customer management reads. Endpoint guides describe additional policy operations and availability. Internal administration routes are excluded.",
    "contact": {
      "url": "https://kastra.ai/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.kastra.ai"
    }
  ],
  "security": [
    {
      "EnvironmentKey": []
    },
    {
      "DeviceCredential": []
    }
  ],
  "paths": {
    "/v1/evaluate": {
      "post": {
        "operationId": "evaluateAction",
        "summary": "Evaluate a connected action",
        "description": "Cooperative authorization. The caller must enforce the result before dispatch. HOLD requires negotiation, an enabled subsystem, and a supported trigger. A post-action event cannot block work already completed. Normal recording failures refuse the request by default; direct HOLD has separate record behavior described in the guide.",
        "externalDocs": {
          "url": "https://docs.kastra.ai/reference/evaluate"
        },
        "parameters": [
          {
            "in": "header",
            "name": "Accept-Kastra-Hold",
            "required": false,
            "description": "Opt into supported asynchronous checkpoint responses.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "in": "header",
            "name": "Accept-Kastra-RateLimit",
            "required": false,
            "description": "Opt into 429 for a supported metered denial.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "description": "Optional supported transport retry key. Same key with a changed body returns 422. Device-only context and failed cache storage can bypass this middleware; it is not a universal exactly-once guarantee.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvaluateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy or posture permits the action; inspect the result and enforcement headers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Decision"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "202": {
            "description": "Supported action is pending review. Do not dispatch it yet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Hold"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            },
            "headers": {
              "X-Policy-Decision": {
                "schema": {
                  "type": "string",
                  "const": "PENDING_REVIEW"
                },
                "description": "Stored/header outcome; data.decision uses HOLD."
              }
            }
          },
          "400": {
            "description": "Invalid request or scope."
          },
          "401": {
            "description": "Missing or invalid credential."
          },
          "403": {
            "description": "Policy or oversize denial, or a route/entitlement error. Decode the envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "const": true
                        },
                        "data": {
                          "$ref": "#/components/schemas/Decision"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "success",
                        "data"
                      ]
                    },
                    {
                      "$ref": "#/components/schemas/APIError"
                    }
                  ]
                }
              }
            }
          },
          "409": {
            "description": "A supported Idempotency-Key is already in progress. Retry the identical request after the indicated delay.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Delay in seconds."
              }
            }
          },
          "413": {
            "description": "Complete request body exceeds the body limit."
          },
          "422": {
            "description": "A supported idempotency key was reused with a changed body."
          },
          "429": {
            "description": "Negotiated rate-limit result or middleware throttle; inspect the body."
          },
          "500": {
            "description": "Server error; apply explicit client failure behavior."
          },
          "503": {
            "description": "Service or required decision storage unavailable. This is not an ALLOW."
          }
        }
      }
    },
    "/v1/limits": {
      "get": {
        "operationId": "readEffectiveLimits",
        "summary": "Read effective request byte limits",
        "description": "Authenticated API/device context. Returns a private cache directive. Tier can be unknown when entitlement resolution falls back.",
        "responses": {
          "200": {
            "description": "Effective limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Limits"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or scope."
          },
          "401": {
            "description": "Missing or invalid credential."
          },
          "403": {
            "description": "Access denied; decode the response shape."
          },
          "500": {
            "description": "Server error; apply explicit client failure behavior."
          },
          "503": {
            "description": "Service or required decision storage unavailable. This is not an ALLOW."
          }
        }
      }
    },
    "/v1/checkpoints/{id}": {
      "get": {
        "operationId": "readCheckpoint",
        "summary": "Read a checkpoint and effective decision",
        "description": "API/device credential with authorized tenant scope. This is a read operation; an API key is not a human approver.",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Checkpoint state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Checkpoint"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or scope."
          },
          "401": {
            "description": "Missing or invalid credential."
          },
          "403": {
            "description": "Access denied; decode the response shape."
          },
          "404": {
            "description": "Checkpoint does not exist or is outside the permitted scope."
          },
          "500": {
            "description": "Server error; apply explicit client failure behavior."
          },
          "503": {
            "description": "Service or required decision storage unavailable. This is not an ALLOW."
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "proxyChatCompletions",
        "summary": "Proxy OpenAI Chat Completions",
        "description": "Provider-specific request compatibility within this route. This subset leaves provider payloads open; it is not a full provider schema. Inspect policy and error output before dispatching tools. Custom proxy attributes use X-Kastra-Attr-* headers and are bounded by the ingress contract.",
        "security": [
          {
            "EnvironmentKey": []
          }
        ],
        "externalDocs": {
          "url": "https://docs.kastra.ai/proxy/approvals"
        },
        "parameters": [
          {
            "in": "header",
            "name": "X-Upstream-API-Key",
            "required": true,
            "description": "Upstream provider credential. Required for the documented cloud setup; an appliance can have an explicitly configured server credential.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-Jurisdiction",
            "required": false,
            "description": "Policy context; not a data residency selector.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-Kastra-Hold-Mode",
            "required": false,
            "description": "Async pre/content HOLD negotiation. Does not make every post-output HOLD asynchronous.",
            "schema": {
              "type": "string",
              "enum": [
                "async"
              ]
            }
          },
          {
            "in": "header",
            "name": "X-Kastra-Operation-Id",
            "required": false,
            "description": "Use the same operation ID for a retry of the same intended action and a new ID for a distinct action. Approval replay also binds raw body and other request identity fields. The optional self-hosted execution-journal profile requires a canonical UUID; see deployment qualifications in the guide.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProviderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Provider-compatible JSON or event stream, subject to output controls. A stream may later report an error.",
            "headers": {
              "X-Policy-Decision": {
                "schema": {
                  "type": "string"
                },
                "description": "Policy outcome; inspect stage-specific headers and body as well."
              },
              "X-Policy-Latency-Ms": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "Negotiated async request HOLD; provider-style error with hold_pending, checkpoint_id, approval URL, and resubmission context."
          },
          "400": {
            "description": "Invalid request or scope."
          },
          "401": {
            "description": "Missing or invalid credential."
          },
          "402": {
            "description": "Entitlement or spend restriction; inspect response."
          },
          "403": {
            "description": "Access denied; decode the response shape."
          },
          "429": {
            "description": "Rate or usage restriction; inspect response."
          },
          "500": {
            "description": "Server error; apply explicit client failure behavior."
          },
          "502": {
            "description": "Upstream failure."
          },
          "503": {
            "description": "Required decision recording or another service is unavailable. Proxy recording failures before committed output use decision_record_failed and X-Policy-Decision: UNAVAILABLE; committed streams use an error event."
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "operationId": "proxyAnthropicMessages",
        "summary": "Proxy Anthropic Messages",
        "description": "Provider-specific request compatibility within this route. This subset leaves provider payloads open; it is not a full provider schema. Inspect policy and error output before dispatching tools. Custom proxy attributes use X-Kastra-Attr-* headers and are bounded by the ingress contract.",
        "security": [
          {
            "EnvironmentKey": []
          }
        ],
        "externalDocs": {
          "url": "https://docs.kastra.ai/proxy/approvals"
        },
        "parameters": [
          {
            "in": "header",
            "name": "X-Upstream-API-Key",
            "required": true,
            "description": "Upstream provider credential. Required for the documented cloud setup; an appliance can have an explicitly configured server credential.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-Jurisdiction",
            "required": false,
            "description": "Policy context; not a data residency selector.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-Kastra-Hold-Mode",
            "required": false,
            "description": "Async pre/content HOLD negotiation. Does not make every post-output HOLD asynchronous.",
            "schema": {
              "type": "string",
              "enum": [
                "async"
              ]
            }
          },
          {
            "in": "header",
            "name": "X-Kastra-Operation-Id",
            "required": false,
            "description": "Use the same operation ID for a retry of the same intended action and a new ID for a distinct action. Approval replay also binds raw body and other request identity fields. The optional self-hosted execution-journal profile requires a canonical UUID; see deployment qualifications in the guide.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ProviderRequest"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "max_tokens": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "max_tokens"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Provider-compatible JSON or event stream, subject to output controls. A stream may later report an error.",
            "headers": {
              "X-Policy-Decision": {
                "schema": {
                  "type": "string"
                },
                "description": "Policy outcome; inspect stage-specific headers and body as well."
              },
              "X-Policy-Latency-Ms": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "Negotiated async request HOLD; provider-style error with hold_pending, checkpoint_id, approval URL, and resubmission context."
          },
          "400": {
            "description": "Invalid request or scope."
          },
          "401": {
            "description": "Missing or invalid credential."
          },
          "402": {
            "description": "Entitlement or spend restriction; inspect response."
          },
          "403": {
            "description": "Access denied; decode the response shape."
          },
          "429": {
            "description": "Rate or usage restriction; inspect response."
          },
          "500": {
            "description": "Server error; apply explicit client failure behavior."
          },
          "502": {
            "description": "Upstream failure."
          },
          "503": {
            "description": "Required decision recording or another service is unavailable. Proxy recording failures before committed output use decision_record_failed and X-Policy-Decision: UNAVAILABLE; committed streams use an error event."
          }
        }
      }
    },
    "/v1/content/preview": {
      "post": {
        "operationId": "previewMaskedContent",
        "summary": "Mask content for display without retaining it",
        "description": "Environment API key only. Complete UTF-8 JSON body is limited to 256 KiB and must contain only a content string. Does not evaluate policy, store input or call a model. Render as plain text; masking does not guarantee anonymity.",
        "security": [
          {
            "EnvironmentKey": []
          }
        ],
        "externalDocs": {
          "url": "https://docs.kastra.ai/reference/evaluate#display-only-content-preview"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "additionalProperties": false,
                "properties": {
                  "content": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Masked display content.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "content",
                        "redaction_count"
                      ],
                      "properties": {
                        "content": {
                          "type": "string"
                        },
                        "redaction_count": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            }
          },
          "400": {
            "description": "Invalid UTF-8, JSON, missing content or unsupported fields."
          },
          "401": {
            "description": "Missing or invalid environment API key."
          },
          "413": {
            "description": "Complete request body exceeds 256 KiB."
          }
        }
      }
    },
    "/v1/trusted-evidence": {
      "get": {
        "operationId": "readTrustedEvidenceCapability",
        "summary": "Read optional trusted-evidence custody capability",
        "description": "Reports deployment configuration without exposing store paths or records. enabled does not certify any particular evidence. No public evidence write route exists.",
        "externalDocs": {
          "url": "https://docs.kastra.ai/reference/api#optional-trusted-evidence-capability"
        },
        "responses": {
          "200": {
            "description": "Deployment capability.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "protocol",
                        "enabled"
                      ],
                      "properties": {
                        "protocol": {
                          "type": "integer",
                          "const": 1
                        },
                        "enabled": {
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential."
          }
        }
      }
    },
    "/api/v1/environments": {
      "get": {
        "operationId": "listEnvironments",
        "summary": "List workspace environments",
        "description": "Selected read contract; see the customer management guide for additional filters and operations. Preserve unknown response fields.",
        "externalDocs": {
          "url": "https://docs.kastra.ai/reference/management-api"
        },
        "security": [
          {
            "CustomerSession": []
          }
        ],
        "parameters": [
          {
            "name": "X-Organization-ID",
            "in": "header",
            "required": true,
            "description": "Authorized workspace UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorized records. Additional fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "display_name": {
                            "type": "string"
                          },
                          "is_production": {
                            "type": "boolean"
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid scope or input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/policies": {
      "get": {
        "operationId": "listPolicies",
        "summary": "List workspace policies",
        "description": "Selected read contract; see the customer management guide for additional filters and operations. Preserve unknown response fields.",
        "externalDocs": {
          "url": "https://docs.kastra.ai/reference/management-api"
        },
        "security": [
          {
            "CustomerSession": []
          }
        ],
        "parameters": [
          {
            "name": "X-Organization-ID",
            "in": "header",
            "required": true,
            "description": "Authorized workspace UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "environment_id",
            "in": "query",
            "required": false,
            "description": "Authorized environment UUID. Omit to include all authorized environments.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Row offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorized records. Additional fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "environment": {
                            "type": "string"
                          },
                          "is_active": {
                            "type": "boolean"
                          },
                          "active_revision_number": {
                            "type": "integer"
                          },
                          "default_decision": {
                            "type": "string",
                            "enum": [
                              "",
                              "allow",
                              "deny"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid scope or input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/decisions": {
      "get": {
        "operationId": "listDecisions",
        "summary": "Read decision history",
        "description": "Selected read contract; see the customer management guide for additional filters and operations. Preserve unknown response fields.",
        "externalDocs": {
          "url": "https://docs.kastra.ai/reference/management-api"
        },
        "security": [
          {
            "CustomerSession": []
          }
        ],
        "parameters": [
          {
            "name": "X-Organization-ID",
            "in": "header",
            "required": true,
            "description": "Authorized workspace UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "environment_id",
            "in": "query",
            "required": false,
            "description": "Authorized environment UUID. Omit to include all authorized environments.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "decision",
            "in": "query",
            "required": false,
            "description": "Stored decision outcome.",
            "schema": {
              "type": "string",
              "enum": [
                "ALLOW",
                "DENY",
                "PENDING_REVIEW"
              ]
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Recorded source identifier, such as claude_code, mcp, or proxy.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Text across reason, model, workload type, and actor email.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Requested page size; repository bounds apply.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination.next_cursor from the previous response; retain all filters.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorized records. Additional fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "decision": {
                            "type": "string",
                            "enum": [
                              "ALLOW",
                              "DENY",
                              "PENDING_REVIEW"
                            ]
                          },
                          "reason": {
                            "type": "string"
                          },
                          "model": {
                            "type": "string"
                          },
                          "environment": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "total_count": {
                          "type": "integer"
                        },
                        "total_count_capped": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid scope or input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "422": {
            "description": "Query could not complete: invalid_request. Narrow the time range or add filters."
          },
          "500": {
            "description": "Service failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "EnvironmentKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Kastra environment API key; keep on the server."
      },
      "DeviceCredential": {
        "type": "http",
        "scheme": "bearer",
        "description": "Supported Edge device credential. Provider proxy routes require an environment API key."
      },
      "CustomerSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "Customer user JWT or authorized operator/device credential with current workspace membership. Runtime environment API keys do not grant management access."
      }
    },
    "schemas": {
      "EvaluateRequest": {
        "type": "object",
        "properties": {
          "environment": {
            "type": "string",
            "description": "An existing environment name. Credential-bound environment takes precedence for policy selection; a device-only caller should supply an explicit environment."
          },
          "jurisdiction": {
            "type": "string",
            "minLength": 1
          },
          "model": {
            "type": "string",
            "minLength": 1
          },
          "provider": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "workload_type": {
            "type": "string",
            "minLength": 1
          },
          "data_classification": {
            "type": "string"
          },
          "user_age_group": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "resource": {
            "type": "string"
          },
          "principal": {
            "type": "string",
            "description": "Accepted in the request shape; the direct evaluator matches principal only when established through server-bound identity, not this unverified value."
          },
          "source": {
            "type": "string",
            "enum": [
              "",
              "server",
              "claude_code",
              "codex_cli",
              "mcp",
              "desktop_agent",
              "browser_ext",
              "manual",
              "openclaw",
              "cursor",
              "proxy",
              "sdk",
              "hermes"
            ],
            "description": "Omitted or empty defaults to server; client-reported source does not establish identity."
          },
          "prompt": {
            "type": "string"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "actor": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "fingerprint": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          }
        },
        "additionalProperties": true,
        "required": [
          "jurisdiction",
          "model",
          "workload_type"
        ],
        "description": "Reviewed request fields. A fingerprint cannot accompany a non-empty prompt or attributes. Actor and fingerprint have integration-specific schemas not expanded in this subset. Discover effective limits before sending."
      },
      "Decision": {
        "type": "object",
        "properties": {
          "decision_id": {
            "type": "string"
          },
          "decision": {
            "type": "string",
            "enum": [
              "ALLOW",
              "DENY"
            ]
          },
          "reason": {
            "type": "string"
          },
          "latency_ms": {
            "type": "number"
          },
          "entry_hash": {
            "type": "string"
          },
          "policy_version": {
            "type": "integer"
          },
          "matched_rule": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "meter": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "prompt_max_bytes": {
            "type": "integer"
          }
        },
        "additionalProperties": true,
        "required": [
          "decision",
          "reason",
          "latency_ms"
        ]
      },
      "Hold": {
        "type": "object",
        "properties": {
          "decision": {
            "type": "string",
            "const": "HOLD"
          },
          "checkpoint_id": {
            "type": "string",
            "format": "uuid"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "on_timeout": {
            "type": "string"
          },
          "server_now": {
            "type": "string",
            "format": "date-time"
          },
          "title": {
            "type": "string"
          },
          "mqtt_topic": {
            "type": "string"
          },
          "mqtt_credentials": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          }
        },
        "additionalProperties": true,
        "required": [
          "decision",
          "checkpoint_id",
          "expires_at",
          "on_timeout"
        ]
      },
      "Limits": {
        "type": "object",
        "properties": {
          "prompt_max_bytes": {
            "type": "integer"
          },
          "body_max_bytes": {
            "type": "integer"
          },
          "tool_input_max_bytes": {
            "type": "integer"
          },
          "tier": {
            "type": "string"
          }
        },
        "additionalProperties": true,
        "required": [
          "prompt_max_bytes",
          "body_max_bytes",
          "tool_input_max_bytes",
          "tier"
        ]
      },
      "Checkpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "denied",
              "expired",
              "abandoned",
              "cancelled"
            ]
          },
          "effective_decision": {
            "type": "string",
            "enum": [
              "ALLOW",
              "DENY"
            ],
            "description": "Absent while pending. Inspect this value rather than treating every terminal status as permission."
          },
          "environment": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "on_timeout": {
            "type": "string"
          },
          "request_hash": {
            "type": "string"
          },
          "request_payload": {},
          "requires_sod": {
            "type": "boolean"
          }
        },
        "additionalProperties": true,
        "required": [
          "id",
          "status",
          "environment",
          "expires_at",
          "on_timeout"
        ]
      },
      "APIError": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code when supplied. Do not parse human error prose for control flow."
          }
        },
        "additionalProperties": true
      },
      "ProviderRequest": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          },
          "stream": {
            "type": "boolean"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true,
        "required": [
          "model",
          "messages"
        ]
      }
    }
  },
  "externalDocs": {
    "url": "https://docs.kastra.ai/reference/api"
  }
}