Documents API

Agents reason over a corpus of documents you upload. The Documents API lets you add policies, evidence, questionnaires, and custom frameworks to that corpus, list and filter them, and remove them. Uploaded documents are referenced by document_id in expert chat and workflows.

Method Endpoint Description
POST /v1/documents Upload a document
GET /v1/documents List / filter documents
DELETE /v1/documents/{document_id} Delete a document

All endpoints require authorization: YOUR_API_KEY.

Document types

Type Use Required extra fields
policy Policy/procedure text for coverage analysis —
evidence Artifacts proving a control is met, for audit readiness framework_id, control_id, expires_at
questionnaire Security questionnaires to answer or analyze —
custom_framework Your own control set, to map and reason against —

Upload a Document

POST /v1/documents

Send as multipart/form-data.

Field Type Required Description
file binary Yes File content to upload (PDF, PNG, TXT, etc.).
type string Yes One of policy, evidence, questionnaire, custom_framework.
framework_id string For evidence Framework this document relates to. Optional for other types.
control_id string For evidence Control this document provides evidence for. Optional for other types.
expires_at string (ISO 8601) For evidence When this document expires. Optional (omit for no expiry) for policy and questionnaire.

Example — policy

curl -X POST https://compliance.secberus.ai/v1/documents \
  -H "authorization: YOUR_API_KEY" \
  -F "file=@access-control-policy.pdf" \
  -F "type=policy"

Example — evidence

curl -X POST https://compliance.secberus.ai/v1/documents \
  -H "authorization: YOUR_API_KEY" \
  -F "file=@mfa-screenshot.png" \
  -F "type=evidence" \
  -F "framework_id=pci_dss_v4" \
  -F "control_id=8.4.2" \
  -F "expires_at=2026-12-31T00:00:00Z"

Response

Status: 200 OK — returns the created Document object:

{
  "document_id": "doc_01h9z…",
  "filename": "mfa-screenshot.png",
  "type": "evidence",
  "file_type": "png",
  "chunks": 1,
  "uploaded_at": "2026-06-04T15:04:05Z",
  "expires_at": "2026-12-31T00:00:00Z",
  "framework_id": "pci_dss_v4",
  "control_id": "8.4.2",
  "image_summary": "Screenshot of the admin console showing MFA enforced for all administrators…"
}

List Documents

GET /v1/documents

Returns an array of Document objects. All query parameters are optional and combine as filters.

Parameter Type Description
type string Filter by document type.
file_type string Filter by file extension (e.g. pdf, png, txt).
framework_id string Filter by framework ID.
control_id string Filter by control ID.
expired boolean true returns only expired documents; false only unexpired; omit for all.

Example

List the unexpired evidence for one framework — useful for spotting evidence that needs refreshing before an audit:

curl -H "authorization: YOUR_API_KEY" \
  "https://compliance.secberus.ai/v1/documents?type=evidence&framework_id=pci_dss_v4&expired=false"

Response

Status: 200 OK

[
  {
    "document_id": "doc_01h9z…",
    "filename": "mfa-screenshot.png",
    "type": "evidence",
    "file_type": "png",
    "chunks": 1,
    "uploaded_at": "2026-06-04T15:04:05Z",
    "expires_at": "2026-12-31T00:00:00Z",
    "framework_id": "pci_dss_v4",
    "control_id": "8.4.2"
  }
]

Delete a Document

DELETE /v1/documents/{document_id}
Parameter In Description
document_id path ID of the document to delete.

Example

curl -X DELETE https://compliance.secberus.ai/v1/documents/doc_01h9z… \
  -H "authorization: YOUR_API_KEY"

Response

Status: 204 No Content — the document and its indexed chunks are removed from your corpus.

Document Object

Field Type Description
document_id string Unique identifier. Use this in document_ids and --docs.
filename string Original filename.
type string policy, evidence, questionnaire, or custom_framework.
file_type string File extension without the leading dot (e.g. pdf, png, txt).
chunks integer Number of indexed chunks the document was split into.
uploaded_at string ISO 8601 upload timestamp.
expires_at string ISO 8601 expiry timestamp. Absent means no expiry.
framework_id string Framework the document is associated with.
control_id string Control the document provides evidence for.
image_summary string For image evidence: an AI-generated, compliance-focused summary of the image. Absent for non-image files.

Error Responses

Errors use RFC 7807 format:

Status Description
400 Bad Request — missing file/type, or missing required evidence fields
403 Forbidden — invalid or missing API key
500 Internal Server Error — contact support if persistent
Audit Readiness MCP Server