Agent sessions

Minto is fileAI’s AI assistant: it answers questions about the documents in your workspace. The agent sessions API is how you use Minto from your own code. You open a session, ask a question, and get back a job that you poll (or receive by callback) for the answer. Later questions in the same session build on earlier ones.

How it works

A session holds the conversation. Each question you ask is a turn, and each turn runs as an asynchronous agent job with an id that starts sajob_. Agent jobs are polled on the same route as document jobs; see Async jobs. A session runs one turn at a time. Asking while a turn is still QUEUED or RUNNING returns 409 AGENT_RUN_IN_PROGRESS; wait for it to settle, or stop it.

Requirements

Every route uses the usual x-api-key header. See Authentication.
The key must be associated with a user. A key with no user gets 403 FORBIDDEN on session creation and on every ask. Re-issue the key with a user rather than retrying.
POST /v1/agent/sessions, POST …/ask and POST …/stop require an Idempotency-Key header. Without it you get 400. DELETE /v1/agent/sessions/{session_id} accepts one optionally. See Idempotent requests.

Endpoints

Method and path	What it does
`POST /v1/agent/sessions`	Create a session. Returns `201`.
`GET /v1/agent/sessions`	List sessions, newest first.
`GET /v1/agent/sessions/{session_id}`	Read one session, including `run_status`.
`POST /v1/agent/sessions/{session_id}/ask`	Ask a question. Returns `202` with a job.
`POST /v1/agent/sessions/{session_id}/stop`	Ask the agent to stop the running turn. Returns `202`.
`GET /v1/agent/sessions/{session_id}/messages`	Read the conversation, oldest first.
`DELETE /v1/agent/sessions/{session_id}`	Delete the session, stopping a live turn first.
`GET /v1/jobs/{job_id}`	Poll a turn’s job.

Example

The cURL commands assume FILEAI_BASE_URL="https://api.orion.file.ai/prod/v1", or your regional host.

Create a session

curl -X POST "$FILEAI_BASE_URL/agent/sessions" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Q3 supplier invoices" }'

Response (201)

{
  "session_id": "665f1c2e8a1b4c0012ab34cd",
  "title": "Q3 supplier invoices",
  "created_at": "2026-09-14T09:00:00.000Z",
  "updated_at": "2026-09-14T09:00:00.000Z",
  "last_active_at": null
}

title is optional (up to 200 characters). Without it the session is called New Chat until the agent names it from the first turn.

Ask a question

curl -X POST "$FILEAI_BASE_URL/agent/sessions/665f1c2e8a1b4c0012ab34cd/ask" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Idempotency-Key: 0f1c8e03-978e-40d5-bc93-6894a57f9324" \
  -H "Content-Type: application/json" \
  -d '{
    "user_prompt": "Which invoices from Acme are still unpaid?",
    "directory_id": "665f1c2e8a1b4c0012ab9911",
    "client_ref": "order-4417"
  }'

import os, uuid, requests

BASE = "https://api.orion.file.ai/prod/v1"
HEADERS = {"x-api-key": os.environ["FILEAI_API_KEY"]}

job = requests.post(
    f"{BASE}/agent/sessions/{session_id}/ask",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "user_prompt": "Which invoices from Acme are still unpaid?",
        "directory_id": "665f1c2e8a1b4c0012ab9911",
        "client_ref": "order-4417",
    },
).json()

const BASE = "https://api.orion.file.ai/prod/v1";
const headers = { "x-api-key": process.env.FILEAI_API_KEY };

const job = await fetch(`${BASE}/agent/sessions/${sessionId}/ask`, {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    user_prompt: "Which invoices from Acme are still unpaid?",
    directory_id: "665f1c2e8a1b4c0012ab9911",
    client_ref: "order-4417",
  }),
}).then((r) => r.json());

Response (202)

{
  "job_id": "sajob_9f2c1a4b7e8d4c1fa0b3",
  "status": "QUEUED",
  "session_id": "665f1c2e8a1b4c0012ab34cd",
  "created_at": "2026-09-15T02:14:00.000Z",
  "poll_url": "https://api.orion.file.ai/prod/v1/jobs/sajob_9f2c1a4b7e8d4c1fa0b3"
}

Poll the job

curl "$FILEAI_BASE_URL/jobs/sajob_9f2c1a4b7e8d4c1fa0b3" \
  -H "x-api-key: $FILEAI_API_KEY"

Response

{
  "job_id": "sajob_9f2c1a4b7e8d4c1fa0b3",
  "kind": "agent",
  "status": "COMPLETED",
  "session_id": "665f1c2e8a1b4c0012ab34cd",
  "created_at": "2026-09-15T02:14:00.000Z",
  "updated_at": "2026-09-15T02:14:11.000Z",
  "settled_at": "2026-09-15T02:14:11.000Z",
  "client_ref": "order-4417",
  "result": {
    "answer": "Two Acme invoices are unpaid: INV-2291 ($4,200) and INV-2309 ($1,150).",
    "title": "Unpaid Acme invoices",
    "execution_time": 8.7,
    "execution_cost": 0.021,
    "files": []
  },
  "error": null
}

If your API key has a default callback URL, the settled job is also POSTed there. Keep polling as a fallback; see Async jobs.

Reference

Ask fields

Field	Type	Description
`user_prompt`	string, required	The question. 1 to 30,000 characters.
`document_ids`	string[]	Limit this turn to these documents. Up to 100. Takes precedence over `file_ids`.
`file_ids`	string[]	Limit this turn to these files; their documents are resolved for you. Up to 100.
`directory_id`	string	Limit this turn to one folder. Must be a valid id.
`use_all_files`	boolean	Search the workspace’s processed documents instead of a fixed list. Overrides `file_ids` and `document_ids`. Default `false`.
`llm_model`	string	Model hint for this turn. Defaults to the workspace’s configured model.
`allow_internet_search`	boolean	Let the agent search the public internet. Default `true`.
`allow_ai_query_subagent`	boolean	Let the agent run structured queries over your data. Default `true`.
`client_ref`	string	Your own reference, up to 255 characters. Echoed on the job and on its callback.
`language_code`	string	BCP-47 tag for the answer language, e.g. `en`. Up to 35 characters.

Omit document_ids, file_ids and use_all_files to keep the session’s own scope.

use_all_files only considers the 100 most recently created processed documents. In a larger workspace the agent does not see the rest. When coverage matters, name the documents with document_ids or file_ids.

Job result

GET /v1/jobs/{job_id} returns kind: "agent" for a sajob_ id. For what each status means (QUEUED, RUNNING, COMPLETED, STOPPED, FAILED), see Agent jobs. Two things matter for Minto in particular:

result.answer holds the answer on COMPLETED, and the partial answer on STOPPED. On FAILED, error.code and error.detail describe the failure, and error.retryable says whether asking again is worthwhile.
FAILED with error.code SUPERAGENT_RUN_STALE is provisional. The run went quiet for too long and was given up on, but a run that was only slow can still finish and move to COMPLETED or STOPPED, with a second callback. Treat it as safe to retry, but don’t close out your own record for that job_id on it.

result.files lists any files the agent generated (PDF, HTML or Excel), each with name, content_type, a presigned url and its expires_at. Use the URL as given; ask again for a fresh link once it expires.

Session run status

GET /v1/agent/sessions/{session_id} includes run_status and the latest job_id. The list endpoint leaves run_status out, so read the single session when you need to know whether it can take a turn.

`run_status`	Session state
`null`	Never run. Free.
`QUEUED`, `RUNNING`	A turn is in flight. `ask` returns `409`.
`COMPLETED`, `FAILED`, `STOPPED`	Free.
`STALE`	Free. The last turn stopped reporting and was cleaned up when the session was read.

A turn that stops reporting sends no final event. It is only marked STALE when you read the session or its messages, or ask a new question; that is what frees the session.

Reading the conversation

GET /v1/agent/sessions/{session_id}/messages returns one row per message, oldest first: a user row for each question and an assistant row for each answer, so a turn appears as two rows.

Field	Description
`message_id`	The message’s id.
`role`	`user` or `assistant`.
`content`	The question on a `user` row; the answer on an `assistant` row. Empty while the turn is still running.
`content_truncated`	`true` when the answer was longer than 262,144 characters (256 × 1024) and `content` holds only the first part.
`content_length`	The answer’s full length in characters.
`run_status`	The turn’s status on an `assistant` row; `null` on a `user` row.
`job_id`	The turn’s job, or `null` for a turn asked in the app.
`error`	`code` and `detail` when the turn failed.
`execution_time`, `execution_cost`	Seconds taken and model spend in USD.
`files`	Files the agent generated on this turn.
`created_at`, `updated_at`	Timestamps.

To read a truncated answer in full, fetch its job_id from GET /v1/jobs/{job_id}. A turn asked in the app has no job, so its truncated answer can’t be retrieved in full through the API.

Pagination

Both list routes use cursor pagination only; there is no page parameter. Omit cursor for the first page, then pass pagination.nextCursor until hasMore is false.

Route	Order	Default `limit`	Maximum
`GET /v1/agent/sessions`	Newest first	50	100
`GET …/{session_id}/messages`	Oldest first	20	50

A larger limit is reduced to the maximum.

Stopping a turn

POST /v1/agent/sessions/{session_id}/stop is a request, not a completion. It returns 202 straight away with stop_requested, the run_status at that moment, job_id and poll_url.

The agent keeps working for about a second while it saves its partial work, then ends the turn. The partial answer is kept, and the time and cost already spent are still billed.
If the turn had already finished, stop_requested is false. That is a normal outcome, not an error.
The session stays open, and the next turn continues from where the agent stopped.

Poll the job_id until it reaches STOPPED, or whatever status the turn reached on its own.

Deleting a session

DELETE /v1/agent/sessions/{session_id} stops a live turn first instead of refusing. The response has deleted: true, stopped_run (whether a turn was stopped) and that turn’s job_id. The job outlives the session: its partial answer, cost and callback still arrive through GET /v1/jobs/{job_id}. Every route on a deleted session, including another DELETE, returns 404.

Async jobs

How agent jobs, document jobs and uploads report progress.

Idempotent requests

Why create, ask and stop require an Idempotency-Key.

Pagination

Cursor rules for the session and message lists.

Errors

AGENT_RUN_IN_PROGRESS, FORBIDDEN and the rest.

Get started

Products

Build

Go live

How it works

Requirements

Endpoints

Example

Reference

Ask fields

Job result

Session run status

Reading the conversation

Stopping a turn

Deleting a session

Async jobs

Idempotent requests

Pagination

Errors

​How it works

​Requirements

​Endpoints

​Example

​Reference

​Ask fields

​Job result

​Session run status

​Reading the conversation

​Pagination

​Stopping a turn

​Deleting a session

​Related

Async jobs

Idempotent requests

Pagination

Errors

How it works

Requirements

Endpoints

Example

Reference

Ask fields

Job result

Session run status

Reading the conversation

Pagination

Stopping a turn

Deleting a session

Related