> ## 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.

# Quickstart

> Check the account, create a research run over REST, poll it, and read the compact report.

Seneca accepts research over the REST API and over [MCP](/mcp-server). This page is the REST path. It takes a workspace from an API key to a stored research report. The create request returns as soon as the run is accepted. Poll with a new request. Do not keep the original POST open. MCP uses the same key, panels, and credit ledger.

## Prerequisites

* A Seneca account at [seneca.professionalaiagents.com](https://seneca.professionalaiagents.com)
* An API key from the [Developers page](https://seneca.professionalaiagents.com/developers#api-keys)
* An entitled workspace with enough credits for the panel you choose

Reads work without an active subscription. Paid research requires `entitled: true` and enough `available_credits`.

## Launch a run

<Steps>
  <Step title="Store the key">
    The secret starts with `seneca_sk_` and is shown once. Keep it in an environment variable.

    ```bash theme={null}
    export SENECA_API_KEY="seneca_sk_..."
    ```
  </Step>

  <Step title="Read the account">
    ```bash theme={null}
    curl https://seneca-research.fly.dev/v1/account \
      -H "Authorization: Bearer $SENECA_API_KEY"
    ```

    Confirm `entitled` is true and `available_credits` covers the panel. [Wide Research](/research/depths) reserves 15 credits.
  </Step>

  <Step title="Create research">
    `POST /v1/research` requires `Content-Type: application/json` and `Idempotency-Key`. A new run returns `202`. Store `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"}'
    ```
  </Step>

  <Step title="Poll until the run finishes">
    Research often takes several minutes.

    ```bash theme={null}
    curl -sS https://seneca-research.fly.dev/v1/research/$RUN_ID \
      -H "Authorization: Bearer $SENECA_API_KEY"
    ```

    Stop when `status` is `completed`, `partial`, or `failed`. In-progress statuses are `queued`, `running`, and `synthesizing`.
  </Step>

  <Step title="Read the report">
    Quote the URL so the shell does not treat `?` as a pattern.

    ```bash theme={null}
    curl -sS "https://seneca-research.fly.dev/v1/research/$RUN_ID/result?detail=compact" \
      -H "Authorization: Bearer $SENECA_API_KEY"
    ```

    Read the finding from `report.answer`. This read does not start research and does not write a credit charge.
  </Step>
</Steps>

<Note>
  If the create response is lost, repeat the same POST with the same `Idempotency-Key`, prompt, and panel. For 24 hours the server returns the original run and does not charge again.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="MCP" icon="plug" href="/mcp-server">
    Call the same research engine from a Streamable HTTP client.
  </Card>

  <Card title="Polling" icon="clock" href="/research/polling">
    Statuses, phase, and progress counts.
  </Card>

  <Card title="Results" icon="file-text" href="/research/results">
    Full and compact reports.
  </Card>

  <Card title="Agents" icon="bot" href="/agents">
    A REST lifecycle, plus MCP for an agent client.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/errors">
    Read `error.code` before you retry.
  </Card>
</CardGroup>


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