{
  "openapi": "3.1.0",
  "info": {
    "title": "PAM-E reference handoff API",
    "version": "1.0.0",
    "description": "Local reference service for PAM-E escalation handoffs. Offline by default; no authentication, not for production use."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/v1/handoffs": {
      "post": {
        "summary": "Create a handoff",
        "description": "Builds a signed PAM-E handoff and a standard PAM handoff from an L1 conversation, with a readable brief, a readiness check and audit ids.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "messages": {
                    "type": "array",
                    "minItems": 2,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "customer",
                            "agent",
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string",
                          "maxLength": 4000
                        }
                      }
                    }
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "budget": {
                    "type": "integer",
                    "minimum": 256,
                    "maximum": 32768,
                    "default": 1024
                  },
                  "checks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 12
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Both handoffs, the brief and the readiness check."
          },
          "400": {
            "description": "Invalid request; the body explains why."
          }
        }
      }
    },
    "/v1/verify": {
      "post": {
        "summary": "Verify a handoff",
        "description": "Checks the envelope digest, PAM's integrity hashes and (for PAM-E) the Ed25519 signature.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "artifact"
                ],
                "properties": {
                  "artifact": {
                    "type": "object",
                    "required": [
                      "payload",
                      "digest"
                    ],
                    "description": "A handoff envelope as returned in handoffs.<method>.artifact"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "valid, the layer that decided, and the reason."
          },
          "400": {
            "description": "Invalid request; the body explains why."
          }
        }
      }
    },
    "/v1/brief": {
      "post": {
        "summary": "Read a PAM-E handoff",
        "description": "Verifies a PAM-E handoff and returns its readable brief.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "artifact"
                ],
                "properties": {
                  "artifact": {
                    "type": "object",
                    "required": [
                      "payload",
                      "digest"
                    ],
                    "description": "A handoff envelope as returned in handoffs.<method>.artifact"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The brief, in sections."
          },
          "400": {
            "description": "Invalid request; the body explains why."
          }
        }
      }
    },
    "/v1/readiness": {
      "post": {
        "summary": "Check readiness before escalating",
        "description": "Flags what the next agent would be missing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "messages": {
                    "type": "array",
                    "minItems": 2,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "customer",
                            "agent",
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string",
                          "maxLength": 4000
                        }
                      }
                    }
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "budget": {
                    "type": "integer",
                    "minimum": 256,
                    "maximum": 32768,
                    "default": 1024
                  },
                  "checks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 12
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Score, level, issues and strengths."
          },
          "400": {
            "description": "Invalid request; the body explains why."
          }
        }
      }
    },
    "/v1/webhooks/helpdesk": {
      "post": {
        "summary": "Helpdesk escalation webhook",
        "description": "Accepts a generic ticket.escalated event and returns the same result as /v1/handoffs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ticket"
                ],
                "properties": {
                  "event": {
                    "type": "string"
                  },
                  "ticket": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "As /v1/handoffs."
          },
          "400": {
            "description": "Invalid request; the body explains why."
          }
        }
      }
    }
  }
}