{
  "openapi": "3.1.0",
  "info": {
    "title": "PolDex API",
    "version": "2026.05.0",
    "description": "Vertical insurance document extraction API for developers, workflow tools, and AI agents. Commercial insurance schemas are live first, with evidence-backed JSON and machine-readable agent discovery."
  },
  "externalDocs": {
    "description": "PolDex docs",
    "url": "https://poldex-web.pages.dev/docs"
  },
  "servers": [
    {
      "url": "https://poldex-api.plain-water-cd0f.workers.dev",
      "description": "Production API"
    }
  ],
  "tags": [
    { "name": "Agent Discovery" },
    { "name": "Initialize" },
    { "name": "Schemas" },
    { "name": "Credits" },
    { "name": "Extraction" },
    { "name": "Processor" },
    { "name": "Connectors" },
    { "name": "Health" }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Health"],
        "summary": "Liveness check",
        "operationId": "health",
        "security": [],
        "responses": {
          "200": {
            "description": "API process is alive.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          }
        }
      }
    },
    "/ready": {
      "get": {
        "tags": ["Health"],
        "summary": "Readiness check",
        "operationId": "ready",
        "security": [],
        "responses": {
          "200": {
            "description": "API dependencies are ready.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          },
          "503": {
            "description": "Dependency not ready.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/initialize": {
      "post": {
        "tags": ["Initialize", "Agent Discovery"],
        "summary": "Create a PolDex customer and issue an API key",
        "operationId": "initialize",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/InitializeRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Customer initialized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InitializeResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/schemas": {
      "get": {
        "tags": ["Schemas", "Agent Discovery"],
        "summary": "List supported extraction schemas",
        "operationId": "listSchemas",
        "security": [],
        "responses": {
          "200": {
            "description": "Supported commercial insurance schemas.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SchemaListResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/schemas/{schema_id}": {
      "get": {
        "tags": ["Schemas", "Agent Discovery"],
        "summary": "Get schema details",
        "operationId": "getSchema",
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/SchemaId" }
        ],
        "responses": {
          "200": {
            "description": "Schema contract with fields and example output.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SchemaDetailResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/credits": {
      "get": {
        "tags": ["Credits"],
        "summary": "Get credit balance",
        "operationId": "getCredits",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Credit balance and recent ledger events.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreditsResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/extract": {
      "post": {
        "tags": ["Extraction"],
        "summary": "Submit an async extraction job",
        "operationId": "createExtractionJob",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1 },
            "description": "Unique key per create request. Reuse is safe only with the same payload."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ExtractionRequest" }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job accepted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExtractAcceptedResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/jobs/{job_id}": {
      "get": {
        "tags": ["Extraction"],
        "summary": "Get job status and result",
        "operationId": "getJob",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Job lifecycle status.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JobStatusResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/batches/estimate": {
      "post": {
        "tags": ["Processor"],
        "summary": "Estimate processor batch cost",
        "operationId": "estimateBatch",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": { "$ref": "#/components/schemas/BatchSubmissionForm" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch estimate.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchEstimateResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/batches": {
      "post": {
        "tags": ["Processor"],
        "summary": "Create processor batch",
        "operationId": "createBatch",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": { "$ref": "#/components/schemas/BatchSubmissionForm" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch status after processing attempt.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchStatusResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/batches/{batch_id}": {
      "get": {
        "tags": ["Processor"],
        "summary": "Get processor batch status",
        "operationId": "getBatch",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/BatchId" }
        ],
        "responses": {
          "200": {
            "description": "Batch status and item states.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchStatusResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/batches/{batch_id}/downloads/{artifact}": {
      "get": {
        "tags": ["Processor"],
        "summary": "Download processor batch artifact",
        "operationId": "downloadBatchArtifact",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/BatchId" },
          {
            "name": "artifact",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["manifest.csv", "combined.csv", "combined.xlsx", "results.zip"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Artifact bytes.",
            "content": {
              "text/csv": { "schema": { "type": "string", "format": "binary" } },
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } },
              "application/zip": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/connector/events": {
      "get": {
        "tags": ["Connectors", "Agent Discovery"],
        "summary": "Poll completed or failed connector events",
        "operationId": "listConnectorEvents",
        "security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Cursor or timestamp returned by a prior call."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
          }
        ],
        "responses": {
          "200": {
            "description": "Connector events.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ConnectorEventsResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "parameters": {
      "SchemaId": {
        "name": "schema_id",
        "in": "path",
        "required": true,
        "schema": { "$ref": "#/components/schemas/SchemaId" }
      },
      "BatchId": {
        "name": "batch_id",
        "in": "path",
        "required": true,
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "Error": {
        "description": "Error response.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    },
    "schemas": {
      "SchemaId": {
        "type": "string",
        "enum": [
          "commercial_gl",
          "commercial_auto",
          "workers_comp",
          "umbrella_excess",
          "commercial_property",
          "professional_lines"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": { "type": "string", "examples": ["ok"] }
        }
      },
      "InitializeRequest": {
        "type": "object",
        "required": ["org_name", "contact_email", "intended_use", "path"],
        "properties": {
          "org_name": { "type": "string" },
          "contact_email": { "type": "string", "format": "email" },
          "intended_use": { "type": "string" },
          "path": { "type": "string", "enum": ["self_serve", "enterprise_preload"] },
          "prepaid_credits": { "type": "integer", "minimum": 0 },
          "amount_minor": { "type": "integer", "minimum": 0 },
          "currency": { "type": "string" },
          "metadata": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        }
      },
      "InitializeResponse": {
        "type": "object",
        "required": ["customer_id", "status", "key_delivery", "message", "payment_status"],
        "properties": {
          "customer_id": { "type": "string" },
          "status": { "type": "string", "enum": ["funded", "pending_enterprise", "pending_payment"] },
          "key_delivery": { "type": "string", "enum": ["email", "in_page_once"] },
          "message": { "type": "string" },
          "api_key": { "type": "string" },
          "payment_status": { "type": "string", "enum": ["succeeded", "pending", "failed", "not_applicable"] }
        }
      },
      "SchemaInfo": {
        "type": "object",
        "required": ["schema_id", "slug", "title", "version", "description", "supported_document_profiles", "required_fields", "proof_documents", "benchmark_documents", "status", "example_output"],
        "properties": {
          "schema_id": { "$ref": "#/components/schemas/SchemaId" },
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "version": { "type": "string" },
          "description": { "type": "string" },
          "supported_document_profiles": { "type": "array", "items": { "type": "string" } },
          "required_fields": { "type": "array", "items": { "type": "string" } },
          "proof_documents": { "type": "integer" },
          "benchmark_documents": { "type": "integer" },
          "status": { "type": "string", "enum": ["Done"] },
          "example_output": { "type": "object", "additionalProperties": true }
        }
      },
      "SchemaListResponse": {
        "type": "object",
        "required": ["schemas"],
        "properties": {
          "schemas": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SchemaInfo" }
          }
        }
      },
      "SchemaDetailResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/SchemaInfo" },
          {
            "type": "object",
            "required": ["fields", "proof_documents"],
            "properties": {
              "fields": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["name", "type", "required"],
                  "properties": {
                    "name": { "type": "string" },
                    "type": { "type": "string" },
                    "required": { "type": "boolean" }
                  }
                }
              },
              "proof_documents": {
                "type": "array",
                "items": { "type": "object", "additionalProperties": true }
              }
            }
          }
        ]
      },
      "ExtractionRequest": {
        "type": "object",
        "properties": {
          "document_url": { "type": "string", "format": "uri" },
          "upload_ref": { "type": "string" },
          "schema": { "$ref": "#/components/schemas/SchemaId" },
          "webhook_url": { "type": "string", "format": "uri" },
          "client_ref": { "type": "string" },
          "correlation": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        },
        "oneOf": [
          { "required": ["document_url"] },
          { "required": ["upload_ref"] }
        ]
      },
      "ExtractAcceptedResponse": {
        "type": "object",
        "required": ["job_id", "status", "idempotency_key", "created_at", "estimated_seconds", "credits_held", "poll_url"],
        "properties": {
          "job_id": { "type": "string" },
          "status": { "type": "string", "enum": ["queued"] },
          "idempotency_key": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "estimated_seconds": { "type": "integer" },
          "credits_held": { "type": "integer" },
          "poll_url": { "type": "string", "format": "uri" }
        }
      },
      "JobStatusResponse": {
        "type": "object",
        "required": ["job_id", "status", "schema_id", "schema_version", "created_at", "updated_at", "delete_status", "credits_held", "credits_captured", "result_available"],
        "properties": {
          "job_id": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "queued", "processing", "complete", "failed", "dlq", "cancelled"] },
          "schema_id": { "$ref": "#/components/schemas/SchemaId" },
          "schema_version": { "type": "string" },
          "client_ref": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "queued_at": { "type": "string", "format": "date-time" },
          "started_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": "string", "format": "date-time" },
          "failed_at": { "type": "string", "format": "date-time" },
          "failure_code": { "type": "string" },
          "failure_reason": { "type": "string" },
          "delete_status": { "type": "string" },
          "credits_held": { "type": "integer" },
          "credits_captured": { "type": "integer" },
          "result_available": { "type": "boolean" },
          "result": { "type": "object", "additionalProperties": true }
        }
      },
      "CreditsResponse": {
        "type": "object",
        "required": ["balance", "recent_events"],
        "properties": {
          "balance": {
            "type": "object",
            "required": ["total_credits", "held_credits", "available_credits", "currency", "as_of"],
            "properties": {
              "total_credits": { "type": "integer" },
              "held_credits": { "type": "integer" },
              "available_credits": { "type": "integer" },
              "currency": { "type": "string", "enum": ["credits"] },
              "as_of": { "type": "string", "format": "date-time" }
            }
          },
          "recent_events": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          }
        }
      },
      "BatchSubmissionForm": {
        "type": "object",
        "properties": {
          "schema": { "$ref": "#/components/schemas/SchemaId" },
          "files": {
            "type": "array",
            "items": { "type": "string", "format": "binary" }
          },
          "text_items": {
            "type": "string",
            "description": "JSON array of { name?: string, text: string }."
          },
          "url_items": {
            "type": "string",
            "description": "JSON array of { name?: string, document_url: string }."
          }
        }
      },
      "BatchEstimateResponse": {
        "type": "object",
        "required": ["schema_id", "item_count", "total_estimated_pages", "estimated_credits", "limits", "items", "note"],
        "properties": {
          "schema_id": { "$ref": "#/components/schemas/SchemaId" },
          "item_count": { "type": "integer" },
          "total_estimated_pages": { "type": "integer" },
          "estimated_credits": { "type": "integer" },
          "limits": { "type": "object", "additionalProperties": true },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "note": { "type": "string" }
        }
      },
      "BatchStatusResponse": {
        "type": "object",
        "required": ["batch_id", "customer_id", "schema_id", "status", "item_count", "completed_count", "failed_count", "total_estimated_pages", "estimated_credits", "credits_held", "credits_captured", "expires_at", "deleted_at", "created_at", "updated_at", "completed_at", "items"],
        "properties": {
          "batch_id": { "type": "string" },
          "customer_id": { "type": "string" },
          "schema_id": { "$ref": "#/components/schemas/SchemaId" },
          "status": { "type": "string", "enum": ["processing", "complete", "partial", "failed"] },
          "item_count": { "type": "integer" },
          "completed_count": { "type": "integer" },
          "failed_count": { "type": "integer" },
          "total_estimated_pages": { "type": "integer" },
          "estimated_credits": { "type": "integer" },
          "credits_held": { "type": "integer" },
          "credits_captured": { "type": "integer" },
          "expires_at": { "type": "string", "format": "date-time" },
          "deleted_at": { "type": ["string", "null"], "format": "date-time" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": ["string", "null"], "format": "date-time" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/BatchItemStatus" }
          }
        }
      },
      "BatchItemStatus": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "item_id": { "type": "string" },
          "source_type": { "type": "string", "enum": ["upload", "text", "url"] },
          "source_name": { "type": "string" },
          "status": { "type": "string", "enum": ["processing", "complete", "failed"] },
          "job_id": { "type": ["string", "null"] },
          "result_available": { "type": "boolean" },
          "result_links": { "type": ["object", "null"], "additionalProperties": true }
        }
      },
      "ConnectorEventsResponse": {
        "type": "object",
        "required": ["events", "next_cursor", "limit"],
        "properties": {
          "events": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ConnectorEvent" }
          },
          "next_cursor": { "type": ["string", "null"] },
          "limit": { "type": "integer" }
        }
      },
      "ConnectorEvent": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "event_id": { "type": "string" },
          "event_type": { "type": "string" },
          "source_type": { "type": "string", "enum": ["job", "batch_item", "intake_run"] },
          "source_id": { "type": "string" },
          "schema_id": { "$ref": "#/components/schemas/SchemaId" },
          "status": { "type": "string" },
          "result_available": { "type": "boolean" },
          "result_links": { "type": ["object", "null"], "additionalProperties": true }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "request_id": { "type": "string" },
              "job_id": { "type": "string" }
            }
          }
        }
      }
    }
  }
}