Document Workspace

Overview

The Document Workspace allows users to upload files into a chat session. Uploaded files are processed through a pipeline of text extraction, chunking, and embedding. Once processed, documents become searchable by the model via the file_search built-in tool.

Documents persist across all messages and branches within a chat. This means that regardless of which conversation branch the user is on, all uploaded documents remain available for search. The model can reference any uploaded document by name and search across all document content to answer user questions.

Note: Document Workspace is a chat-level feature. Documents uploaded to one chat session are not accessible from other chat sessions.

Supported File Types

The following file types are supported for upload. Text-based formats are fully searchable after processing. Binary formats are stored but their content is not indexed for search.

Type	Extensions	Extraction Method
PDF	`.pdf`	Text extracted via PDF extractor
HTML	`.html`, `.htm`	Text extracted via HTML extractor
Plain text	`.txt`, `.md`, `.csv`, `.json`, `.xml`	Raw content used directly
Code files	`.swift`, `.py`, `.js`, `.ts`, `.go`, `.rs`, etc.	Raw content used directly
Binary formats	All other extensions	Metadata stored, content not searchable

Upload Flow

When a user uploads a file to a chat session, the following processing pipeline executes:

Upload initiation -- User drags and drops files or clicks the upload button in the chat UI.
File transfer -- The file is uploaded via the resumable upload endpoint, supporting large files and interrupted connections.
Artifact creation -- An artifact record is created linking the file to the chat session.
Text extraction -- The appropriate extractor runs based on file type (PDF extractor, HTML extractor, or raw content pass-through).
Chunking -- Extracted text is split into chunks of 1024 tokens with 128 tokens of overlap between adjacent chunks to preserve context at boundaries.
Embedding -- Each chunk is embedded as a vector representation for semantic search.
Available for search -- The document and its chunks are immediately available for search by the model via the file_search tool.

Note: Processing happens asynchronously after upload. Small text files are typically searchable within seconds. Larger PDFs may take longer depending on page count and content complexity.

file_search Tool

The file_search tool is a built-in tool that is automatically registered when a chat session has uploaded documents. The model invokes this tool to search across all document chunks using semantic similarity.

Parameters

Parameter	Type	Description
queryrequired	string	The search query to match against document chunks.
max_resultsoptional	integer	Maximum number of results to return. Default: 5.

Return Value

The tool returns an array of search results, each containing the following fields:

Field	Type	Description
filename	string	Name of the source file containing the matched chunk.
chunk_text	string	The text content of the matched chunk.
relevance_score	number	Cosine similarity score between the query and chunk embeddings (0.0 to 1.0).
artifact_id	string	The ID of the artifact record for the source document.

SSE Events

When streaming is enabled, the following SSE events are emitted during a file_search tool call:

Event	Description
`response.file_search_call.in_progress`	Emitted when the file_search tool call begins execution.
`response.file_search_call.searching`	Emitted while the search is being performed against document chunks.
`response.file_search_call.completed`	Emitted when search results are ready and have been returned to the model.

Example tool result

                    [
  {
    "filename": "architecture-overview.pdf",
    "chunk_text": "The system uses a three-tier architecture consisting of a load balancer, application servers, and a distributed database cluster...",
    "relevance_score": 0.92,
    "artifact_id": "artifact-abc123"
  },
  {
    "filename": "design-notes.md",
    "chunk_text": "Database sharding strategy follows a hash-based partitioning scheme across four primary nodes...",
    "relevance_score": 0.87,
    "artifact_id": "artifact-def456"
  }
]
                

Responses API Integration

The file_search tool can be included in the tools[] array of a Responses API request. When the chat has uploaded documents, the tool is available for the model to invoke during response generation.

Request Format

Include file_search as a tool type in the tools array. Use the include parameter with file_search_call.results to control whether the full chunk text appears in the response object.

JSON

                    {
  "model": "llama-3.1-8b",
  "input": "What does the architecture document say about database sharding?",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "include": ["file_search_call.results"],
  "stream": true
}
                

include Parameter Values

Value	Description
`file_search_call.results`	Include the full chunk text in each search result within the response output. When omitted, results contain only metadata (filename, relevance_score, artifact_id) without the chunk_text field.

Example response with file_search output

                    {
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "file_search_call",
      "id": "fs_call_001",
      "status": "completed",
      "queries": ["database sharding"],
      "results": [
        {
          "filename": "architecture-overview.pdf",
          "chunk_text": "Database sharding strategy follows a hash-based partitioning scheme...",
          "relevance_score": 0.92,
          "artifact_id": "artifact-abc123"
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "According to the architecture document, the database uses a hash-based sharding strategy..."
        }
      ]
    }
  ]
}
                

Automatic Context Injection

In addition to explicit file_search tool calls, the Document Workspace supports automatic context injection. This follows the same pattern used for chat memory:

The user's message is embedded and searched against all document chunks in the chat session.
The top relevant chunks are automatically injected into the model's context alongside the user message.
The complete file list is included in the system prompt so the model can reference documents by name, even before performing an explicit search.

This means the model has awareness of uploaded documents from the first message after upload, without the user needing to explicitly ask the model to search. For more targeted retrieval, the model can still invoke the file_search tool with specific queries.

Note: Automatic context injection uses the same relevance threshold as memory injection. Only chunks above the similarity threshold are included to avoid injecting irrelevant content.

Document Management API

The following REST endpoints manage documents within a chat session. All paths are relative to the chat API base.

List Documents

GET /chat/api/{chatId}/documents

Returns all documents uploaded to the specified chat session.

curl

                    curl https://api.xerotier.ai/chat/api/chat-abc123/documents \
  -H "Cookie: session=your_session_token"
                

Response

                        {
  "documents": [
    {
      "artifact_id": "artifact-abc123",
      "filename": "architecture-overview.pdf",
      "size": 2048576,
      "type": "application/pdf",
      "uploaded_at": "2026-03-07T10:30:00Z",
      "status": "processed"
    },
    {
      "artifact_id": "artifact-def456",
      "filename": "design-notes.md",
      "size": 15234,
      "type": "text/markdown",
      "uploaded_at": "2026-03-07T10:31:00Z",
      "status": "processed"
    }
  ],
  "total": 2
}
                    

Document Status Values

Status	Description
`uploading`	File upload is in progress.
`processing`	Text extraction and embedding are running.
`processed`	Document is fully indexed and searchable.
`error`	Processing failed. The document is stored but not searchable.

Delete Document

DELETE /chat/api/{chatId}/documents/{artifactId}

Soft-deletes a document and all of its associated chunks and embeddings. The document will no longer appear in search results or the document list.

curl

                    curl -X DELETE https://api.xerotier.ai/chat/api/chat-abc123/documents/artifact-abc123 \
  -H "Cookie: session=your_session_token"
                

Response

                        {
  "deleted": true,
  "artifact_id": "artifact-abc123"
}
                    

Python (requests)

Python

                    import requests

base = "https://api.xerotier.ai/chat/api"
chat_id = "chat-abc123"
cookies = {"session": "your_session_token"}

# List documents
docs = requests.get(f"{base}/{chat_id}/documents", cookies=cookies).json()
for doc in docs["documents"]:
    print(f"{doc['filename']} ({doc['status']}) - {doc['size']} bytes")

# Delete a document
requests.delete(
    f"{base}/{chat_id}/documents/artifact-abc123",
    cookies=cookies
)
                

Node.js (fetch)

JavaScript

                    const base = "https://api.xerotier.ai/chat/api";
const chatId = "chat-abc123";
const headers = { "Cookie": "session=your_session_token" };

// List documents
const docsRes = await fetch(`${base}/${chatId}/documents`, { headers });
const docs = await docsRes.json();
docs.documents.forEach(doc =>
    console.log(`${doc.filename} (${doc.status}) - ${doc.size} bytes`)
);

// Delete a document
await fetch(`${base}/${chatId}/documents/artifact-abc123`, {
    method: "DELETE",
    headers
});
                

Chat UI

The chat interface includes a documents sidebar panel for managing uploaded files. The panel provides the following features:

Upload area -- A drag-and-drop zone for uploading files. Users can drag files from their desktop directly into the panel, or click to open a file picker dialog.
Document list -- Displays all uploaded documents with their filename, file size, and file type. Documents are listed in upload order with the most recent at the top.
Delete button -- Each document row includes a delete button that removes the document from the workspace after confirmation.
Document count badge -- The toolbar displays a badge showing the total number of documents in the workspace. The badge updates in real time as documents are added or removed.

Processing status is shown inline next to each document. While a document is being processed, a spinner is displayed. Once processing completes, a checkmark indicates the document is searchable. If processing fails, an error indicator is shown with a tooltip describing the failure.

Limits

The following limits apply to the Document Workspace. All limits are configurable by the platform administrator.

Limit	Default	Description
Maximum file size	200 MB	Maximum size of a single uploaded file. Files exceeding this limit are rejected at upload time.
Maximum files per chat	50	Maximum number of documents that can be uploaded to a single chat session.
Extracted text per file	500,000 characters	Maximum number of characters of extracted text indexed per file. Text beyond this limit is truncated and a warning is logged.

Note: When a file's extracted text exceeds the 500,000 character limit, the text is truncated at the limit boundary. The document is still searchable, but content beyond the truncation point is not indexed. A warning is included in the document's processing status.