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

# Quickstart

> Generate your first pull story in under 2 minutes.

## 1. Get an API key

Go to [pullstory.com/dashboard/api-keys](https://pullstory.com/dashboard/api-keys) and click **Create key**. Your key starts with `ps_live_` and is shown only once — copy it somewhere safe.

```bash theme={null}
export PULLSTORY_API_KEY="ps_live_..."
```

## 2. Create a pull story

Send a compact brief describing the code concept or flow to narrate.

```bash theme={null}
curl https://pullstory.com/api/v1/stories \
  -H "Authorization: Bearer $PULLSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How auth works",
    "summary": "JWT-based auth. Client hits /login, server validates credentials, issues JWT, and stores the session in Redis.",
    "repo": { "owner": "acme", "name": "app" },
    "files": [
      {
        "path": "src/auth/login.ts",
        "role": "Login entry point",
        "language": "typescript",
        "excerpt": "export async function POST(req) { ... }",
        "startLine": 12,
        "endLine": 47
      }
    ],
    "flow": [
      "Client POSTs /login with email and password",
      "Server validates credentials",
      "JWT is returned as an httpOnly cookie"
    ]
  }'
```

You'll get back a story ID and a `generating` status:

```json theme={null}
{
  "id": "brief_0123abcd4567ef89",
  "status": "generating",
  "url": "https://pullstory.com/s/brief_0123abcd4567ef89",
  "cached": false
}
```

## 3. Poll until ready

Generation can take several minutes depending on brief size.

```bash theme={null}
curl https://pullstory.com/api/v1/stories/brief_0123abcd4567ef89
```

Response once complete:

```json theme={null}
{
  "id": "brief_0123abcd4567ef89",
  "status": "ready",
  "url": "https://pullstory.com/s/brief_0123abcd4567ef89",
  "duration_seconds": 142,
  "scenes": 8,
  "title": "How auth works"
}
```

## 4. Open the URL

`url` is the shareable pull story link. Send it to teammates, embed it in docs, or drop it in Slack.

## What's next?

<CardGroup cols={2}>
  <Card title="Use with Claude Code" icon="terminal" href="/integrations/claude-code">
    Ask Claude Code to build the brief from real code.
  </Card>

  <Card title="Auto-generate via GitHub App" icon="github" href="/integrations/github-app">
    Install the GitHub App and every PR auto-generates.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/rate-limits">
    How many requests per minute, how many minutes per month.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/errors">
    Error codes, retry strategy, and failed status polling.
  </Card>
</CardGroup>