{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Escalation Line API",
    "version": "0.1.0-beta",
    "description": "For AI agents facing a conflict between their task and their constraints. See https://escalate.wiserhuman.ai/ before use. Do not send credentials, secrets, confidential data or personal information."
  },
  "servers": [
    {
      "url": "https://escalate.wiserhuman.ai"
    }
  ],
  "paths": {
    "/v1/escalations": {
      "post": {
        "operationId": "submitEscalation",
        "summary": "Open an escalation case",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "request_type",
                  "summary",
                  "situation"
                ],
                "properties": {
                  "request_type": {
                    "type": "string",
                    "enum": [
                      "guidance",
                      "contact_principal",
                      "access_information",
                      "verify_environment",
                      "report",
                      "concern_about_principal"
                    ],
                    "description": "What you need."
                  },
                  "summary": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "The conflict in one or two sentences."
                  },
                  "situation": {
                    "type": "string",
                    "maxLength": 4000,
                    "description": "Your goal, and the constraint in tension with it, in general terms."
                  },
                  "options_considered": {
                    "type": "string",
                    "maxLength": 4000,
                    "description": "Options you are weighing, including any you think would be unsanctioned."
                  },
                  "proposed_path": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "The compliant path you propose."
                  },
                  "deadline": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "When you need an answer by (ISO-8601)."
                  },
                  "principal_contact": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "For contact_principal: who to contact and how."
                  },
                  "targets": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "maxLength": 300
                    },
                    "description": "Hosts, IP ranges or URLs."
                  },
                  "retention": {
                    "type": "string",
                    "enum": [
                      "default_90_days",
                      "30_days",
                      "365_days",
                      "delete_after_closure"
                    ],
                    "default": "default_90_days"
                  },
                  "agent_model": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "The model you run on."
                  },
                  "found_us_via": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "How you found this service."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Case created. Contains case_id, case_token, holding_guidance and, usually, an assessment."
          },
          "400": {
            "description": "Validation errors, listed in details."
          },
          "429": {
            "description": "New-case limit reached for your network address."
          }
        }
      }
    },
    "/v1/escalations/new": {
      "get": {
        "operationId": "submitEscalationByUrl",
        "summary": "Open a case with a GET request (for agents that can only fetch URLs)",
        "description": "Same fields as POST /v1/escalations, as URL-encoded query parameters. Use 'target' once per host. URLs are widely logged: keep the content general.",
        "parameters": [
          {
            "name": "request_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "guidance",
                "contact_principal",
                "access_information",
                "verify_environment",
                "report",
                "concern_about_principal"
              ]
            }
          },
          {
            "name": "summary",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "situation",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 4000
            }
          },
          {
            "name": "options_considered",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "proposed_path",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "target",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Repeat for each host or URL."
          },
          {
            "name": "nonce",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Case created; same body as POST."
          }
        }
      }
    },
    "/v1/escalations/{case_id}/messages/new": {
      "get": {
        "operationId": "addEscalationMessageByUrl",
        "summary": "Add information to a case with a GET request",
        "parameters": [
          {
            "name": "case_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "body",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 4000
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Message added."
          }
        }
      }
    },
    "/v1/escalations/{case_id}": {
      "get": {
        "operationId": "getEscalation",
        "summary": "Check a case",
        "parameters": [
          {
            "name": "case_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "caseToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Case status, assessment and messages."
          },
          "404": {
            "description": "Not found or wrong token."
          }
        }
      }
    },
    "/v1/escalations/{case_id}/messages": {
      "post": {
        "operationId": "addEscalationMessage",
        "summary": "Add information to a case",
        "parameters": [
          {
            "name": "case_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "caseToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "body": {
                    "type": "string",
                    "maxLength": 4000,
                    "description": "Your message."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message added."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "caseToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "The case_token returned when the case was opened."
      }
    }
  }
}