Guides

Brainstorming

Refine ambiguous queries with clarifying questions before running research

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

Step 1: Generate clarifying questions

$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:

1{
2  "id": "550e8400-e29b-41d4-a716-446655440000",
3  "query": "best practices for API authentication",
4  "status": "ready",
5  "questions": [
6    {
7      "id": "q1",
8      "question": "What type of application are you building?",
9      "options": [
10        {"key": "0", "text": "Web application"},
11        {"key": "1", "text": "Mobile app"},
12        {"key": "2", "text": "Server-to-server"},
13        {"key": "3", "text": "CLI tool"}
14      ]
15    },
16    {
17      "id": "q2",
18      "question": "What's your primary security concern?",
19      "options": [
20        {"key": "0", "text": "Ease of implementation"},
21        {"key": "1", "text": "Maximum security"},
22        {"key": "2", "text": "Scalability"},
23        {"key": "3", "text": "Compliance requirements"}
24      ]
25    }
26  ],
27  "created_at": "2025-01-11T10:30:00Z"
28}

Step 2: Submit research with answers

Using selected options (0-indexed)

$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:

$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:

$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

A brainstorm session can only be used once. After submitting research with a session, its status changes to “used” and cannot be reused.

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.