Skip to main content
POST
/
stories
Create a pull story
curl --request POST \
  --url https://pullstory.com/api/v1/stories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "How auth works in this codebase",
  "summary": "JWT-based auth. Client hits /login, server validates credentials, issues JWT, and stores the session in Redis.",
  "files": [
    {
      "path": "src/auth/login.ts",
      "role": "Login entry point",
      "language": "typescript",
      "excerpt": "export async function POST(req) { ... }",
      "startLine": 12,
      "endLine": 47
    }
  ],
  "flow": [
    "<string>"
  ],
  "highlights": [
    "<string>"
  ]
}
'
{
  "id": "brief_0123abcd4567ef89",
  "url": "https://pullstory.com/s/brief_0123abcd4567ef89",
  "cached": false,
  "message": "Another request is already generating this story",
  "estimated_seconds": 90,
  "duration_seconds": 142,
  "scenes": 8,
  "title": "How auth works in this codebase",
  "error": "Story generation failed. Retry with a smaller brief."
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
title
string
required
Required string length: 3 - 140
Example:

"How auth works in this codebase"

​
summary
string
required
Required string length: 10 - 2000
Example:

"JWT-based auth. Client hits /login, server validates credentials, issues JWT, and stores the session in Redis."

​
files
object[]
required
Required array length: 1 - 20 elements
​
repo
object
​
flow
string[]
Required array length: 3 - 7 elements
Required string length: 3 - 500
​
highlights
string[]
Maximum array length: 8
Required string length: 3 - 200

Response

Cached story is ready

​
id
string
Example:

"brief_0123abcd4567ef89"

​
status
enum<string>
Available options:
generating,
ready,
failed
​
url
string
Example:

"https://pullstory.com/s/brief_0123abcd4567ef89"

​
cached
boolean
Example:

false

​
message
string
Example:

"Another request is already generating this story"

​
estimated_seconds
integer | null
Example:

90

​
duration_seconds
integer | null
Example:

142

​
scenes
integer | null
Example:

8

​
title
string
Example:

"How auth works in this codebase"

​
error
string | null
Example:

"Story generation failed. Retry with a smaller brief."