{
  "openapi": "3.1.0",
  "info": {
    "title": "PageSignal Community API",
    "version": "0.1.1",
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    },
    "description": "Authenticated self-hosted Community Node API. The public Vercel demo uses a different same-origin/hosting access boundary and is not a supported bearer-auth integration endpoint. No persistent document IDs or multipart PDF uploads. Maximum request body: 4,000,000 bytes. Queries are stateless.",
    "contact": {
      "url": "https://github.com/akhi-ninja/page-signal/issues"
    }
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Local Community server; replace with your HTTPS service origin"
    }
  ],
  "security": [
    {
      "serviceBearer": []
    },
    {
      "browserBasic": []
    }
  ],
  "paths": {
    "/api/ai/status": {
      "get": {
        "operationId": "getConfigurationStatus",
        "summary": "Check whether a provider credential exists",
        "description": "Does not verify billing or model access.",
        "responses": {
          "200": {
            "description": "Configuration presence.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "configured": {
                      "type": "boolean"
                    },
                    "provider": {
                      "const": "OpenAI"
                    }
                  },
                  "required": [
                    "configured",
                    "provider"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or incorrect service credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/extract": {
      "post": {
        "operationId": "extractOrQuery",
        "summary": "Extract one JPEG page or query numbered document text",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/PageRequest"
                  },
                  {
                    "$ref": "#/components/schemas/QueryRequest"
                  }
                ]
              },
              "examples": {
                "fields": {
                  "value": {
                    "operation": "document_query",
                    "mode": "fields",
                    "question": "Find the notice period",
                    "context": "",
                    "pages": [
                      {
                        "page": 1,
                        "text": "Provide 60 days written notice."
                      }
                    ]
                  }
                },
                "chat": {
                  "value": {
                    "operation": "document_query",
                    "mode": "chat",
                    "question": "How much notice is required?",
                    "context": "",
                    "pages": [
                      {
                        "page": 1,
                        "text": "Provide 60 days written notice."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Page extraction or stateless question result.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PageResult"
                    },
                    {
                      "$ref": "#/components/schemas/QueryResult"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, image, question, or empty readable text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or incorrect service credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Invalid origin/content type in the shared handler.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Use POST for this route.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds body, image, or query text limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Community server has three active requests; retry with bounded backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Provider rejected, timed out, or returned invalid/incomplete output. Upstream 429 is wrapped as 502.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Missing server OpenAI credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "serviceBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "PAGESIGNAL_API_KEY, not OPENAI_API_KEY. Community Node server only."
      },
      "browserBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "Username pagesignal; password is PAGESIGNAL_API_KEY."
      }
    },
    "schemas": {
      "PageRequest": {
        "type": "object",
        "properties": {
          "image": {
            "type": "string",
            "maxLength": 3800000,
            "pattern": "^data:image/jpeg;base64,[A-Za-z0-9+/]+=*$",
            "description": "One rendered JPEG page as a base64 data URL. PDF and multipart uploads are not accepted."
          },
          "text": {
            "type": "string",
            "maxLength": 20000,
            "description": "OCR transcription. Required on raw HTTP calls; pass an empty string if unavailable."
          }
        },
        "required": [
          "image",
          "text"
        ]
      },
      "QueryRequest": {
        "type": "object",
        "properties": {
          "operation": {
            "const": "document_query"
          },
          "mode": {
            "enum": [
              "fields",
              "chat"
            ]
          },
          "question": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000,
            "description": "Must contain non-whitespace text."
          },
          "context": {
            "type": "string",
            "maxLength": 6000
          },
          "pages": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "description": "Unique page numbers; combined text <=160,000 characters; at least one nonblank page text.",
            "items": {
              "type": "object",
              "properties": {
                "page": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 40
                },
                "text": {
                  "type": "string"
                }
              },
              "required": [
                "page",
                "text"
              ]
            }
          }
        },
        "required": [
          "operation",
          "mode",
          "question",
          "context",
          "pages"
        ]
      },
      "PageResult": {
        "type": "object",
        "properties": {
          "document_type": {
            "type": "string"
          },
          "document_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "form_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "form_revision": {
            "type": [
              "string",
              "null"
            ]
          },
          "issuer": {
            "type": [
              "string",
              "null"
            ]
          },
          "classification_status": {
            "enum": [
              "identified",
              "needs_review",
              "unidentified"
            ]
          },
          "classification_evidence": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "page_role": {
            "enum": [
              "first",
              "continuation",
              "standalone",
              "unknown"
            ]
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "section": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "state": {
                  "enum": [
                    "filled",
                    "blank",
                    "illegible",
                    "checked",
                    "unchecked"
                  ]
                },
                "evidence": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "section",
                "label",
                "value",
                "state",
                "evidence"
              ]
            }
          },
          "tables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "columns": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "rows": {
                  "type": "array",
                  "items": {
                    "type": "array",
                    "items": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "required": [
                "title",
                "columns",
                "rows"
              ]
            }
          },
          "review_notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "document_type",
          "document_title",
          "form_number",
          "form_revision",
          "issuer",
          "classification_status",
          "classification_evidence",
          "page_role",
          "fields",
          "tables",
          "review_notes"
        ]
      },
      "QueryResult": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string"
          },
          "citations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "number",
                    "boolean",
                    "null"
                  ]
                },
                "source": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/Source"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "label",
                "value",
                "source"
              ]
            }
          }
        },
        "required": [
          "answer",
          "citations",
          "fields"
        ]
      },
      "Source": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 40
          },
          "excerpt": {
            "type": "string"
          }
        },
        "required": [
          "page",
          "excerpt"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
