{
  "openapi": "3.0.3",
  "info": {
    "title": "Praesidia preparation and checkpoint tools",
    "version": "1.0.0",
    "description": "Explicit registered HTTP preparation and readback only. No approve, resume, or arbitrary target dispatch operation is exposed. This schema does not itself enforce a tools host allowlist."
  },
  "servers": [
    {
      "url": "https://api.praesidia.ai"
    }
  ],
  "security": [
    {
      "personalCaller": []
    }
  ],
  "paths": {
    "/organizations/{orgId}/protected-actions/http/prepare": {
      "post": {
        "operationId": "preparePraesidiaHttpRequest",
        "summary": "Prepare a registered HTTP request for separate human approval; never dispatches it.",
        "parameters": [
          {
            "name": "orgId",
            "in": "path",
            "required": true,
            "description": "The organization where your personal caller has access.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrepareRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Owned durable checkpoint; retain all IDs and the exact request commitment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Checkpoint"
                }
              }
            }
          },
          "403": {
            "description": "Caller permission, feature, scope, or target access denied."
          }
        }
      }
    },
    "/organizations/{orgId}/protected-actions/http/checkpoints/{approvalId}": {
      "get": {
        "operationId": "readPraesidiaHttpCheckpoint",
        "summary": "Read your existing approval checkpoint and any committed outcome.",
        "parameters": [
          {
            "name": "orgId",
            "in": "path",
            "required": true,
            "description": "The organization where your personal caller has access.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "approvalId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fresh owned checkpoint state. This read does not approve or dispatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Checkpoint"
                }
              }
            }
          },
          "404": {
            "description": "Checkpoint unavailable for this requester and organization."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "personalCaller": {
        "type": "http",
        "scheme": "bearer",
        "description": "Configure in the platform credential store; do not embed in the schema. Requires real-user workflows.execute, agents:invoke, and proof.actions."
      }
    },
    "schemas": {
      "PrepareRequest": {
        "type": "object",
        "required": [
          "targetId",
          "body",
          "checkpoint",
          "description"
        ],
        "properties": {
          "targetId": {
            "type": "string",
            "maxLength": 128,
            "description": "Operator-registered target ID, never an arbitrary destination URL."
          },
          "body": {
            "type": "object",
            "additionalProperties": true,
            "description": "Exact JSON object to commit for human review."
          },
          "checkpoint": {
            "type": "object",
            "required": [
              "runtime",
              "threadId",
              "nodeId"
            ],
            "properties": {
              "runtime": {
                "type": "string",
                "enum": [
                  "custom"
                ],
                "default": "custom"
              },
              "threadId": {
                "type": "string",
                "maxLength": 256,
                "description": "Unique stable workflow run identifier; preserve across restart."
              },
              "nodeId": {
                "type": "string",
                "maxLength": 256
              }
            }
          },
          "description": {
            "type": "string",
            "maxLength": 1000
          },
          "expiresInHours": {
            "type": "integer",
            "minimum": 1,
            "maximum": 168,
            "default": 24
          }
        }
      },
      "Checkpoint": {
        "type": "object",
        "required": [
          "approvalId",
          "actionId",
          "requestCommitment",
          "status",
          "expiresAt"
        ],
        "properties": {
          "approvalId": {
            "type": "string",
            "format": "uuid"
          },
          "actionId": {
            "type": "string"
          },
          "requestCommitment": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "status": {
            "type": "string",
            "description": "Live approval status; pending is not permission to dispatch."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "consumedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "approverId": {
            "type": "string",
            "nullable": true
          },
          "closure": {
            "type": "string",
            "nullable": true
          },
          "evidenceGrade": {
            "type": "string",
            "enum": [
              "A",
              "C"
            ]
          },
          "result": {
            "nullable": true,
            "description": "The committed target result when present; no result must not be mistaken for success."
          }
        }
      }
    }
  }
}