Files

The REST API for the Files app. Create documents for AI-powered analysis and semantic search. Document content is stored securely and automatically indexed for semantic search.

List Documents

GET /v1/documents

Query Parameters

Parameter	Type	Description
`project_id`	UUID	Scope results to a project (optional)
`parent_id`	UUID	Scope results to a folder (optional)
`search`	string	Filter by title text (optional)
`limit`	integer	Max results (1–100)
`offset`	integer	Pagination offset

Create Document

POST /v1/documents

Create a document with text content. The content is automatically indexed for semantic search in the background after the response returns.

System-assigned fields (id, org_id, created_at, updated_at) are never supplied by the caller; the organization comes from the authenticated session and the rest are assigned by the server.

Request Body

Field	Type	Description
`title`	string	Document title (required)
`content`	string	Document content (optional)
`content_type`	string	One of `markdown`, `plain`, `rich_text` (optional, defaults to `markdown`)
`project_id`	UUID	Project to attach the document to (optional)
`parent_id`	UUID	Folder to place the document in (optional)
`tags`	string[]	Tags (optional)

Response

On success (201 Created) the complete created document is returned.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "folder_id": null,
    "project_id": null,
    "title": "My Document",
    "content": "...",
    "content_type": "markdown",
    "file_url": null,
    "file_size": null,
    "metadata": {},
    "is_indexed": false,
    "indexed_at": null,
    "created_by": "...",
    "created_at": "2026-06-20T12:00:00Z",
    "updated_at": "2026-06-20T12:00:00Z",
    "deleted_at": null
  }
}

is_indexed is false immediately after creation; indexing completes in the background (see Indexing for Search below).

Response Codes

Status	Meaning
`201`	Document created; the full record is returned
`400`	Validation error (missing/invalid field, a `project_id`/`parent_id` that does not reference an existing item, or content rejected by the safety policy)
`401`	Authentication required
`403`	Caller lacks the required permission to create documents
`500`	Unexpected server error

Get Document

GET /v1/documents/:id

Returns the document record, including its content and metadata.

Update Document

PUT /v1/documents/:id

Update a document's title, content, content_type, or tags. When new content is supplied the document is automatically re-indexed in the background.

Delete Document

DELETE /v1/documents/:id

Removes the document and its stored content.

Indexing for Search

After a document is created or its content is updated, it is automatically indexed for semantic search in the background, so the API response returns immediately. The search index is kept up to date for you, so no manual reindexing is required.

Once indexed, documents are searchable via the Search API and the AI assistant.