API Reference
Base URL: https://api.research.alpha-sense.com/superanalyst/v1
Auth: Authorization: Bearer <access token>
The same API is available as an OpenAPI spec and a Postman collection. Download both from Postman and OpenAPI.
Conventions
- Request and response bodies are JSON, except event streams.
- Ids are opaque. URL-encode each id once when you put it in a path.
- Fields with no value are
null, except fields documented as absent. - Any endpoint can also return
401,403,429,500,502,503, or504. - Lists page with
limitandcursor. Stop whennext_cursorisnull. - Responses from the API include an
X-Request-Idheader. Quote it when you contact support. - Sessions and files belong to the user in the token. Another user's resource returns
404.
Endpoints
Every endpoint below is under /superanalysts/default. For example, the full URL to list sessions
is https://api.research.alpha-sense.com/superanalyst/v1/superanalysts/default/sessions.
| Method | Path | Description |
|---|---|---|
| POST | /sessions | Create a session and run the first turn |
| GET | /sessions | List sessions |
| GET | /sessions/{session_id} | Retrieve a session |
| POST | /sessions/{session_id}/messages | Send a follow-up |
| GET | /sessions/{session_id}/messages | Read the transcript |
| GET | /sessions/{session_id}/events | Stream the session's turns |
| POST | /sessions/{session_id}/cancel | Cancel the running turn |
| GET | /sessions/{session_id}/artifacts | List a session's artifacts |
| GET | /artifacts/{artifact_id} | Retrieve an artifact |
| GET | /artifacts/{artifact_id}/content | Download an artifact |
| GET | /files | List a workspace folder |
| GET | /files/{file_id} | Retrieve a workspace file |
| GET | /files/{file_id}/content | Download a workspace file |
A health check, with no auth, is at https://api.research.alpha-sense.com/superanalyst/v1/health.
It is not under /superanalysts/default.
Sessions
Create a session
POST /sessions
| Body field | Type | Required | Description |
|---|---|---|---|
input.text | string | Yes | The question. Not blank. |
input.type | string | No | text |
model | string | No | default, or omit |
metadata | object | No | String values only. Echoed back. |
With Accept: text/event-stream, the response is an event stream, starting with the first turn.
Otherwise it is the session object with status: "queued". Errors: 400, 401,
403, 404, 503.
List sessions
GET /sessions?limit=&cursor=. limit is 1–200, default 20. Returns
{"object": "list", "data": [...], "next_cursor": ...}, most recently active first. A cursor that
is too old returns 502; start again from the first page. See
Pagination.
Retrieve a session
GET /sessions/{session_id} returns the session object. Errors: 404.
Send a follow-up
POST /sessions/{session_id}/messages takes the same body as create and returns the
session object with status: "queued". Omitting model keeps the current model.
Errors: 400, 404, and 409 SESSION_BUSY while the session is queued or in_progress.
Cancel a turn
POST /sessions/{session_id}/cancel, with no body, returns the session object.
If a turn was queued or running, status is cancelled and cancelled_at is set. Calling it twice
is safe. A cancel sent in the first few seconds of a turn may not take effect: check the session,
and cancel again if it is still busy.
Session object
| Field | Type | Description |
|---|---|---|
id | string | Session id |
object | string | session |
title | string | null | Set once SuperAnalyst names the conversation |
superanalyst_id | string | default |
model | string | null | Echo of model on create and follow-up |
status | string | queued, in_progress, completed, failed, cancelled, timed_out |
cancelled_at | string | null | ISO-8601. Only on a cancel response that stopped a turn |
error | object | null | {code, message, retryable} when failed or timed_out |
metadata | object | Echo of metadata on create and follow-up, otherwise {} |
Messages
List messages
GET /sessions/{session_id}/messages?limit=. limit is 1–200, default 200, and keeps the newest
messages, oldest first. There is no paging.
Returns object, session_id, session_status, data (messages), next_cursor (always null),
and dropped_older_messages.
Message object
| Field | Type | Description |
|---|---|---|
id | string | Message id |
object | string | message |
superanalyst_id | string | default |
session_id | string | Session id |
role | string | user or assistant |
content | array | [{"type": "text", "text": "…"}]; text is Markdown |
citations | array | Citation objects |
artifacts | array | [{name, file_id}]; file_id is null |
created_at | string | null | ISO-8601 |
Citation object
| Field | Type | Description |
|---|---|---|
type | string | document or data. Skip types you don't recognize |
id | string | Unique within the message. Changes between reads, except datapoints |
title | string | null | Document title, or the cited value or data view name |
source | string | null | Where a document comes from, such as a news source or broker |
url | string | null | Opens the citation in AlphaSense |
document_id | string | null | The cited document. null for data |
page | integer | null | 1-based page of the cited passage |
statement_ids | array | The cited statements, the main one first. Empty for data |
broker_code | string | null | Set for broker research |
broker_name | string | null | Set for broker research |
text_ranges | array | [{start, end}]: each place the text cites it, in UTF-16 units |
See Citations for how to use text_ranges.
Events
Stream events
GET /sessions/{session_id}/events always returns text/event-stream. The first event is
session.resumed with the session's status. The stream stays open across turns, so a follow-up
streams on the same connection. Errors: 404, and 502, 503, or 504 when the stream can't be
opened. Events are listed on Streaming. Stream limits are in
Timeouts and limits.
Artifacts
List artifacts
GET /sessions/{session_id}/artifacts?limit=&cursor=. limit is 1–100, default 20. Returns
object, session_id, data (artifacts), and next_cursor.
Retrieve an artifact
GET /artifacts/{artifact_id} returns the artifact object with size_bytes. An
unknown or malformed id, or a folder, returns 404.
Artifact object
| Field | Type | Description |
|---|---|---|
id | string | Artifact id, the same value as file_id |
object | string | artifact |
superanalyst_id | string | default |
session_id | string | null | Session that produced it |
file_id | string | Use with the /files endpoints |
name | string | File name |
type | string | dashboard, report, slide, spreadsheet, other; may be absent |
mime_type | string | null | From the file extension |
size_bytes | integer | On retrieve only, and absent when unknown |
updated_at | string | null | ISO-8601. Approximate on lists |
Files
List files
GET /files?path=&limit=&cursor=. path is a folder path; omit it for the root. limit is 1–100,
default 20. Returns object, path, data (files), and next_cursor.
Retrieve a file
GET /files/{file_id} returns the file object. Errors: 400 for a malformed id,
404.
File object
| Field | Type | Description |
|---|---|---|
id | string | File id |
object | string | file |
name | string | File or folder name |
path | string | Path in the workspace |
type | string | file or directory |
mime_type | string | null | From the file extension |
size_bytes | integer | null | null for folders and some files |
updated_at | string | null | ISO-8601 |
Download content
GET /artifacts/{artifact_id}/content and GET /files/{file_id}/content return 200:
| Field | Present when | Description |
|---|---|---|
id | Always | The artifact or file id |
object | Always | artifact.content or file.content |
delivery | Always | inline or too_large |
encoding | inline | utf-8 or base64 |
content | inline, utf-8 | Text content |
content_base64 | inline, base64 | Base64-encoded bytes |
error | too_large | {code: "FILE_TOO_LARGE", message, retryable: false} |
Artifact content also includes superanalyst_id and session_id. Files over the download size
limit return too_large. A folder's content on /files/{file_id}/content returns 400.
Errors
Every error from the API uses one JSON shape. See Errors and Limits.
{
"error": {
"code": "SESSION_BUSY",
"message": "A turn is already in progress on this conversation. Wait for it to finish or cancel it.",
"type": "conflict",
"param": null,
"request_id": "req_3f9c0a1b2c3d4e5f60718293",
"retryable": false,
"details": {}
}
}