> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Create an API key, an environment, and an agent, start a session with a task, and read the agent's reply, in the console or with cURL.
This quickstart runs the whole flow once: an API key, an environment, an agent, and a session that writes a short file. Each step shows the console and the matching cURL request, so you can follow either path. It takes about 10 minutes.
Sign in to the [Recursion console](https://recursion.labelbox.com). If this is your first sign-in, Recursion creates your tenant and its **Default** organization. You need the organization developer or admin role to create agents and environments and to start sessions; see [Organizations and roles](/recursion/organizations-and-roles). Your tenant needs credits to start a session. If it has none, a billing manager can add them on **Billing**; [Pricing](/recursion/pricing) explains what a session hour costs. Creating the agent and environment does not start paid work.
The sign-in page links to the [Terms of Service](https://docs.labelbox.com/page/terms-of-service), [Privacy Policy](https://docs.labelbox.com/page/privacy-notice), and [Copyright Dispute Policy](https://docs.labelbox.com/page/copyright-dispute-policy).
## 1. Create an API key
Skip this step if you use only the console.
1. In the [Recursion console](https://recursion.labelbox.com), open **Settings** and choose **API keys**, then click **Create key**.
2. Enter a **Name**, such as `quickstart`, and keep the default **Expires** value.
3. Set **Scope** to the **Default** organization, then click **Create key**.
4. Copy the key. It starts with `rma_` and is shown only once.
Store it in an environment variable for the requests below:
```bash theme={"theme":"css-variables"}
export RECURSION_API_KEY='rma_...'
```
An organization-scoped key needs no other header. See [API keys](/recursion/api-keys) for scopes and rotation.
## 2. Create an environment
An environment is where the session's sandbox runs. This one uses the default compute and has no internet access, which is enough for a task that only writes a file.
1. In the sidebar, click **Environments**, then click **Create environment**.
2. Enter a **Name**, such as `quickstart`.
3. Click **Create environment**.
```bash theme={"theme":"css-variables"}
curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/environments' \
-H "Authorization: Bearer $RECURSION_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name": "quickstart", "provider": "runs"}'
```
The response is the environment. Save its `environment_id`. Some fields are left out here:
```json theme={"theme":"css-variables"}
{
"organization_id": "org_01a08a705220724f9a2fe1bcd8638c9d",
"environment_id": "4c8e2a61-9b3f-4d70-a5e2-1f6b8c9d0e47",
"name": "quickstart",
"scope": "organization",
"provider": "runs",
"computer_use": false,
"created_at": "2026-09-25T14:02:11Z",
"updated_at": "2026-09-25T14:02:11Z"
}
```
See [Environments](/recursion/environments) to add internet access, a setup script, or more compute.
## 3. Create an agent
An agent is a model with a system prompt, saved as a version that sessions run.
1. In the sidebar, click **Agents**, then click **Create agent**.
2. Under **Choose a starting point**, click **Blank**.
3. Under **General**, enter a **Name**, choose a **Model** such as Claude Sonnet 5, and write a **System prompt**, such as `You are a concise writing assistant.`
4. Click **Create agent**.
List the models you can use, and pick one's `modelId`:
```bash theme={"theme":"css-variables"}
curl 'https://api.recursion.labelbox.com/managed-agents/v1/models' \
-H "Authorization: Bearer $RECURSION_API_KEY"
```
Create the agent with it in place of ``:
```bash theme={"theme":"css-variables"}
curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents' \
-H "Authorization: Bearer $RECURSION_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "Quickstart writer",
"model": "",
"system": "You are a concise writing assistant."
}'
```
The response is the agent with its first version. Save its `agent_id`. Some fields are left out here:
```json theme={"theme":"css-variables"}
{
"agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
"latest_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
"name": "Quickstart writer"
}
```
Your organization can use only the models that list returns. See [Agent setup](/recursion/agents) to add tools, skills, and credentials.
## 4. Start a session
A session runs the agent in the environment on the task in its opening message.
1. In the sidebar, click **Sessions**, then click **Launch session**.
2. Under **Configuration**, select your **Agent** and **Environment**.
3. Under **Task**, write the **Opening message**: `Write a four-line poem about sandboxes and save it as poem.md.`
4. Click **Launch session**. The session opens while its sandbox starts.
Replace the ids with the ones from steps 2 and 3.
```bash theme={"theme":"css-variables"}
curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \
-H "Authorization: Bearer $RECURSION_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quickstart-session-1' \
-d '{
"agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
"environment_id": "4c8e2a61-9b3f-4d70-a5e2-1f6b8c9d0e47",
"message": "Write a four-line poem about sandboxes and save it as poem.md."
}'
```
The request returns `202 Accepted` right away. The agent works in the background:
```json theme={"theme":"css-variables"}
{
"session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
"status_path": "/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53"
}
```
`Idempotency-Key` is required, so a retried request never starts a second session. Use a new key for each new session. If launch is refused because no credits are available, ask someone who manages billing to add credits, then try again. Your agent and environment remain saved.
## 5. Read the reply
Read the **Transcript** as the agent works. It shows messages, tool calls, and results. The session header shows its status and cost. Open the **Files** tab to preview or download `poem.md`.
Stream the agent's messages as they arrive. The stream closes when the session finishes.
```bash theme={"theme":"css-variables"}
curl -N 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events/stream?types=agent.message' \
-H "Authorization: Bearer $RECURSION_API_KEY"
```
Or list every recorded event after the session finishes:
```bash theme={"theme":"css-variables"}
curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events' \
-H "Authorization: Bearer $RECURSION_API_KEY"
```
In the event list, the agent's reply is a `message` event with `role` set to `assistant`. Some fields are left out here:
```json theme={"theme":"css-variables"}
{
"events": [
{
"event_id": "01997a3d-0b82-7c15-9a43-6e1f2d8c5b09",
"event_type": "message",
"role": "assistant",
"session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
"content": {
"blocks": [{ "type": "text", "text": "I saved the poem as poem.md." }]
},
"created_at": "2026-09-25T14:05:40Z"
}
],
"next_page_token": ""
}
```
When the agent finishes, the session's `status` is `completed` and `stop_reason` is `end_turn`. To continue the work, send a follow-up message. See [Sessions](/recursion/sessions) and [Events](/recursion/events).
In the console, you can also start from a template. On **Agents**, click **Create agent** and choose **Issue fixer** or **PR reviewer**. Enable the template's required tools on the organization GitHub connection, then choose the agent's tools and repositories. The template creates the agent and a matching environment, and opens the launch form with a suggested task.
## Next steps
Learn where agents, environments, credentials, and sessions live.
Learn the shared rules for retries, paging, and errors.
Let agents work in GitHub, Slack, and other apps.
Run the same agent on a schedule or when an event arrives.