Generate a Deep Spec

cURL

curl --fail-with-body https://api.pre.dev/deep-spec \
  -H "Authorization: Bearer $PREDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "Build a team task manager with projects, assignees, and due dates.",
  "async": true
}'

import requests

url = "https://api.pre.dev/deep-spec"

payload = { "input": "Build a team task manager with projects, assignees, and due dates." }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({input: 'Build a team task manager with projects, assignees, and due dates.'})
};

fetch('https://api.pre.dev/deep-spec', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pre.dev/deep-spec",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'Build a team task manager with projects, assignees, and due dates.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pre.dev/deep-spec"

	payload := strings.NewReader("{\n  \"input\": \"Build a team task manager with projects, assignees, and due dates.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pre.dev/deep-spec")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"Build a team task manager with projects, assignees, and due dates.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/deep-spec")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"Build a team task manager with projects, assignees, and due dates.\"\n}"

response = http.request(request)
puts response.read_body

{
  "specId": "507f1f77bcf86cd799439011",
  "status": "pending"
}

POST

deep-spec

cURL

curl --fail-with-body https://api.pre.dev/deep-spec \
  -H "Authorization: Bearer $PREDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "Build a team task manager with projects, assignees, and due dates.",
  "async": true
}'

import requests

url = "https://api.pre.dev/deep-spec"

payload = { "input": "Build a team task manager with projects, assignees, and due dates." }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({input: 'Build a team task manager with projects, assignees, and due dates.'})
};

fetch('https://api.pre.dev/deep-spec', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pre.dev/deep-spec",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'Build a team task manager with projects, assignees, and due dates.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pre.dev/deep-spec"

	payload := strings.NewReader("{\n  \"input\": \"Build a team task manager with projects, assignees, and due dates.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pre.dev/deep-spec")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"Build a team task manager with projects, assignees, and due dates.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/deep-spec")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"Build a team task manager with projects, assignees, and due dates.\"\n}"

response = http.request(request)
puts response.read_body

{
  "specId": "507f1f77bcf86cd799439011",
  "status": "pending"
}

Deep Spec adds implementation detail to the planning pass. It accepts the same JSON and multipart fields as Fast Spec.

Example

curl --fail-with-body https://api.pre.dev/deep-spec \
  -H "Authorization: Bearer $PREDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Build an organization-scoped reporting platform with scheduled exports, audit logs, and role-based access.",
    "async": true
  }'

Save specId from the HTTP 200 response, then poll its status. Async submission is useful for detailed specifications because generation can outlast client and network 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 rules match Fast Spec.

Errors

Status	When
`400`	No `input` or file, or `docURLs` is not an array of strings
`401`	Missing or invalid key, or a personal key without a paid plan
`402`	Not enough credits to start
`403`	The specification trial is used up (Plus, or a team workspace without a plan), or the call came from a browser origin that is not allowed
`500`	Generation failed. Check history before retrying

Each status has an example body in the response examples. See errors and retries.

Authorizations

Authorization

string

header

required

Your pre.dev workspace API key (pdk_...) from Integrations, Built-in tab: https://pre.dev/projects/integrations?tab=built-in

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.

Option 1
Option 2

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)

Show child attributes

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)

Show child attributes

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

Show child attributes

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)

Show child attributes

architectureGraph

object | null

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

Show child attributes

enrichedTechStack

object[] | null

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

Show child attributes

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

plan

object

The project's verified plan, once the spec is completed and its project has something planned or built. Absent otherwise.

Show child attributes

API

Specs (Architect)

Browser Agents

AI Gateway

SDKs

MCP

Generate a Deep Spec

Example

Errors

Authorizations

Body

Response

​Example

​Errors

Authorizations

Body

Response

Example

Errors