Skip to main content

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, or 504.
  • Lists page with limit and cursor. Stop when next_cursor is null.
  • Responses from the API include an X-Request-Id header. 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.

MethodPathDescription
POST/sessionsCreate a session and run the first turn
GET/sessionsList sessions
GET/sessions/{session_id}Retrieve a session
POST/sessions/{session_id}/messagesSend a follow-up
GET/sessions/{session_id}/messagesRead the transcript
GET/sessions/{session_id}/eventsStream the session's turns
POST/sessions/{session_id}/cancelCancel the running turn
GET/sessions/{session_id}/artifactsList a session's artifacts
GET/artifacts/{artifact_id}Retrieve an artifact
GET/artifacts/{artifact_id}/contentDownload an artifact
GET/filesList a workspace folder
GET/files/{file_id}Retrieve a workspace file
GET/files/{file_id}/contentDownload 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 fieldTypeRequiredDescription
input.textstringYesThe question. Not blank.
input.typestringNotext
modelstringNodefault, or omit
metadataobjectNoString 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​

FieldTypeDescription
idstringSession id
objectstringsession
titlestring | nullSet once SuperAnalyst names the conversation
superanalyst_idstringdefault
modelstring | nullEcho of model on create and follow-up
statusstringqueued, in_progress, completed, failed, cancelled, timed_out
cancelled_atstring | nullISO-8601. Only on a cancel response that stopped a turn
errorobject | null{code, message, retryable} when failed or timed_out
metadataobjectEcho 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​

FieldTypeDescription
idstringMessage id
objectstringmessage
superanalyst_idstringdefault
session_idstringSession id
rolestringuser or assistant
contentarray[{"type": "text", "text": "…"}]; text is Markdown
citationsarrayCitation objects
artifactsarray[{name, file_id}]; file_id is null
created_atstring | nullISO-8601

Citation object​

FieldTypeDescription
typestringdocument or data. Skip types you don't recognize
idstringUnique within the message. Changes between reads, except datapoints
titlestring | nullDocument title, or the cited value or data view name
sourcestring | nullWhere a document comes from, such as a news source or broker
urlstring | nullOpens the citation in AlphaSense
document_idstring | nullThe cited document. null for data
pageinteger | null1-based page of the cited passage
statement_idsarrayThe cited statements, the main one first. Empty for data
broker_codestring | nullSet for broker research
broker_namestring | nullSet for broker research
text_rangesarray[{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​

FieldTypeDescription
idstringArtifact id, the same value as file_id
objectstringartifact
superanalyst_idstringdefault
session_idstring | nullSession that produced it
file_idstringUse with the /files endpoints
namestringFile name
typestringdashboard, report, slide, spreadsheet, other; may be absent
mime_typestring | nullFrom the file extension
size_bytesintegerOn retrieve only, and absent when unknown
updated_atstring | nullISO-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​

FieldTypeDescription
idstringFile id
objectstringfile
namestringFile or folder name
pathstringPath in the workspace
typestringfile or directory
mime_typestring | nullFrom the file extension
size_bytesinteger | nullnull for folders and some files
updated_atstring | nullISO-8601

Download content​

GET /artifacts/{artifact_id}/content and GET /files/{file_id}/content return 200:

FieldPresent whenDescription
idAlwaysThe artifact or file id
objectAlwaysartifact.content or file.content
deliveryAlwaysinline or too_large
encodinginlineutf-8 or base64
contentinline, utf-8Text content
content_base64inline, base64Base64-encoded bytes
errortoo_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": {}
}
}