Create a Brainstorm Session | Caesar

import requests
url = "https://api.caesar.xyz/research/brainstorm"
payload = { "query": "What are the key factors affecting global semiconductor supply chains?" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "query": "What are the key factors affecting global semiconductor supply chains?",
  "questions": [
    {
      "id": "q1",
      "question": "What geographic regions are you most interested in?",
      "options": [
        {
          "key": "0",
          "text": "Global overview"
        },
        {
          "key": "1",
          "text": "Asia-Pacific (Taiwan, South Korea, Japan)"
        },
        {
          "key": "2",
          "text": "North America"
        },
        {
          "key": "3",
          "text": "Europe"
        }
      ]
    },
    {
      "id": "q2",
      "question": "What time period should the analysis focus on?",
      "options": [
        {
          "key": "0",
          "text": "Current state (2024-2025)"
        },
        {
          "key": "1",
          "text": "Historical trends (past 5 years)"
        },
        {
          "key": "2",
          "text": "Future projections"
        }
      ]
    },
    {
      "id": "q3",
      "question": "Which aspect of the supply chain interests you most?",
      "options": [
        {
          "key": "0",
          "text": "Manufacturing and fabrication"
        },
        {
          "key": "1",
          "text": "Raw materials and sourcing"
        },
        {
          "key": "2",
          "text": "Geopolitical factors"
        },
        {
          "key": "3",
          "text": "All aspects equally"
        }
      ]
    }
  ],
  "status": "ready",
  "created_at": "2025-11-27T12:00:00Z"
}

Generate clarification questions for a research query before starting the research. This is a two-phase workflow:

Call this endpoint with your query to get 2-7 multiple choice questions
Call POST /research with the brainstorm_session_id and your answers to start research with enhanced context

Questions are optional - you can skip any or all of them when calling /research.

Generate clarification questions for a research query before starting the research. This is a two-phase workflow: 1. Call this endpoint with your query to get 2-7 multiple choice questions 2. Call `POST /research` with the `brainstorm_session_id` and your answers to start research with enhanced context Questions are optional - you can skip any or all of them when calling `/research`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

querystringRequired

The research query to generate clarification questions for.

Response

Brainstorm session created with clarification questions.

idstringformat: "uuid"

Unique identifier for the brainstorm session.

querystring

The original research query.

questionslist of objects

Generated clarification questions (2-7 questions).

statusenum

Session status:

ready: Session can be used with /research
used: Session has already been used (single-use)

Session status: - `ready`: Session can be used with `/research` - `used`: Session has already been used (single-use)

Allowed values:

created_atdatetime

ISO 8601 timestamp when the session was created.

Authentication

Request

Response

Errors