Sessions

A session is one piece of agent work: an ask, an automation run, a chat, or the set-up run. GET /v1/sessions/{id} reads one (see Endpoints). The endpoints on this page list them and act on them. Each has an MCP twin with the same payload: list_sessions, cancel_session, delete_session and add_context. See the tool reference.

GET /v1/sessions

Read-only. No credits. MCP tool: list_sessions.

Sessions, newest first.

Parameter	In	Type	Default	Notes
`status`	query	string	—	`complete`, `running` or `failed`, or a stored state: `queued`, `running`, `awaiting_person`, `suspended`, `completed`, `failed`, `cancelled`. Comma-separate or repeat for several
`origin`	query	string	—	`user`, `automation`, `mcp` or `setup`. Comma-separate or repeat
`since`	query	string	—	RFC 3339 timestamp or `YYYY-MM-DD`
`limit`	query	integer	50	1–200

Shell

curl -G https://api.attensira.com/v1/sessions \
  --data-urlencode "status=running" --data-urlencode "origin=automation" \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "sessions": [
    {
      "id": "ses_9d02",
      "title": "Daily win plan",
      "origin": "automation",
      "status": "running",
      "state": "running",
      "automation_id": "aut_71cd",
      "created_at": "2026-09-23T06:00:02Z",
      "ended_at": null
    }
  ]
}

status is the three-word vocabulary (complete, running, failed); state is the finer stored word. A cancelled session reads failed under status and cancelled under state.

POST /v1/sessions/{id}/cancel

No credits. Works on a spent balance. MCP tool: cancel_session.

Stops a running session before its next step. Credits already spent on it stay spent. Idempotent: cancelling twice is the same as cancelling once. If the run already finished, the call returns that real ending unchanged; a cancel never rewrites a finished run.

Response

{ "id": "ses_9d02", "status": "failed", "state": "cancelled" }

DELETE /v1/sessions/{id}

Destructive. MCP tool: delete_session.

Permanently deletes a finished session and its trace. A running session answers 409: cancel it first.

Response

{ "id": "ses_9d02", "deleted": true }

POST /v1/sessions/{id}/context

Spends credits only with run: true. MCP tool: add_context.

Gives a session text or links it cannot find itself. The agent reads it as a message in the thread.

Field	Type	Notes
`text`	string	At most 20,000 characters
`urls`	string[]	`http` or `https`, at most 10
`run`	boolean	Default `false`

Send text, urls, or both.

run: false (default): nothing starts. The session’s next turn reads the context, and a run already in flight picks it up when its current turn ends.
run: true: the session is queued again to act on it now. That is a new turn, and it costs credits.

A cancelled session refuses new context.

Shell

curl -X POST https://api.attensira.com/v1/sessions/ses_9d02/context \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"text":"Our pricing page moved to /plans last week.","urls":["https://acme.com/plans"],"run":false}'

Response

{ "session_id": "ses_9d02", "status": "running" }

POST /v1/sessions/{id}/attachments

No credits. Needs steer. MCP tool: ask, through its files.

Attaches a file to a session so the agent can read it: a security letter, a price list, a screenshot. Send multipart/form-data with one file in a field named file, then reference the returned id in POST /v1/ask as files with the same session.

Type	What the agent gets
PDF, DOCX, CSV, TXT	The file’s text, read once when you upload it. Up to about 12,000 characters per file; a longer file is cut, and the agent is told it was cut
PNG, JPG	The image itself

The type is read from the file’s content, not its name. Anything else is 415; a file over 10 MB is 413. A session in another workspace is 404.

Shell

curl -X POST https://api.attensira.com/v1/sessions/ses_9d02/attachments \
  -H "Authorization: Bearer atn_live_<your key>" \
  -F "file=@soc2-letter.pdf"

Response

{
  "id": "att_5f1c0b2e9a7d4c3e8b6a1f0d2c4e6a8b",
  "session_id": "ses_9d02",
  "name": "soc2-letter.pdf",
  "content_type": "application/pdf",
  "size": 48213,
  "status": "read",
  "url": "https://…",
  "url_expires_at": "2026-10-18T13:52:29Z",
  "created_at": "2026-10-18T12:52:29Z"
}

status is read (the text was read), image, or unreadable. An unreadable file, such as a scanned PDF with no text in it, is still attached and still answers 201; notice then says which file it was and to upload it again as a PDF with selectable text. The agent is told it has not read that file, so it will not describe what is in it. The file is private. url is a signed link that works for one hour. To get a fresh one, call GET /v1/sessions/{id}/attachments/{attachment_id}.

Shell

curl -X POST https://api.attensira.com/v1/ask \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"question":"What is our SOC 2 status per this doc?","session":"ses_9d02","files":["att_5f1c0b2e9a7d4c3e8b6a1f0d2c4e6a8b"]}'

A message can reference at most 5 files, and only files attached to its own session. When a file states a fact about your company, the agent may propose it for your company facts. The proposal waits in your Inbox, and nothing is saved until you approve it. To ask the agent, use POST /v1/ask.

GET /v1/attachments/{id}

Read-only. No credits. Needs read. MCP: get on attensira://{workspace}/attachment/{id}.

Not on api.attensira.com as its own path: read it there as GET /v1/objects/attachment/{id}, or send this path to https://webapp.attensira.com with the same key.

One attachment of any session in the workspace, by its id alone, with a fresh url signed for one hour: the same body as GET /v1/sessions/{id}/attachments/{attachment_id}. An attachment in another workspace is 404. Read through GET /v1/objects/attachment/{id}, the answer also carries it as file.

POST /v1/uploads

No credits. Needs steer. Works on a spent balance. MCP tool: upload.

Not on api.attensira.com yet: send it to https://webapp.attensira.com with the same key, which answers errors in its own envelope.

Hands over one file for an action to use, and answers an upload id. Today one action takes a file: act with answer on a question an agent asked, as payload.file. To give the agent a file to read in a conversation, attach it to the session instead, above. Send JSON with the file base64-encoded, which is what an MCP client can send, or the same multipart/form-data as an attachment, with the file in a field named file:

Field	Type	Notes
`file_name`	string	Required. The name the file is shown under, with its extension
`file_base64`	string	Required. The file’s bytes, base64-encoded (standard or URL-safe, padded or not), without a `data:` prefix
`workspace`	string	Optional. Omit for the key’s workspace

The same types as an attachment are taken (PDF, DOCX, CSV, TXT, PNG, JPG), read from the file’s content and not its name: anything else is 415, and a file over 10 MB is 413.

Shell

curl -X POST https://webapp.attensira.com/v1/uploads \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"soc2-letter.pdf","file_base64":"JVBERi0xLjcK…"}'

Response

{
  "id": "upl_7b3e0c9d2a1f4e5b8c6d0a1b2c3d4e5f",
  "name": "soc2-letter.pdf",
  "content_type": "application/pdf",
  "size": 48213,
  "expires_at": "2026-10-28T12:52:29Z",
  "created_at": "2026-10-27T12:52:29Z"
}

An upload belongs to the workspace that made it, is used once, and is deleted a day after it was made if nothing used it. An id from another workspace, an expired one or one already used is 404: upload the file again.

Get started

The app

What you track

Reading the numbers

Pages and AI traffic

The agent

MCP

REST API

Agencies and client reporting

Account

Reference

GET /v1/sessions

POST /v1/sessions/{id}/cancel

DELETE /v1/sessions/{id}

POST /v1/sessions/{id}/context

POST /v1/sessions/{id}/attachments

GET /v1/attachments/{id}

POST /v1/uploads

​GET /v1/sessions

​POST /v1/sessions/{id}/cancel

​DELETE /v1/sessions/{id}

​POST /v1/sessions/{id}/context

​POST /v1/sessions/{id}/attachments

​GET /v1/attachments/{id}

​POST /v1/uploads

GET /v1/sessions

POST /v1/sessions/{id}/cancel

DELETE /v1/sessions/{id}

POST /v1/sessions/{id}/context

POST /v1/sessions/{id}/attachments

GET /v1/attachments/{id}

POST /v1/uploads