Skip to main content

​
1. Get an API key

Go to pullstory.com/dashboard/api-keys and click Create key. Your key starts with ps_live_ and is shown only once — copy it somewhere safe. 
export PULLSTORY_API_KEY="ps_live_..."

​
2. Create a pull story

Send a compact brief describing the code concept or flow to narrate. 
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: 
{
  "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. 
curl https://pullstory.com/api/v1/stories/brief_0123abcd4567ef89
Response once complete: 
{
  "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?

Use with Claude Code

Ask Claude Code to build the brief from real code.

Auto-generate via GitHub App

Install the GitHub App and every PR auto-generates.

Rate limits

How many requests per minute, how many minutes per month.

Error handling

Error codes, retry strategy, and failed status polling.