> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.caesar.xyz/2025-11-27/documentation/guides/brainstorming/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caesar.xyz/_mcp/server.

# Brainstorming

Brainstorming helps improve research quality by generating clarifying questions before executing a query. This is useful when a query is ambiguous or could be interpreted multiple ways.

## When to use brainstorming

* The query is broad (e.g., "best practices for authentication")
* Multiple interpretations are possible (e.g., "compare React frameworks")
* You want more targeted, relevant results

## How it works

1. Submit your query to the brainstorm endpoint
2. Receive 2-7 clarifying questions with multiple-choice options
3. Collect answers from the user (or skip questions that aren't relevant)
4. Submit the research request with the brainstorm session and answers
5. The research runs with the additional context, producing more focused results

```mermaid
sequenceDiagram
    participant Client
    participant Caesar API

    Client->>Caesar API: POST /research/brainstorm
    Note right of Client: { "query": "..." }
    Caesar API-->>Client: Questions with options

    Note over Client: User selects answers<br />or provides custom text

    Client->>Caesar API: POST /research
    Note right of Client: { "query": "...",<br />"brainstorm_session_id": "...",<br />"answers": [...] }
    Caesar API-->>Client: Research results (enhanced with context)
```

## Step 1: Generate clarifying questions

```bash
curl -X POST https://api.caesar.xyz/research/brainstorm \
  -H "Authorization: Bearer csk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "best practices for API authentication"}'
```

**Response:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "best practices for API authentication",
  "status": "ready",
  "questions": [
    {
      "id": "q1",
      "question": "What type of application are you building?",
      "options": [
        {"key": "0", "text": "Web application"},
        {"key": "1", "text": "Mobile app"},
        {"key": "2", "text": "Server-to-server"},
        {"key": "3", "text": "CLI tool"}
      ]
    },
    {
      "id": "q2",
      "question": "What's your primary security concern?",
      "options": [
        {"key": "0", "text": "Ease of implementation"},
        {"key": "1", "text": "Maximum security"},
        {"key": "2", "text": "Scalability"},
        {"key": "3", "text": "Compliance requirements"}
      ]
    }
  ],
  "created_at": "2025-01-11T10:30:00Z"
}
```

## Step 2: Submit research with answers

### Using selected options (0-indexed)

```bash
curl -X POST https://api.caesar.xyz/research \
  -H "Authorization: Bearer csk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best practices for API authentication",
    "brainstorm_session_id": "550e8400-e29b-41d4-a716-446655440000",
    "answers": [
      {"question_id": "q1", "selected_option": 0},
      {"question_id": "q2", "selected_option": 1}
    ]
  }'
```

### Using custom text (overrides predefined options)

When the predefined options don't fit your needs, use `custom_text` to provide a free-form answer:

```bash
curl -X POST https://api.caesar.xyz/research \
  -H "Authorization: Bearer csk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best practices for API authentication",
    "brainstorm_session_id": "550e8400-e29b-41d4-a716-446655440000",
    "answers": [
      {"question_id": "q1", "custom_text": "Embedded IoT devices with limited resources"},
      {"question_id": "q2", "selected_option": 1}
    ]
  }'
```

### Skipping questions

To skip a question, simply omit it from the answers array. Only include answers for questions you want to influence the research:

```bash
curl -X POST https://api.caesar.xyz/research \
  -H "Authorization: Bearer csk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best practices for API authentication",
    "brainstorm_session_id": "550e8400-e29b-41d4-a716-446655440000",
    "answers": [
      {"question_id": "q1", "selected_option": 0}
    ]
  }'
```

In this example, only q1 is answered. Question q2 is skipped and won't influence the research context.

## Answer format

Each answer requires:

* `question_id` (required): The ID of the question being answered
* `selected_option` (optional): 0-based index into the options array
* `custom_text` (optional): Free-form text that overrides `selected_option`

You must provide either `selected_option` or `custom_text` (not both empty). If both are provided, `custom_text` takes precedence.

## Notes

> **Note**
>
> A brainstorm session can only be used once. After submitting research with a session, its status changes to "used" and cannot be reused.

> **Warning**
>
> If you provide a brainstorm session but skip all questions (empty answers array), the research will proceed but you'll receive a warning in the response.

**Optional usage:** Brainstorming is entirely optional. You can always call `POST /research` directly without a brainstorm session.

**No questions needed:** If your query is already specific enough, the brainstorm response may return an empty `questions` array. In this case, proceed directly to research without a session.

> Refine ambiguous queries with clarifying questions before running research