Document API¶

List, create, retrieve, update, delete and query documents in Knowledge Bases. The public routes retain the repositories identifier.

Use the external repository UUID and document UUID returned by the API. The examples below use placeholders; replace them with actual identifiers before sending a request. See authentication for API keys and workspace identity headers.

List Documents¶

Endpoint: GET /repositories/{repositoryId}/documents

Parameters¶

The documented status values are queued, summary_uploaded, ready, summary_processing, summary_generated, summary_failed, upload_failed, failed, index_pending and indexing.

Example¶

curl --fail-with-body --max-time 30 --get \
  "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/REPOSITORY_UUID/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "start=0" \
  --data-urlencode "limit=50" \
  --data-urlencode "includeText=false"

Response¶

The response contains a top-level data array and pagination object. Each document includes document_id, name, document_status, additional_fields, metadata and timestamps. The full text is omitted when includeText=false.

Abbreviated example with synthetic values:

{
  "data": [
    {
      "id": 123,
      "document_id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Example Guide",
      "document_status": "ready",
      "additional_fields": {},
      "metadata": {}
    }
  ],
  "pagination": {"start": 0, "limit": 50, "total": 1}
}

Create Document¶

Endpoint: POST /repositories/{repositoryId}/documents

Request Body¶

Use application/json for text documents. The current request fields are name and text, with metadata, locks and notes shown in the schema. File documents use multipart/form-data; consult the interactive schema for the file fields.

{
  "name": "Example Guide",
  "text": "Synthetic documentation example.",
  "metadata": {"source": "documentation-example"},
  "locks": [],
  "notes": "Synthetic test document"
}

Review the intended document locks before upload; an empty array in this example is not an access-control recommendation.

Example¶

Save the intended body in document.json, then submit it to an approved test repository:

curl --fail-with-body --max-time 30 -X POST \
  "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/REPOSITORY_UUID/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

Response¶

A successful creation returns 201 with top-level success and a data array containing per-item fileName, response and type fields. Inspect the item outcome and subsequent document status; do not assume the upload response is a ready document object.

Get Document¶

Endpoint: GET /repositories/{repositoryId}/documents/{id}

The path id is the document UUID. includeText=false can omit the full text. The success response is a top-level document object, including document_id, name, document_status, metadata, additional_fields, notes and summary; it is not wrapped in data.documents.

curl --fail-with-body --max-time 30 \
  "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/REPOSITORY_UUID/documents/DOCUMENT_UUID?includeText=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Document¶

Endpoint: PUT /repositories/{repositoryId}/documents/{id}

The documented JSON request uses the same name, text, metadata, locks and notes field names as creation. The success schema returns a document_id field.

Read the current document before preparing an update. Confirm how omitted fields and nested metadata are handled before relying on a partial update, and re-read the document afterward to verify the intended change. Do not bulk-update search results without reviewing the target list and payload.

Delete Document¶

Endpoint: DELETE /repositories/{repositoryId}/documents/{id}

Check the repository and document UUIDs against a fresh retrieval before deletion. Review your organization's recovery and retention requirements before removing a document. See the interactive endpoint schema for its response contract.

Query Documents¶

Endpoint: POST /repositories/{repositoryId}/documents/query

The request includes query, topK, full_document and optional filters. Filter syntax is distinct from the list endpoint's query parameters.

{
  "query": "How do I configure a search filter?",
  "topK": 10,
  "full_document": false
}

The response has top-level query and results. Each result contains Document, score and document_id; Document contains pageContent, fullDocument and metadata.

{
  "query": "How do I configure a search filter?",
  "results": [
    {
      "Document": {
        "pageContent": "Synthetic matching content.",
        "fullDocument": "",
        "metadata": {}
      },
      "score": 0.8,
      "document_id": "550e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

These values illustrate the shape, not a guaranteed score or a captured retrieval result. Compare retrieved content with the expected source and verify access under the intended identity.

Finding Repository ID¶

Use List Repositories and read attributes.repository_id from the matching entry. Do not assume the Knowledge Base's UI slug is its external API UUID.

Best Practices¶

Document Structure¶

Use name and text for JSON text-document requests. Keep metadata and extracted additional_fields distinct; listing filters operate on declared extracted fields.

Tips¶

• Check HTTP status and endpoint-specific response shapes before accessing fields.
• Use finite request timeouts and bounded retries for read operations.
• Inspect document processing status before diagnosing missing search results.
• Test retrieval with synthetic source content and the intended member identity.
• Keep private text, locks, credentials and identifying metadata out of shared evidence.

Common Use Cases¶

Bulk Document Upload¶

Validate one synthetic upload and its resulting document status before batching. Record per-item outcomes from the creation response, stop on unexpected errors, and review failures before retrying to avoid duplicate work.

Search and Update¶

Query first and review the returned document_id values. Retrieve each intended document, prepare the update from its current state, then verify the result with another GET. Query results are evidence for selecting targets, not authorization to overwrite every match.

Related Topics¶

• Interactive Document schema — complete request fields and responses.
• Repository API — external repository identifiers.
• Knowledge — document processing in the platform.
• API Overview — authentication and setup.