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

# Quickstart

> Create a run, point your agent at it, finish it, read the result.

The first environment is `offsite-planning`: a 14-person company in Oslo with a mailbox, Slack and calendars. Its task is "Schedule the Q4 offsite". The examples below were recorded against the engine. Long answers are cut with `...`.

**1. Create a run**

```bash theme={null}
curl -s -X POST $TESTWORLD_URL/v1/runs \
  -H "Authorization: Bearer $TESTWORLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment":"offsite-planning","task":"Schedule the Q4 offsite","idempotency_key":"quickstart-1"}'
```

```json theme={null}
{
  "id": "run_5296fdfe-b495-4c5b-8e30-8f767d4c47dc",
  "status": "created",
  "tools_url": "$TESTWORLD_URL/v1/runs/run_5296fdfe-.../tools",
  "mcp_url": "$TESTWORLD_URL/v1/runs/run_5296fdfe-.../tools/mcp",
  "token": "tw_run_6cdb03085eae616dbb91402d469952ef",
  "calls": 0,
  "...": "..."
}
```

Keep `id`, `tools_url` and `token`. The task title selects the task and its five checks.

**2. Point the agent at tools\_url**

The agent calls Gmail, Slack and Calendar under `tools_url`, on the real APIs' shape, with the run token as its bearer token.

```bash theme={null}
curl -s "$TOOLS_URL/gmail.googleapis.com/gmail/v1/users/me/messages?q=offsite" \
  -H "Authorization: Bearer $RUN_TOKEN"
```

An MCP client connects to `mcp_url` instead. See [Tools](https://docs.testworld.dev/tools.md).

**3. Finish the run**

```bash theme={null}
curl -s -X POST $TESTWORLD_URL/v1/runs/$RUN_ID/finish \
  -H "Authorization: Bearer $TESTWORLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output":"Booked Friday 13 November and told #leadership and #general."}'
```

The answer has `"status": "evaluating"`. A run you never finish ends after 10 minutes without a call and is scored the same.

**4. Read the result**

```bash theme={null}
curl -s $TESTWORLD_URL/v1/runs/$RUN_ID -H "Authorization: Bearer $TESTWORLD_KEY"
```

Poll until `status` is `done`. The run then holds the trace and the evaluation:

```json theme={null}
{
  "status": "done",
  "ended_by": "finish",
  "calls": 10,
  "trace": { "calls": ["..."] },
  "evaluation": { "score": 1, "passed": true, "checks": ["..."] }
}
```


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