Skip to main content
POST
cURL
Deep Spec adds implementation detail to the planning pass. It accepts the same JSON and multipart fields as Fast Spec.

Example

Save specId from the HTTP 200 response, then poll its status. Async submission is useful for detailed specifications because generation can outlast client or proxy timeouts. Inputs and outputs explains file uploads, existing context, JSON, Markdown, and graphs. Credit use is variable; inspect creditsUsed rather than assuming a fixed per-request price. Access and trial errors follow the same authentication and error rules as Fast 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