Skip to main content

Conversations and files

Every conversation has its own private folder (the workspace) where your uploads and the files created by the agent live. This page shows the typical flows: send a document and ask about it, download a report the agent generated, and manage conversations (list, read messages, rename, delete). Each step says which API key permission it needs.

The conversation folder​

FolderContent
uploads/Files you uploaded.
workspace/Files the agent created (reports, Word documents, CSV, charts…).
derived/Files AION derived automatically, for example a .docx converted from an old .doc upload.

Files are always addressed by their relative path, such as uploads/3f9a1c2b_offer.pdf or workspace/report.docx.

Ask the agent about a file​

Permissions: Upload files + Chat.

1. Upload the file with a multipart request (field name files, repeatable for several files). The conversation is created if it does not exist, so you can use a fresh UUID:

CONVERSATION_ID=$(uuidgen)
curl -s "$AION_URL/v1/conversations/$CONVERSATION_ID/files" \
-H "Authorization: Bearer $AION_API_KEY" \
-F "files=@offer.pdf"
{
"attachments": [
{
"relative_path": "uploads/3f9a1c2b_offer.pdf",
"original_relative_path": "uploads/offer.pdf",
"name": "3f9a1c2b_offer.pdf",
"original_name": "offer.pdf",
"size_bytes": 482113,
"mime": "application/pdf"
}
]
}

2. Ask about it with the streaming endpoint, passing the returned objects in attachments so the agent knows which files the message refers to:

curl -N "$AION_URL/v1/chat/stream" \
-H "Authorization: Bearer $AION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"conversation_id": "'"$CONVERSATION_ID"'",
"message": "Summarize this offer: price, duration and penalties.",
"attachments": [{"relative_path": "uploads/3f9a1c2b_offer.pdf", "original_name": "offer.pdf", "mime": "application/pdf"}]
}'

How to read the stream: Streaming responses.

The same flow in Python:

import os, uuid, json, requests

AION_URL = os.environ["AION_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['AION_API_KEY']}"}
conv = str(uuid.uuid4())

# 1. upload
with open("offer.pdf", "rb") as fh:
up = requests.post(f"{AION_URL}/v1/conversations/{conv}/files",
headers=HEADERS, files=[("files", ("offer.pdf", fh, "application/pdf"))], timeout=120)
up.raise_for_status()
attachments = up.json()["attachments"]

# 2. ask, reading the streamed answer
body = {"conversation_id": conv, "message": "Summarize this offer: price, duration and penalties.",
"attachments": attachments}
with requests.post(f"{AION_URL}/v1/chat/stream", headers=HEADERS, json=body, stream=True, timeout=(10, 900)) as r:
r.raise_for_status()
for line in r.iter_lines(decode_unicode=True):
if line and line.startswith("data:"):
ev = json.loads(line[5:].strip())
if ev.get("type") == "final":
print(ev["text"])
note

The synchronous POST /v1/chat has no attachments field: to point the agent at specific files, use POST /v1/chat/stream.

Large PDFs, scanned documents and old Word files are processed automatically after upload (text extraction, OCR, .doc → .docx conversion). See Office and legacy Word and Document evidence.

Download the files the agent produced​

Permission: Read files.

1. List the files of a folder (uploads, workspace or derived):

curl -s "$AION_URL/sessions/$CONVERSATION_ID/files?subdir=workspace" \
-H "Authorization: Bearer $AION_API_KEY"
{"files": [{"name": "offer_summary.docx", "relative_path": "workspace/offer_summary.docx", "size_bytes": 18234, "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"}]}

GET /v1/conversations/{id}/files returns the same information for uploads/ only.

2. Download one file by relative path:

curl -s -o offer_summary.docx \
"$AION_URL/sessions/$CONVERSATION_ID/download?relative_path=workspace/offer_summary.docx" \
-H "Authorization: Bearer $AION_API_KEY"
Invoke-WebRequest -OutFile offer_summary.docx -Headers @{ Authorization = "Bearer $env:AION_API_KEY" } `
-Uri "$env:AION_URL/sessions/$env:CONVERSATION_ID/download?relative_path=workspace/offer_summary.docx"

Manage conversations​

TaskRequestPermission
Create a conversation with a title, tags or metadataPOST /v1/conversations with {"profile": "aion_std", "title": "Q2 audit", "tags": ["audit"], "metadata": {"source": "crm"}}Manage conversations
List your conversationsGET /v1/conversations?limit=20Read conversations
Read one conversationGET /v1/conversations/{id}Read conversations
Read its messagesGET /v1/conversations/{id}/messages?limit=50 (include_internal=true adds tool messages)Read conversations
Rename, retagPATCH /v1/conversations/{id} with {"title": "…", "tags": […]}Manage conversations
Delete (archive)DELETE /v1/conversations/{id}Manage conversations

Creating a conversation explicitly is optional: POST /v1/chat creates one when you omit the id, and POST /v1/chat/stream creates it on first use. Create it explicitly when you want a title, tags or metadata (for example the id of the CRM ticket that originated it), so you can find it later.

Example — read the last messages of a conversation:

curl -s "$AION_URL/v1/conversations/$CONVERSATION_ID/messages?limit=10" \
-H "Authorization: Bearer $AION_API_KEY"
{"data": [
{"id": "…", "role": "user", "content": "Summarize this offer…", "created_at": "2026-11-18T09:12:03Z"},
{"id": "…", "role": "assistant", "content": "The offer is valid for 24 months…", "reasoning": null, "created_at": "2026-11-18T09:12:41Z"}
]}

Ownership and privacy​

  • A conversation belongs to the user who created it (for a key: the key's owner). Every other user — administrators included — gets 404 Conversation not found, so its existence is not revealed.
  • Conversations created through the API show up in the owner's chat sidebar, where they can be continued by hand.
  • Deleting a conversation archives it and frees the resources the agent was keeping for it.

Full request and response schemas: REST API reference.