Xagent Docs
Get started

Files Overview

Files let agents work with real documents and data during task execution — upload reference materials, data files, or any document an agent needs to analyse, process, or reference.

What You Can Do

  • Analyze — process documents and extract information.
  • Reference — consult files during execution.
  • Transform — convert between formats.
  • Generate — create new files as output.

How Files Work

  1. Upload — the file is stored in your workspace.
  2. Available — it becomes accessible to agents.
  3. Read — the agent reads it when needed.
  4. Process — the agent analyses the content.
  5. Generate — the agent can produce new files.

Managing Files via API

POST   /api/files/upload               # upload a file (multipart/form-data)
GET    /api/files/list                 # list files
GET    /api/files/preview/{file_id}
GET    /api/files/stream-tickets/{file_id}   # short-lived ticket for media playback
GET    /api/files/download/{file_id}
DELETE /api/files/{file_id}

Preview normally authenticates like every other endpoint, with a bearer token. For a <video> or <audio> element that needs to stream and seek a file directly — where the browser can't attach an Authorization header — first mint a single-use ticket scoped to that one file with GET /api/files/stream-tickets/{file_id}, then pass it as ?ticket= on the preview URL instead of a bearer token. The ticket expires quickly (by default within a few minutes, matching your own session) and is only valid for the one file it was issued for.

Next Steps