List Documents

List all documents in your workspace with pagination support.

GET /api/v1/documents

Authentication

Requires an API key with the read permission.

Header	Value
X-API-Key	ink_live_abc123...

Query Parameters

Parameter	Type	Required	Default	Constraints	Description
page	integer	No	1	Minimum 1	Page number to retrieve
page_size	integer	No	20	Minimum 1, maximum 100	Number of documents per page

Code Examples

cURL

curl "https://api.inherent.systems/api/v1/documents?page=1&page_size=20" \
  -H "X-API-Key: $INHERENT_API_KEY"

Python

import requests

response = requests.get(
    "https://api.inherent.systems/api/v1/documents",
    headers={"X-API-Key": "ink_live_abc123..."},
    params={"page": 1, "page_size": 20},
)

data = response.json()
for doc in data["documents"]:
    print(f"{doc['name']} ({doc['status']}) - {doc['chunk_count']} chunks")

print(f"Page {data['page']} of {-(-data['total'] // data['page_size'])}")

JavaScript

const params = new URLSearchParams({ page: "1", page_size: "20" });

const response = await fetch(
  `https://api.inherent.systems/api/v1/documents?${params}`,
  {
    headers: {
      "X-API-Key": "ink_live_abc123...",
    },
  }
);

const data = await response.json();
data.documents.forEach((doc) => {
  console.log(`${doc.name} (${doc.status}) - ${doc.chunk_count} chunks`);
});

Response

Status: 200 OK

{
  "documents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "API Authentication Guide.md",
      "workspace_id": "ws_abc123",
      "source_type": "upload",
      "mime_type": "text/markdown",
      "size_bytes": 32768,
      "chunk_count": 24,
      "status": "completed",
      "created_at": "2026-03-15T10:30:00Z",
      "updated_at": "2026-03-15T10:31:45Z",
      "metadata": {
        "category": "documentation"
      }
    },
    {
      "id": "b2c3d4e5-f678-9012-bcde-f12345678901",
      "name": "Q4 Engineering Report.pdf",
      "workspace_id": "ws_abc123",
      "source_type": "upload",
      "mime_type": "application/pdf",
      "size_bytes": 1048576,
      "chunk_count": 87,
      "status": "completed",
      "created_at": "2026-03-14T09:00:00Z",
      "updated_at": "2026-03-14T09:05:12Z",
      "metadata": {
        "department": "engineering",
        "quarter": "Q4"
      }
    }
  ],
  "total": 142,
  "page": 1,
  "page_size": 20
}

Response Fields

Field	Type	Description
documents	array	Array of document objects
documents[].id	string	Unique document identifier (UUID)
documents[].name	string	Original filename
documents[].workspace_id	string	ID of the workspace
documents[].source_type	string	How the document was ingested (e.g., "upload")
documents[].mime_type	string	MIME type of the document
documents[].size_bytes	integer	File size in bytes
documents[].chunk_count	integer	Number of chunks the document was split into
documents[].status	string	Processing status: "pending", "processing", "completed", or "failed"
documents[].created_at	string	ISO 8601 timestamp of when the document was uploaded
documents[].updated_at	string	ISO 8601 timestamp of the last status change
documents[].metadata	object | null	User-provided metadata from upload
total	integer	Total number of documents in the workspace
page	integer	Current page number
page_size	integer	Number of items per page

Errors

Status	Error Type	Description
401	unauthorized	Missing or invalid API key
403	forbidden	API key does not have read permission
422	validation-error	Invalid query parameters (e.g., page_size out of range)
429	rate-limit-exceeded	Rate limit exceeded

Example Error Response

{
  "type": "https://api.inherent.systems/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "page_size must be between 1 and 100, got 500.",
  "instance": "/api/v1/documents",
  "trace_id": "d4e5f678-9012-abcd-ef12-345678901234",
  "timestamp": "2026-04-03T12:34:56.789Z"
}