Conversations - Rhizome AI

A conversation is the same thing as a conversation on rhizomeai.com: you send a question, Rhizome’s research agent searches the regulatory corpus, and you get back a cited answer, plus any reports or files it wrote. You can then ask follow-ups in the same conversation. Conversations started through the API appear in your account on rhizomeai.com, and conversations started there can be continued through the API. A research run takes 1 to 10 minutes, so the API is asynchronous:

Start a conversation. The call returns in about a second with a conversation_id and status: "running".
Read the conversation with wait=45 until status is no longer running. Each call holds up to 45 seconds and returns as soon as the run ends.
Read the answer and citations from the last turn. Fetch documents the agent wrote, if any.
Send a follow-up and poll again.

Nothing depends on keeping a connection open: the run continues on Rhizome’s side whatever your client does. To cancel one, stop it.

Statuses

A conversation’s status is its latest message’s status.

Status	Meaning
`running`	The agent is working on the latest message. Poll again.
`completed`	The latest turn has an answer.
`needs_input`	The agent asked a clarifying question instead of answering. The turn’s `question` has it; reply with a follow-up message.
`stopped`	The message was stopped. It is removed from `turns` and not counted against your plan, so the last turn is the previous answer, if any.
`error`	The run failed. `error` says why. You can send the message again as a follow-up.

Answers and citations

answer is markdown. Citations appear in it as [1], [2], matching the index of an entry in the turn’s citations. Citation numbers continue across the turns of a conversation. A link of the form doc:<id> in an answer points at an entry in the conversation’s documents. Each citation gives the source document’s name, dataset, date and page, and a url that opens the source in the conversation on rhizomeai.com.

Retries and idempotency

Send an Idempotency-Key header with each message to make retries safe. If a request times out and you retry it with the same key, you get the conversation or turn the first request created instead of a second run. Keys are scoped to your account; use a new one, such as a UUID, for each message. Reusing a key with a different message is a 422.

Plans and limits

Runs use the plan of the API key’s owner, as on rhizomeai.com: on a free plan each message counts against the monthly question limit, and a message over the limit is a 402. Downloading Word, Excel and PowerPoint files needs a paid plan. An account can have 3 conversations running at once, counting those started on rhizomeai.com. A message that would start a fourth is a 429 with code concurrent_conversations and a Retry-After header; send it again once a run finishes. Request bodies are JSON, up to 1 MB.

Errors

Errors return {"error": {"code", "message", "field", "request_id"}}, as on every API v3 endpoint; field names the value at fault when there is one. Every response has an X-Request-Id header. See Errors.

Status	Code	Description
400	`invalid_request`	A body that isn’t JSON, a missing or empty `message`, a bad parameter, or a malformed `Idempotency-Key`
401	`missing_api_key`, `invalid_api_key`	Missing or invalid API key
402	`quota_exhausted`	The free plan’s monthly questions are used up
403	`forbidden`	Downloading a Word, Excel or PowerPoint file needs a paid plan
404	`not_found`	No conversation or document with this id in your account
409	`turn_in_flight`	The conversation is still running the previous message
409	`idempotency_key_in_use`	A request with this key is still being processed. Retry shortly.
413	`payload_too_large`	The request body is over 1 MB
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.
429	`rate_limited`	Rate limit exceeded (50 requests/minute)

Example

Python

import time
import uuid

import requests

BASE = "https://rhizomeai.com/api/v3/conversations"
HEADERS = {"x-api-key": "YOUR_API_KEY"}


def ask(message, conversation_id=None):
    url = f"{BASE}/{conversation_id}/messages" if conversation_id else BASE
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    response = requests.post(url, headers=headers, json={"message": message})
    response.raise_for_status()
    conversation_id = response.json()["conversation_id"]

    while True:
        response = requests.get(
            f"{BASE}/{conversation_id}", headers=HEADERS, params={"wait": 45}
        )
        response.raise_for_status()
        conversation = response.json()
        if conversation["status"] in ("stopped", "error"):
            raise RuntimeError(conversation["error"] or "The message was stopped.")
        if conversation["status"] != "running":
            return conversation


conversation = ask("What De Novo requests has the FDA granted this year?")
turn = conversation["turns"][-1]
print(turn["answer"])
for citation in turn["citations"]:
    print(f"[{citation['index']}] {citation['name']}")

follow_up = ask("Which of them are cardiovascular devices?", conversation["conversation_id"])
print(follow_up["turns"][-1]["answer"])

​Statuses

​Answers and citations

​Retries and idempotency

​Plans and limits

​Errors

​Example