- Core Concepts
- Documents
Core Concepts
Documents
Upload and process documents for RAG
Documents are files you upload to provide context to your assistant via RAG (Retrieval-Augmented Generation). They can be scoped to an assistant (shared across all threads) or a thread (single conversation only).
Supported File Types
| Category | Extensions |
|---|---|
| Documents | .pdf, .doc, .docx, .ppt, .pptx, .xls, .xlsx |
| Text / Data | .txt, .csv, .md, .markdown, .json, .jsonl, .xml |
| Code | .py, .js, .ts, .jsx, .tsx, .html, .css, .cpp, .c, .h, .java, .go, .rs, .rb, .php, .sql |
| Images | .png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff, .tif |
Processing Pipeline
- Upload — document is received via API
- Processing — Backboard extracts and parses content
- Indexed — content is chunked, embedded, and searchable
- On failure the status becomes error
Status values: pending → processing → indexed (or error)
Upload to Assistant (shared context)
import requests
assistant_id = "your-assistant-id"
headers = {"X-API-Key": "YOUR_API_KEY"}
with open("knowledge-base.pdf", "rb") as f:
doc = requests.post(
f"https://app.backboard.io/api/assistants/{assistant_id}/documents",
headers=headers,
files={"file": f}
).json()
print(doc["document_id"], doc["status"])
Upload to Thread (conversation-specific)
with open("meeting-notes.pdf", "rb") as f:
doc = requests.post(
f"https://app.backboard.io/api/threads/{thread_id}/documents",
headers=headers,
files={"file": f}
).json()
Check Document Status
Poll until status is indexed before using the document in messages.
import time
while True:
status = requests.get(
f"https://app.backboard.io/api/documents/{document_id}/status",
headers=headers
).json()
print(f"Status: {status['status']}")
if status["status"] == "indexed":
print(f"Chunks: {status.get('chunk_count')}, Tokens: {status.get('total_tokens')}")
break
elif status["status"] == "error":
print(f"Error: {status.get('status_message')}")
break
time.sleep(2)
Document Status Response
| Field | Type | Description |
|---|---|---|
document_id | uuid | Document identifier |
filename | string | Original filename |
document_type | string | Scope: assistant, thread, or message |
status | string | pending, processing, indexed, or error |
status_message | string | Error details (when status is error) |
file_size_bytes | integer | File size |
total_tokens | integer | Total tokens after processing |
chunk_count | integer | Number of chunks created |
processing_started_at | datetime | When processing began |
processing_completed_at | datetime | When processing finished |
List Documents
# Documents on an assistant
docs = requests.get(
f"https://app.backboard.io/api/assistants/{assistant_id}/documents",
headers=headers
).json()
# Documents on a thread
docs = requests.get(
f"https://app.backboard.io/api/threads/{thread_id}/documents",
headers=headers
).json()
Delete a Document
requests.delete(
f"https://app.backboard.io/api/documents/{document_id}",
headers=headers
)
Documents must reach indexed status before they can be used in conversations. Sending messages while documents are still processing may result in incomplete context.