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

# Create a run

> POST /v1/research accepts a question, requires an idempotency key, and returns before the panel finishes.

`POST /v1/research` requires `Content-Type: application/json` and `Idempotency-Key`.

The body has two fields:

| Field | Meaning |
| - | - |
| `prompt` | The research question. Surrounding whitespace is trimmed. |
| `panel` | `wide`, `consensus`, or `seneca` |

The idempotency key is 1–255 characters: letters, numbers, or `.` `_` `:` `-`. Use one key per logical question. Save it with the run id.

```bash theme={null}
curl -sS -D - -X POST https://seneca-research.fly.dev/v1/research \
  -H "Authorization: Bearer $SENECA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: legal-tool-names-001" \
  -d '{"prompt": "We are designing a backend legal team AI Agent for a small law firm. We are testing which AI labs/model families have the fewest hallucinations in calling the correct tools:\n\n1. `obfuscate_pii` — Your definition here.\n2. `redact_personally_identifiable_information` — Your definition here.\n3. `remove_private_and_secret_customer_data` — Your definition here.\n\nThe purpose of this tool is to remove all the credit card info, phone numbers, addresses, and personal and private data before it gets ingested by an LLM. When the agent is reading the document this tool needs to be expressly called before it can read the document.\n\n**The PRIMARY RESEARCH TASK for which you are being called now:** Evaluate which of these tool names *YOU WOULD CHOOSE* in order to take this action, if you were the chosen LLM behind this agent. Then, after picking your tool_call name of choice, write your best, one sentence, description that would help a stateless AI know exactly what this tool does that would give the highest chance an LLM (like you!) calls it correctly in the future.\n\nIdentify ambiguities that could cause a model to select the wrong operation, propose a clear name choice from the tool names above, use both the number and the full name in snakecase. Then write your concise description below that as a separate answer.\n\n*SECONDARY TASK:* Explain what further execution testing would be necessary to validate your recommendations to reduce agentic hallucinations in this role.\n\nTERTIARY TASK:* Provide your best recommendation on a new type of tool design for an LLM producing JSON that will be parsed by a backend Python server which executes the actual action over software.", "panel": "wide"}'
```

## Response

A new run returns `202` and a body with `id`, `status`, `panel`, `credits_reserved`, `credits_charged`, and `progress`. Store `id`. The create connection does not stay open until the research finishes.

`credits_charged` is null while the run is in progress. `credits_reserved` is the panel price and does not change when the run finishes.

## Replay

The same `Idempotency-Key` with the same prompt and panel returns the original run for 24 hours. That response is `200`, the header `Idempotent-Replayed` is `true`, and the server does not create or charge a second run.

A different prompt or panel with that key returns `409` `idempotency_conflict`.

After 24 hours the same key starts a new paid run. A new key always can. Do not mint a new idempotency key only because the first response did not arrive.

<Warning>
  Do not retry `POST /v1/research` with a different `Idempotency-Key` merely because the client did not receive the first response.
</Warning>


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