{
  "openapi": "3.1.0",
  "info": {
    "title": "GetRatchet API",
    "version": "1.0.0",
    "description": "Versioned API for runs, durable tools, recovery, and developer-owned workers."
  },
  "servers": [
    {
      "url": "https://getratchet.waelfz.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Use an organization API key with the scope required by the operation."
      }
    }
  },
  "paths": {
    "/api/v1/audit": {
      "get": {
        "operationId": "get_audit",
        "summary": "List organization audit events",
        "tags": [
          "Audit"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "targetType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "targetId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          }
        ],
        "description": "Requires an administrator key. Results are scoped to the key's organization and omit payloads and secrets."
      }
    },
    "/api/v1/endpoints": {
      "get": {
        "operationId": "get_endpoints",
        "summary": "List endpoint policies",
        "tags": [
          "Endpoints"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        }
      }
    },
    "/api/v1/endpoints/{id}/pause": {
      "post": {
        "operationId": "post_endpoints_id_pause",
        "summary": "Pause an endpoint",
        "tags": [
          "Endpoints"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/endpoints/{id}/policy": {
      "get": {
        "operationId": "get_endpoints_id_policy",
        "summary": "Get endpoint policy",
        "tags": [
          "Endpoints"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "put": {
        "operationId": "put_endpoints_id_policy",
        "summary": "Update endpoint policy",
        "tags": [
          "Endpoints"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/endpoints/{id}/resume": {
      "post": {
        "operationId": "post_endpoints_id_resume",
        "summary": "Resume an endpoint",
        "tags": [
          "Endpoints"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/executions/{id}": {
      "patch": {
        "operationId": "patch_executions_id",
        "summary": "Finish a synchronous execution",
        "tags": [
          "Executions"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/exports/audit": {
      "get": {
        "operationId": "get_exports_audit",
        "summary": "Export a page of audit events",
        "tags": [
          "Exports"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "targetType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "targetId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          }
        ],
        "description": "Requires an administrator key. Each JSON download contains at most 100 organization audit events and a nextCursor for the next page."
      }
    },
    "/api/v1/exports/runs": {
      "get": {
        "operationId": "get_exports_runs",
        "summary": "Export a page of redacted run summaries",
        "tags": [
          "Exports"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Run name or ID substring",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "runId",
            "in": "query",
            "required": false,
            "description": "Exact run ID",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          },
          {
            "name": "projectId",
            "in": "query",
            "required": false,
            "description": "Exact project ID",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "environmentId",
            "in": "query",
            "required": false,
            "description": "Exact environment ID",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Run status",
            "schema": {
              "type": "string",
              "enum": [
                "RUNNING",
                "SUCCEEDED",
                "FAILED"
              ]
            }
          },
          {
            "name": "isTest",
            "in": "query",
            "required": false,
            "description": "Filter synthetic test runs",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": false,
            "description": "Service name substring",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "tool",
            "in": "query",
            "required": false,
            "description": "Tool name substring",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "handlerVersion",
            "in": "query",
            "required": false,
            "description": "Exact handler version",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "idempotencyKey",
            "in": "query",
            "required": false,
            "description": "Exact step idempotency key",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Inclusive ISO date or timestamp",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Inclusive ISO date or timestamp",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Last run ID from the previous page",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size; default 25",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "description": "Requires an administrator key. Each JSON download contains at most 100 run summaries and a nextCursor for the next page; names and tool payloads are excluded."
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "get_health",
        "summary": "Get organization queue, worker, and circuit health",
        "tags": [
          "Health"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        }
      }
    },
    "/api/v1/jobs/{id}/cancel": {
      "post": {
        "operationId": "post_jobs_id_cancel",
        "summary": "Cancel a durable job",
        "tags": [
          "Jobs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "202": {
            "description": "Accepted or pending"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/recovery": {
      "get": {
        "operationId": "get_recovery",
        "summary": "List bulk recovery plans",
        "tags": [
          "Recovery"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        }
      },
      "post": {
        "operationId": "post_recovery",
        "summary": "Create a bulk recovery plan",
        "tags": [
          "Recovery"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/recovery/{id}": {
      "delete": {
        "operationId": "delete_recovery_id",
        "summary": "Cancel a bulk recovery plan",
        "tags": [
          "Recovery"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "get": {
        "operationId": "get_recovery_id",
        "summary": "Get a bulk recovery plan",
        "tags": [
          "Recovery"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/runs": {
      "get": {
        "operationId": "get_runs",
        "summary": "List recent runs",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Run name or ID substring",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "runId",
            "in": "query",
            "required": false,
            "description": "Exact run ID",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          },
          {
            "name": "projectId",
            "in": "query",
            "required": false,
            "description": "Exact project ID",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "environmentId",
            "in": "query",
            "required": false,
            "description": "Exact environment ID",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Run status",
            "schema": {
              "type": "string",
              "enum": [
                "RUNNING",
                "SUCCEEDED",
                "FAILED"
              ]
            }
          },
          {
            "name": "isTest",
            "in": "query",
            "required": false,
            "description": "Filter synthetic test runs",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": false,
            "description": "Service name substring",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "tool",
            "in": "query",
            "required": false,
            "description": "Tool name substring",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "handlerVersion",
            "in": "query",
            "required": false,
            "description": "Exact handler version",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "idempotencyKey",
            "in": "query",
            "required": false,
            "description": "Exact step idempotency key",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Inclusive ISO date or timestamp",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Inclusive ISO date or timestamp",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Last run ID from the previous page",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size; default 25",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ]
      },
      "post": {
        "operationId": "post_runs",
        "summary": "Start a run",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "201": {
            "description": "Created"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "projectId": {
                    "type": "string",
                    "description": "Supply with environmentId"
                  },
                  "environmentId": {
                    "type": "string",
                    "description": "Supply with projectId"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "name": "customer-onboarding"
              }
            }
          }
        }
      }
    },
    "/api/v1/runs/{id}": {
      "get": {
        "operationId": "get_runs_id",
        "summary": "Get a run and its steps",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "patch": {
        "operationId": "patch_runs_id",
        "summary": "Finish a run",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "SUCCEEDED",
                      "FAILED"
                    ]
                  }
                },
                "required": [
                  "status"
                ],
                "additionalProperties": true
              },
              "example": {
                "status": "SUCCEEDED"
              }
            }
          }
        }
      }
    },
    "/api/v1/runs/{id}/enqueue": {
      "post": {
        "operationId": "post_runs_id_enqueue",
        "summary": "Enqueue a durable tool call",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "202": {
            "description": "Accepted or pending"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "endpoint": {
                    "type": "string"
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 255
                  },
                  "input": {
                    "description": "Any JSON value up to 64 KiB; validated against a published contract when present."
                  },
                  "contractVersion": {
                    "type": "string"
                  },
                  "timeoutMs": {
                    "type": "integer",
                    "minimum": 100
                  },
                  "maxAttempts": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10
                  },
                  "after": {
                    "type": "object",
                    "properties": {
                      "stepId": {
                        "type": "string"
                      },
                      "on": {
                        "type": "string",
                        "enum": [
                          "SUCCEEDED",
                          "FAILED"
                        ]
                      }
                    },
                    "required": [
                      "stepId",
                      "on"
                    ],
                    "additionalProperties": false,
                    "description": "Wait for an earlier durable step in the same run; FAILED schedules a fallback."
                  }
                },
                "required": [
                  "name",
                  "version",
                  "endpoint",
                  "idempotencyKey",
                  "input"
                ],
                "additionalProperties": true
              },
              "example": {
                "name": "send_welcome_email",
                "version": "1",
                "endpoint": "email",
                "idempotencyKey": "welcome:customer-42",
                "input": {
                  "customerId": "customer-42"
                }
              }
            }
          }
        },
        "description": "The idempotency key is unique per organization. Reuse it for safe transport retries; the handler still needs destination-side idempotency for irreversible effects."
      }
    },
    "/api/v1/runs/{id}/steps": {
      "post": {
        "operationId": "post_runs_id_steps",
        "summary": "Record a synchronous step",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/steps/{id}/attempts": {
      "post": {
        "operationId": "post_steps_id_attempts",
        "summary": "Start another synchronous attempt",
        "tags": [
          "Steps"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/steps/{id}/replay": {
      "get": {
        "operationId": "get_steps_id_replay",
        "summary": "Preview replay risks",
        "tags": [
          "Steps"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "operationId": "post_steps_id_replay",
        "summary": "Replay a step",
        "tags": [
          "Steps"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "acknowledgeDuplicateRisk": {
                    "type": "boolean"
                  },
                  "maxAttempts": {
                    "type": "integer"
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "acknowledgeDuplicateRisk",
                  "maxAttempts",
                  "reason"
                ],
                "additionalProperties": true
              },
              "example": {
                "acknowledgeDuplicateRisk": true,
                "maxAttempts": 1,
                "reason": "Provider incident resolved"
              }
            }
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "get_tools",
        "summary": "List published tool contracts",
        "tags": [
          "Tools"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        }
      },
      "post": {
        "operationId": "post_tools",
        "summary": "Publish a tool contract",
        "tags": [
          "Tools"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/test": {
      "post": {
        "operationId": "post_tools_test",
        "summary": "Queue one rate-limited synthetic test of a SAFE tool contract",
        "tags": [
          "Tools"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "202": {
            "description": "Accepted or pending"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "contractVersion": {
                    "type": "string"
                  },
                  "projectId": {
                    "type": "string"
                  },
                  "environmentId": {
                    "type": "string"
                  },
                  "input": {
                    "description": "Any JSON value up to 64 KiB that matches the selected contract."
                  }
                },
                "required": [
                  "name",
                  "contractVersion",
                  "projectId",
                  "environmentId",
                  "input"
                ],
                "additionalProperties": true
              },
              "example": {
                "name": "classify_sample",
                "contractVersion": "1",
                "projectId": "project-id",
                "environmentId": "environment-id",
                "input": {
                  "text": "sample"
                }
              }
            }
          }
        },
        "description": "Requires administrator access. Only contracts marked SAFE can be tested. Creates a separate isTest run with one attempt, limited to 10 requests per organization per hour. A developer-owned worker must register the exact handler version."
      }
    },
    "/api/v1/workers/claim": {
      "post": {
        "operationId": "post_workers_claim",
        "summary": "Claim the next due job",
        "tags": [
          "Workers"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "204": {
            "description": "No due job"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workerId": {
                    "type": "string"
                  }
                },
                "required": [
                  "workerId"
                ],
                "additionalProperties": true
              },
              "example": {
                "workerId": "worker-example-001"
              }
            }
          }
        },
        "description": "Requires a WORKER scoped key. Worker IDs are bound to their registering API key."
      }
    },
    "/api/v1/workers/jobs/{id}/heartbeat": {
      "post": {
        "operationId": "post_workers_jobs_id_heartbeat",
        "summary": "Renew a job lease",
        "tags": [
          "Workers"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workerId": {
                    "type": "string"
                  },
                  "leaseToken": {
                    "type": "integer"
                  }
                },
                "required": [
                  "workerId",
                  "leaseToken"
                ],
                "additionalProperties": true
              },
              "example": {
                "workerId": "worker-example-001",
                "leaseToken": 3
              }
            }
          }
        },
        "description": "Requires a WORKER scoped key. Worker IDs are bound to their registering API key."
      }
    },
    "/api/v1/workers/jobs/{id}/report": {
      "post": {
        "operationId": "post_workers_jobs_id_report",
        "summary": "Report a fenced job result",
        "tags": [
          "Workers"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workerId": {
                    "type": "string"
                  },
                  "leaseToken": {
                    "type": "integer"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "SUCCEEDED",
                      "FAILED"
                    ]
                  },
                  "output": {
                    "description": "Any JSON value up to 64 KiB on success."
                  },
                  "error": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "retryable": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "workerId",
                  "leaseToken",
                  "status"
                ],
                "additionalProperties": true
              },
              "example": {
                "workerId": "worker-example-001",
                "leaseToken": 3,
                "status": "SUCCEEDED",
                "output": {
                  "providerMessageId": "msg_example"
                }
              }
            }
          }
        },
        "description": "Requires a WORKER scoped key. Worker IDs are bound to their registering API key."
      }
    },
    "/api/v1/workers/register": {
      "post": {
        "operationId": "post_workers_register",
        "summary": "Register a worker and handler versions",
        "tags": [
          "Workers"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workerId": {
                    "type": "string"
                  },
                  "capacity": {
                    "type": "integer"
                  },
                  "handlers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "version"
                      ],
                      "additionalProperties": true
                    }
                  }
                },
                "required": [
                  "workerId",
                  "capacity",
                  "handlers"
                ],
                "additionalProperties": true
              },
              "example": {
                "workerId": "worker-example-001",
                "capacity": 4,
                "handlers": [
                  {
                    "name": "send_welcome_email",
                    "version": "1"
                  }
                ]
              }
            }
          }
        },
        "description": "Requires a WORKER scoped key. Worker IDs are bound to their registering API key."
      }
    }
  }
}