AI Documents

AI documents are context files attached to a service. When an AI processor runs, it can retrieve and query these documents to inform its output — for example, referencing your architecture notes, runbooks, or policy documents when generating a configuration.

Accessed via client.ai_documents.

Model properties

Property	Type	Description
`id`	`int`	Document ID
`service_id`	`int`	Associated service ID
`created`	`datetime`	Creation timestamp
`modified`	`datetime`	Last modified timestamp

Methods

`list(**filters)`

Returns a lazy generator of all AI documents.

Filters:

Filter	Type	Description
`service_id`	`int`	Filter by service
`ordering`	`str`	Sort field — prefix with `-` for descending

for doc in client.ai_documents.list():
    print(doc.id)

# All documents for a service
for doc in client.ai_documents.list(service_id=45):
    print(doc.id, doc.created)

`filter(**filters)`

Same as list() but returns all results as a list. Accepts the same filters.

docs = client.ai_documents.filter(service_id=45)
print(f"{len(docs)} documents attached to this service")

`get(id)`

Retrieves a single AI document by ID.

doc = client.ai_documents.get(12)
print(doc.id, doc.service_id, doc.created)

`create(data)`

Uploads a new AI document. Use this to attach a context file directly without tying it to a service in the same call.

Field	Type	Required	Description
`service`	`int`	yes	Service to attach the document to
`filename`	`str`	yes	Filename (e.g. `architecture.md`)
`raw_content`	`str`	yes	The document text content

doc = client.ai_documents.create({
    "service": 45,
    "filename": "architecture.md",
    "raw_content": "# Architecture\nThis service uses a primary-replica PostgreSQL setup..."
})
print(doc.id)

`create_for_service(service_id, data)`

Creates a document and attaches it to a service in a single call. Equivalent to create() but uses a service-scoped endpoint.

Parameter	Type	Description
`service_id`	`int`	Service to attach the document to
`data`	`dict`	Document fields (same as `create()`)

doc = client.ai_documents.create_for_service(
    service_id=45,
    data={
        "filename": "runbook.md",
        "raw_content": "# Runbook\nStep 1: Check the logs at /var/log/app.log..."
    }
)
print(doc.id)

`update(id, data, partial=True)`

Updates an existing AI document. Defaults to PATCH.

Parameter	Type	Description
`id`	`int`	Document ID
`data`	`dict`	Fields to update
`partial`	`bool`	`True` (default) = PATCH, `False` = PUT

client.ai_documents.update(12, {
    "raw_content": "# Architecture (updated)\nMigrated to multi-region in June 2025..."
})

`delete(id)`

Permanently deletes an AI document and removes it from the service.

client.ai_documents.delete(12)

`by_service(service_id)`

Returns all documents attached to a specific service as a list. Shortcut for filter(service_id=service_id).

docs = client.ai_documents.by_service(service_id=45)
for doc in docs:
    print(doc.id, doc.created)

`query_service(service_id, query, **kwargs)`

Performs a semantic search across all documents attached to a service. Useful for testing what context the AI will retrieve at runtime before committing to a processor.

Parameter	Type	Description
`service_id`	`int`	Service whose documents to search
`query`	`str`	Natural language query
`**kwargs`		Any additional parameters to pass to the query endpoint

result = client.ai_documents.query_service(
    service_id=45,
    query="How do I configure a read replica?"
)
print(result)

# With additional parameters
result = client.ai_documents.query_service(
    service_id=45,
    query="What are the supported database engines?",
    top_k=5
)