Create an agent session - fileAI Docs

POST

/

v1

/

agent

/

sessions

Create an agent session

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/agent/sessions \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "title": "Q3 supplier invoices"
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/agent/sessions"

payload = { "title": "Q3 supplier invoices" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({title: 'Q3 supplier invoices'})
};

fetch('https://api.orion.file.ai/prod/v1/agent/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "session_id": "665f1c2e8a1b4c0012ab34cd",
  "title": "New Chat",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "last_active_at": "2023-11-07T05:31:56Z"
}

Request · Response · Guide: Minto

More details

The session starts empty. Creating one runs no agent work — a turn is only enqueued when you ask a question.Idempotency-Key is required, so a retry after a timeout can never leave you with two sessions.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

required

Required opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true. Omitting it is a 400; reusing a key with a different body is a 422; retrying while the first request is still in flight is a 409.

Body

application/json

title

string

Human-readable name for the session.

Omit it — or send a blank string — and the session is titled "New Chat" until the agent generates a name from its first turn.

Maximum string length: 200

Example:

"Q3 supplier invoices"

Response

Session created.

session_id

string

required

Opaque session identifier used by the other agent routes.

Example:

"665f1c2e8a1b4c0012ab34cd"

title

string

required

The submitted title, or the placeholder the agent replaces when it names the session on its first turn.

Example:

"New Chat"

created_at

string<date-time>

required

updated_at

string<date-time>

required

last_active_at

string<date-time> | null

When a turn was last enqueued on this session.

Create an agent session

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/agent/sessions \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "title": "Q3 supplier invoices"
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/agent/sessions"

payload = { "title": "Q3 supplier invoices" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({title: 'Q3 supplier invoices'})
};

fetch('https://api.orion.file.ai/prod/v1/agent/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "session_id": "665f1c2e8a1b4c0012ab34cd",
  "title": "New Chat",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "last_active_at": "2023-11-07T05:31:56Z"
}