> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhizomeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a conversation

> Send a first message; research starts in the background

Starts a new conversation with one message and returns at once, while the research agent works on it. [Read the conversation](/api-reference/v3/conversations/get) with `wait` to get the answer. See [Conversations](/api-reference/v3/conversations/overview) for the whole flow.

## Headers

<ParamField header="Idempotency-Key" type="string">
  Makes a retry safe: a second request with the same key returns the
  conversation the first one created, with `200` instead of `202`, and starts
  nothing. 1 to 255 printable ASCII characters, no spaces. Use a new key, such
  as a UUID, for each message.
</ParamField>

## Request body

<ParamField body="message" type="string" required>
  The question. Specific questions get better answers: name the product area,
  indication, population or device characteristic, and spell out uncommon
  acronyms. Ask for a format (a Word report, an Excel table, a chart) and the
  agent produces it as a document.
</ParamField>

## Response

`202 Accepted` when the run started; `200 OK` for a retry with an `Idempotency-Key` already used.

<ResponseField name="conversation_id" type="string">
  The new conversation's id.
</ResponseField>

<ResponseField name="turn_index" type="integer">
  The message's turn in the conversation: `0` here.
</ResponseField>

<ResponseField name="status" type="string">
  `running` for a new run. For a retry, that turn's current status.
</ResponseField>

<ResponseField name="url" type="string">
  The conversation on rhizomeai.com, for the API key's owner.
</ResponseField>

## Errors

| Status | Code | Description |
| - | - | - |
| 400 | `invalid_request` | A body that isn't JSON, a missing or empty `message`, or a bad `Idempotency-Key` |
| 402 | `quota_exhausted` | The free plan's monthly questions are used up |
| 409 | `idempotency_key_in_use` | A request with this key is still being processed |
| 422 | `idempotency_key_reused` | The key was already used with a different message |
| 429 | `concurrent_conversations` | 3 conversations are already running. Retry after `Retry-After` seconds. |

Plus `401`, `413` and the rate limit's `429`, see [Errors](/api-reference/v3/conversations/overview#errors).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://rhizomeai.com/api/v3/conversations \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Idempotency-Key: 6f1c2a52-0d2e-4f43-9a51-3c8b2f1e7a90" \
    -d '{"message": "What De Novo requests has the FDA granted this year?"}'
  ```

  ```python Python theme={null}
  import uuid

  import requests

  response = requests.post(
      "https://rhizomeai.com/api/v3/conversations",
      headers={"x-api-key": "YOUR_API_KEY", "Idempotency-Key": str(uuid.uuid4())},
      json={"message": "What De Novo requests has the FDA granted this year?"},
  )
  response.raise_for_status()
  conversation_id = response.json()["conversation_id"]
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "conversation_id": "3b1f8c6e-2a4d-4c1e-9f2a-7d5e6b8c9a01",
    "turn_index": 0,
    "status": "running",
    "url": "https://rhizomeai.com/ask/v3/3b1f8c6e-2a4d-4c1e-9f2a-7d5e6b8c9a01"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.