Create Chat Session

Create a new chat session. If a prompt is supplied in the request body, the first message is sent immediately and the session begins generating a response — the new session is returned with status finding_sources and an initial_prompt field echoing the submitted prompt.

POST /chat-v1/sessions

Request Body

Field	Type	Required	Description
title	string	no	Optional session title. If omitted, a title is generated.
prompt	string	no	If provided, the first message is sent immediately and the session begins generating a response.
sources	array	no	Optional initial sources array to scope the session to specific documents, events, or companies. See Chat for source shape.

NOTE

When prompt is provided, the session starts in finding_sources status. Poll GET /chat-v1/sessions/{id}?include_messages=true until status is active to retrieve the response.
The initial_prompt field in the response is only present when a prompt was included in the request.

Request

POST https://premium.aiera.com/api/chat-v1/sessions
Content-Type: application/json

{
  "title": "API Docs Example",
  "prompt": "What were the key takeaways from Tesla Q1 2026 earnings?"
}

Response (201)

{
  "id": 2229,
  "title": "API Docs Example",
  "title_status": "user",
  "status": "finding_sources",
  "active_message_id": null,
  "messages": null,
  "sources": null,
  "model_generation_params": null,
  "model_id": null,
  "user_id": 9846,
  "votes": null,
  "created_at": "2026-04-29T20:52:25Z",
  "updated_at": "2026-04-29T20:52:25Z",
  "initial_prompt": {
    "id": 20712,
    "session_id": 2229,
    "message_type": "prompt",
    "content": "What were the key takeaways from Tesla Q1 2026 earnings?",
    "ordinal_id": null,
    "runner_version": null,
    "tool_settings": null,
    "user_id": 9846,
    "created_at": "2026-04-29T20:52:26Z",
    "updated_at": "2026-04-29T20:52:26Z"
  }
}

Code Samples

Bash

curl --request POST \
  --url 'https://premium.aiera.com/api/chat-v1/sessions' \
  --header 'X-API-Key: your-rest-api-key' \
  --header 'Content-Type: application/json' \
  --data '{"title": "API Docs Example", "prompt": "What were the key takeaways from Tesla Q1 2026 earnings?"}'

Python

import requests
requests.post(
    "https://premium.aiera.com/api/chat-v1/sessions",
    headers={"X-API-Key": "your-rest-api-key"},
    json={
        "title": "API Docs Example",
        "prompt": "What were the key takeaways from Tesla Q1 2026 earnings?",
    },
)