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

# Quickstart

> Start an agent, poll for the result, follow up, and fetch the data.

Create an API key under **Settings → API keys** (you need a paid plan), then set it:

```bash theme={null}
export ORIGAMI_API_KEY=og_live_your_key_here
```

## Start an agent

Send a brief to [`POST /api/v2/agents`](/agents/reference/create-agent). This creates the
agent and starts its first run.

```bash theme={null}
curl -X POST https://origami.chat/api/v2/agents \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Find 20 SaaS founders in Austin who raised seed in the last 6 months." }'
```

You get `202 Accepted` with the run already `running`. Keep the `agent.id` and `run.id`
from the response — you'll need both.

## Poll for the result

The agent works in the background, so poll
[`GET /api/v2/agents/{id}/runs/{runId}`](/agents/reference/get-run) until `status` is no
longer `running`. Each `running` response carries a `Retry-After` header (15 seconds) —
wait that long between polls. Polling is free.

```bash theme={null}
while true; do
  RESP=$(curl -fsSL -D /tmp/headers \
    "https://origami.chat/api/v2/agents/$AGENT_ID/runs/$RUN_ID" \
    -H "Authorization: Bearer $ORIGAMI_API_KEY")
  [ "$(echo "$RESP" | jq -r '.status')" != "running" ] && break
  WAIT=$(grep -i '^retry-after:' /tmp/headers | awk '{print $2}' | tr -d '\r')
  sleep "${WAIT:-15}"
done
echo "$RESP" | jq .
```

## Read the response

When the run finishes, check two things on the run object:

1. **Questions** — if `todo.pendingQuestions[]` isn't empty, the agent needs you to
   clarify something before it continues. Answer it with a follow-up run.
2. **Results** — `response.tables[]` lists every table the agent built or changed, each
   with a `url` you can open in Origami.

```json theme={null}
{
  "status": "completed",
  "response": {
    "text": "Found 18 Austin SaaS founders who raised seed recently.",
    "tables": [
      { "id": "tbl_77", "name": "Austin Seed Founders", "leadCount": 18,
        "url": "https://origami.chat/workspace/ws_4a9b?table=tbl_77" }
    ]
  },
  "todo": { "pendingQuestions": [], "nextActions": [] }
}
```

## Follow up

To answer a question or ask for more, send another run to the same agent with
[`POST /api/v2/agents/{id}/runs`](/agents/reference/send-run). It keeps the same workspace
and conversation, so just say what's next.

```bash theme={null}
curl -X POST https://origami.chat/api/v2/agents/$AGENT_ID/runs \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "For each founder, also find their LinkedIn URL.",
        "focusTableIds": ["'$TABLE_ID'"] }'
```

Poll it the same way. Need to stop one mid-run? Call
[`POST /api/v2/agents/{id}/cancel`](/agents/reference/cancel-run) — whatever it built so
far is kept.

## Fetch the data

The agent stores results in tables. To pull the rows, hand the table id to
[`GET /api/v2/tables/{tableId}/rows`](/agents/reference/list-rows) — it's free and needs no
agent:

```bash theme={null}
curl "https://origami.chat/api/v2/tables/$TABLE_ID/rows" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"
```

Rows come back as typed cells by default. Add `?cells=flat` for the simpler
`{ slug: value }` shape, or `?format=csv` to download a spreadsheet. See the
[list rows reference](/agents/reference/list-rows) for filters, sorting, and pagination.

## Install the skill (optional)

If you drive this API from an AI coding assistant, install the [Origami skill](/agents/skill)
so it can handle the calls above for you.