Skip to main content
POST
cURL
Fast Spec is a concise planning pass. Compare Fast and Deep, or read inputs and outputs for context, uploads, and artifact formats.

Example

With async: true, HTTP 200 returns { "specId": "…", "status": "pending" }. Poll spec status using the returned ID. With async omitted or false, the connection waits for the completed specification; long requests can exceed your client’s timeout.

Access and failures

An accepted API key is required. Eligible accounts can use a limited specification trial; paid generation requires available credits. Trial exhaustion returns 403, insufficient credits 402, and invalid inputs 400. See authentication and errors. Generation cost varies with the request. The completed result includes creditsUsed when available. A network timeout does not prove generation stopped; check history before creating another spec.

Authorizations

Authorization
string
header
required

Use a pre.dev API key from https://pre.dev/projects/key.

Body

input
string
required

Project requirements. Include goals, users, constraints, and acceptance criteria.

Minimum string length: 1
currentContext
string

Existing system or specification as text; this is not a spec ID.

docURLs
string<uri>[]

Public documentation URLs; retrieval and downloadable archives are best effort.

async
boolean
default:false

Return {specId, status: pending} immediately. Poll GET /spec-status/{specId}.

Response

Full result for synchronous requests; specId and pending status for asynchronous requests.

Full specification/status record. Fields may be absent or null until available. Terminal status is completed or failed. executionTime is milliseconds.

status
enum<string>
required
Available options:
completed
_id
string

24-character record ID.

Pattern: ^[a-fA-F0-9]{24}$
created
string<date-time>
endpoint
enum<string>

Which endpoint was used

Available options:
fast_spec,
deep_spec
input
string

Original input text provided

success
boolean

Whether the request succeeded

uploadedFileShortUrl
string | null

Short URL for uploaded file (if file was uploaded)

uploadedFileName
string | null

Name of uploaded file (if file was uploaded)

humanSpecUrl
string<uri> | null

URL where the human-readable spec is hosted (only when completed)

totalHumanHours
number | null

Estimated total hours for a human to implement the spec (only when completed)

architectureInfographicUrl
string<uri> | null

URL to a visual architecture infographic/diagram for the specification (only when completed)

codingAgentSpecUrl
string<uri> | null

URL where the coding agent spec format is hosted (only when completed)

codingAgentSpecJson
object | null

Structured JSON spec optimized for AI coding assistants (only when completed)

codingAgentSpecMarkdown
string | null

Markdown spec optimized for AI coding assistants (only when completed)

humanSpecJson
object | null

Full structured JSON spec with hours, personas, and roles (only when completed)

humanSpecMarkdown
string | null

Full markdown spec with all details for human review (only when completed)

executionTime
integer | null

Processing time in milliseconds (only when completed or failed)

predevUrl
string<uri> | null

pre.dev project URL (only when completed)

zippedDocsUrls
object[] | null

Array of scraped documentation archives (only when completed). Empty array if no docURLs provided or scraping fails

errorMessage
string | null

Error description (only when failed)

progress
number | null

Completion percentage (0-100) while processing

creditsUsed
number | null

Measured credit usage; estimates are not fixed charges.

userFlowGraph
object | null

User flow graph with nodes representing user stories/flows and edges showing navigation paths (only when completed)

architectureGraph
object | null

System architecture graph with C1/C2 level nodes and their relationships (only when completed)

enrichedTechStack
object[] | null

Enriched tech stack with detailed reasons, descriptions, and alternatives for each technology (only when completed)

progressMessage
string | null

Human-readable progress description (e.g. 'Generating architecture...')

currentContext
string | null

Existing context supplied with generation.

specSource
string | null

Origin of the request, such as api or mcp.

docURLs
string<uri>[] | null