Chat - Docs

The Chat API lets you create and manage AI-powered chat sessions that answer financial questions using Aiera's data — earnings transcripts, filings, research reports, company documents, and Third Bridge expert interviews.

Each session is a multi-turn conversation. You create a session (optionally with an initial prompt), send follow-up prompts, and poll for the AI-generated responses. Responses arrive with inline citations that link back to the underlying source documents.

Session Lifecycle

When a prompt is sent, the session transitions through a sequence of statuses:

POST /chat-v1/sessions (with prompt)
         │
         ▼
  finding_sources  ──►  generating_response  ──►  active
         │                                          │
         │            (poll GET /sessions/{id})     │
         │                                          ▼
         │                                Response available
         │                                in messages array
         ▼
  finding_sources_error (on failure)

Status	Meaning
`active`	The session is ready. The most recent response is available.
`finding_sources`	The agent is selecting relevant documents for the current prompt.
`generating_response`	The agent is composing a response from the selected sources.
`cancelling_response`	A cancellation was requested for an in-flight response.
`finding_sources_error`	Source selection failed for the current prompt.
`generating_response_error`	Response generation failed for the current prompt.
`deleted`	The session has been soft-deleted.

Typical Workflow

Create a session with an initial prompt:

POST /chat-v1/sessions
{"prompt": "What were Tesla's Q1 2026 earnings highlights?"}

Poll for the response:
```
GET /chat-v1/sessions/{id}?include_messages=true
```
Repeat until status is active. The response is the last message with message_type: "response" — its blocks[].content contains the rendered answer, and blocks[].citations contains the inline source citations.

Send a follow-up prompt:

POST /chat-v1/sessions/{id}/prompt
{"content": "How does this compare to Q4 2025?"}

Poll again for the new response.