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

> ## Agent Instructions
> Follow the content contract in AGENTS.md.
> Treat text as the canonical explanation; video and screenshots enhance it.
> Do not publish unverified product behavior or duplicate an existing canonical article.

# Quickstart

> Create a StefanBrain API key and complete your first Agent Run with curl.

This quickstart sends one message to a StefanBrain Agent Run and waits for the finished response.

## Before you start

Create an API key in **Settings → Developers**. StefanBrain displays the full secret once, when you create it.

<Warning>
  Store the key as a secret. Do not commit it to your repository or include it in client-side code.
</Warning>

## Start a run

`"sync": true` holds the connection for up to about 90 seconds while the run completes:

```bash theme={"system"}
curl -X POST https://stefanbrain.com/api/developers/v1/runs \
  -H "Authorization: Bearer stefan_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Write three Meta ad hooks for a sleep supplement.",
    "sync": true
  }'
```

A run that finishes inside the synchronous wait window returns `200`:

```json theme={"system"}
{
  "object": "agent_run",
  "run_id": "run_550e8400e29b41d4a716446655440000",
  "chat": "chat_6ba7b8109dad41d180b400c04fd430c8",
  "status": "completed",
  "output": "...the finished hooks...",
  "structured_output": null
}
```

Read the finished response from `output`.

## If the run takes longer

When a run outlives the synchronous wait window, the same request returns `202` with its run identifier and lifecycle URLs. No work is lost. Set your HTTP client's timeout to 120 seconds so it receives that response.

Poll the run until its `status` is `completed`, `failed`, or `cancelled`:

```http theme={"system"}
GET /api/developers/v1/runs/{run_id}
```

Poll once every 3–10 seconds. Polling does not count against rate limits.

## Continue the conversation

Keep the `chat` identifier from the response. Send it with the next run to continue the same conversation:

```json theme={"system"}
{
  "message": "Turn the strongest hook into three body-copy variations.",
  "chat": "chat_6ba7b8109dad41d180b400c04fd430c8",
  "sync": true
}
```

Next, read [Agent Runs](/developers/agent-runs) for attachments, structured outputs, events, and cancellation.


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