{
  "openapi": "3.1.0",
  "info": {
    "title": "Document Services API",
    "version": "1.0.0",
    "description": "Handles document intake for cases and applications: virus scanning, document-type classification, sensitivity labeling (CUI / Privacy), and text extraction. Extracted text carries page references so AI answers can cite the exact page they came from.\n\nReference design by Iron Brick LLC. Not an official government system; endpoints and data models are adapted to each agency's systems of record during implementation.",
    "contact": {
      "name": "Iron Brick LLC",
      "email": "info@ironbrick.us",
      "url": "https://dev.ironbrick.us"
    }
  },
  "servers": [
    {
      "url": "https://dev.ironbrick.us/sandbox/documents/v1",
      "description": "Iron Brick sandbox (synthetic data; free developer account)"
    },
    {
      "url": "https://{agency-gateway}/documents/v1",
      "description": "Agency deployment (behind the agency API gateway)"
    }
  ],
  "security": [
    {
      "oauth2": [
        "documents:read",
        "documents:write"
      ]
    }
  ],
  "paths": {
    "/documents": {
      "post": {
        "operationId": "uploadDocument",
        "summary": "Upload a document",
        "tags": [
          "Documents"
        ],
        "description": "Multipart upload. The document is scanned before it becomes `available`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "caseId": {
                    "type": "string",
                    "description": "Optional case to link to."
                  },
                  "category": {
                    "type": "string",
                    "example": "supporting_evidence"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Document accepted for scanning",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Business rule violation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documents/{documentId}": {
      "get": {
        "operationId": "getDocument",
        "summary": "Get document metadata",
        "tags": [
          "Documents"
        ],
        "parameters": [
          {
            "name": "documentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Document identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Document metadata",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documents/{documentId}/content": {
      "get": {
        "operationId": "downloadDocument",
        "summary": "Download document content",
        "tags": [
          "Documents"
        ],
        "description": "Returns a short-lived signed URL. Every download is written to the audit log.",
        "parameters": [
          {
            "name": "documentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Document identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Signed download URL",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documents/{documentId}/text": {
      "get": {
        "operationId": "getDocumentText",
        "summary": "Get extracted text",
        "tags": [
          "Documents"
        ],
        "description": "Page-level text for search and AI retrieval, with page numbers for citations.",
        "parameters": [
          {
            "name": "documentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Document identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Extracted text",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documentId": {
                      "type": "string"
                    },
                    "pages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "page": {
                            "type": "integer",
                            "example": 1
                          },
                          "text": {
                            "type": "string",
                            "example": "RESIDENTIAL LEASE AGREEMENT ..."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 client credentials for system-to-system calls. Agency deployments federate with the agency identity provider (PIV/CAC-backed for user-delegated access).",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://dev.ironbrick.us/oauth/token",
            "scopes": {
              "documents:read": "Read documents and extracted text",
              "documents:write": "Upload documents"
            }
          }
        }
      }
    },
    "headers": {
      "X-Request-Id": {
        "description": "Unique request identifier; include it when contacting support.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "validation_error"
          },
          "message": {
            "type": "string",
            "example": "status must be one of: received, in_review, decided, closed"
          },
          "requestId": {
            "type": "string",
            "format": "uuid",
            "example": "3f1c9a52-7c1e-4f3e-9d2a-0b8e5f6a1c44"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Page": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "example": "eyJvZmZzZXQiOjUwfQ"
          },
          "limit": {
            "type": "integer",
            "example": 50
          }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "documentId": {
            "type": "string",
            "example": "DOC-551920"
          },
          "fileName": {
            "type": "string",
            "example": "lease-agreement.pdf"
          },
          "mediaType": {
            "type": "string",
            "example": "application/pdf"
          },
          "sizeBytes": {
            "type": "integer",
            "example": 284113
          },
          "sha256": {
            "type": "string",
            "example": "9b1f0c4e3a6d..."
          },
          "classification": {
            "type": "string",
            "nullable": true,
            "example": "proof_of_residence"
          },
          "sensitivity": {
            "type": "string",
            "enum": [
              "public",
              "cui",
              "cui_privacy"
            ],
            "example": "cui_privacy"
          },
          "status": {
            "type": "string",
            "enum": [
              "uploaded",
              "scanning",
              "available",
              "quarantined"
            ],
            "example": "available"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}