Documents API

The Documents API provides endpoints for uploading files, managing document lifecycle, controlling the ingestion queue, and inspecting the resulting knowledge graph entries.

Document Management

Method	Endpoint	Description
POST	/api/v1/documents/upload	Upload one or more files for ingestion
GET	/api/v1/documents/	List all documents
GET	/api/v1/documents/ingestion-status	Ingestion status across all documents
GET	/api/v1/documents/graph	Knowledge graph entries for ingested documents
GET	/api/v1/documents/{doc_id}/preview	Preview a document (PDF, text, or structured)
GET	/api/v1/documents/{doc_id}/download	Download the original file
PATCH	/api/v1/documents/{doc_id}/status	Update document status
POST	/api/v1/documents/{doc_id}/approve	Approve a document for ingestion
POST	/api/v1/documents/{doc_id}/ingest	Trigger ingestion for a specific document
DELETE	/api/v1/documents/{doc_id}	Delete a document

Document Linking

Method	Endpoint	Description
POST	/api/v1/documents/{doc_id}/link	Create a relationship link from this document
DELETE	/api/v1/documents/{doc_id}/link/{rel_id}	Remove a relationship link

Ingestion Queue

Method	Endpoint	Description
POST	/api/v1/documents/queue/enqueue	Add documents to the ingestion queue
POST	/api/v1/documents/queue/pause	Pause the ingestion queue
POST	/api/v1/documents/queue/resume	Resume the ingestion queue
GET	/api/v1/documents/queue/status	Current queue status and progress
GET	/api/v1/documents/queue/stream	SSE stream for real-time queue updates
DELETE	/api/v1/documents/queue/{doc_id}	Remove a document from the queue

---

Examples

Upload Documents

Upload one or more files using multipart/form-data.

curl -X POST https://yourorg.squadai.uk/api/v1/documents/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@fault-schedule-2026.pdf" \
  -F "files=@reactor-specs.docx"

Response 200

{
  "success": true,
  "files_uploaded": 2,
  "files": [
    {"key": "documents/fault-schedule-2026.pdf", "url": "https://storage.squadai.uk/documents/fault-schedule-2026.pdf"},
    {"key": "documents/reactor-specs.docx", "url": "https://storage.squadai.uk/documents/reactor-specs.docx"}
  ]
}

List Documents

curl https://yourorg.squadai.uk/api/v1/documents/ \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "documents": [
    {
      "id": "doc-001",
      "filename": "fault-schedule-2026.pdf",
      "status": "ingested",
      "uploaded_at": "2026-03-17T09:00:00Z",
      "size_bytes": 245760
    },
    {
      "id": "doc-002",
      "filename": "reactor-specs.docx",
      "status": "pending",
      "uploaded_at": "2026-03-17T09:00:01Z",
      "size_bytes": 102400
    }
  ]
}

Ingestion Status

curl https://yourorg.squadai.uk/api/v1/documents/ingestion-status \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "total": 12,
  "ingested": 8,
  "pending": 2,
  "failed": 1,
  "in_progress": 1
}

Update Document Status

curl -X PATCH https://yourorg.squadai.uk/api/v1/documents/doc-001/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved"}'

Response 200

{
  "id": "doc-001",
  "status": "approved",
  "updated_at": "2026-03-17T10:15:00Z"
}

Enqueue for Ingestion

curl -X POST https://yourorg.squadai.uk/api/v1/documents/queue/enqueue \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["doc-001", "doc-002"]}'

Response 200

{
  "queued": 2,
  "document_ids": ["doc-001", "doc-002"]
}

Queue Status

curl https://yourorg.squadai.uk/api/v1/documents/queue/status \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "status": "running",
  "total": 4,
  "completed": 2,
  "in_progress": 1,
  "pending": 1
}

Queue Stream (SSE)

Connect to the real-time ingestion progress stream.

curl -N https://yourorg.squadai.uk/api/v1/documents/queue/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Event stream

{"timestamp": "2026-03-17T10:20:00Z", "event": "ingestion_started", "data": {"doc_id": "doc-001", "filename": "fault-schedule-2026.pdf"}}
{"timestamp": "2026-03-17T10:20:15Z", "event": "ingestion_progress", "data": {"doc_id": "doc-001", "stage": "parsing", "progress": 0.45}}
{"timestamp": "2026-03-17T10:20:30Z", "event": "ingestion_completed", "data": {"doc_id": "doc-001", "nodes_created": 142}}