Update API

Update metadata for an existing document without re-uploading it.

Client Isolation

Updates are scoped to the caller's client. Attempting to update a document that belongs to a different client returns 404 — the same as a non-existent document — to avoid leaking information across clients.

Endpoint

PATCH /update

Request

Headers

Header	Required	Description
X-API-Key	Yes	Valid API key from API_KEY_CLIENTS env var
Content-Type	Yes	application/json

Body Parameters

Parameter	Type	Required	Description
document_id	string	Yes	The document ID to update
metadata	object	Yes	Metadata fields to merge into the existing document

Response

{
  "status": "updated",
  "document_id": "doc-123",
  "updated_fields": ["title", "author"]
}

Field	Description
status	Always "updated" on success
document_id	The document ID that was updated
updated_fields	List of metadata keys that were modified

Examples

Update Metadata

Update user metadata for an existing document:

curl -X PATCH http://localhost:8000/update \
  -H "X-API-Key: super-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc-123",
    "metadata": {
      "title": "Updated Report",
      "author": "Jane Smith",
      "department": "Engineering"
    }
  }'

Updated fields are stored under metadata.custom.* and become searchable. For example, author here is user metadata; system-derived source properties remain under metadata.source.*.

# Search for documents updated with a specific department
curl -X POST http://localhost:8000/search \
  -H "X-API-Key: super-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly report",
    "filters": {
      "department": "Engineering"
    }
  }'

Update from Python

import requests

url = "http://localhost:8000/update"
headers = {
    "X-API-Key": "super-secret-key",
    "Content-Type": "application/json"
}
data = {
    "document_id": "doc-123",
    "metadata": {"title": "Updated Report"}
}
response = requests.patch(url, headers=headers, json=data)
print(response.json())
# {'status': 'updated', 'document_id': 'doc-123', 'updated_fields': ['title']}

Response Codes

Code	Description
200	Success - Document metadata updated
401	Unauthorized - Invalid API key
404	Not Found - Document doesn't exist, or belongs to a different client
422	Validation Error - Missing required fields

Error Responses

{
  "detail": "Invalid API key"
}

{
  "detail": "Document not found"
}

{
  "detail": "Reserved metadata keys are not allowed: classification, metadata.created_at, processing"
}

System and legacy metadata paths are read-only and rejected here. See the Metadata and Entities Reference for the authoritative group and reserved-key contract.

Best Practices

1. Use for user metadata corrections - Fix user-facing titles, authors, or custom fields without reprocessing the entire document
2. Partial updates - Only include the fields you want to change; existing metadata is preserved
3. Custom metadata - All ordinary update keys are stored under metadata.custom.* and become filterable in search
4. Verify first - Use GET /documents to confirm the document exists before updating