Get specification status

Get a spec

curl --request GET \
  --url https://api.pre.dev/spec-status/{specId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.pre.dev/spec-status/{specId}', 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/spec-status/{specId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.pre.dev/spec-status/{specId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/spec-status/{specId}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "_id": "507f1f77bcf86cd799439011",
  "endpoint": "fast_spec",
  "status": "completed",
  "success": true,
  "progress": 100,
  "input": "Build a team task manager with projects, assignees, and due dates.",
  "codingAgentSpecMarkdown": "# Task manager\n\nProjects, assignments, and due dates."
}

GET

spec-status

{specId}

Get a spec

curl --request GET \
  --url https://api.pre.dev/spec-status/{specId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.pre.dev/spec-status/{specId}', 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/spec-status/{specId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.pre.dev/spec-status/{specId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/spec-status/{specId}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "_id": "507f1f77bcf86cd799439011",
  "endpoint": "fast_spec",
  "status": "completed",
  "success": true,
  "progress": 100,
  "input": "Build a team task manager with projects, assignees, and due dates.",
  "codingAgentSpecMarkdown": "# Task manager\n\nProjects, assignments, and due dates."
}

Use the specId returned by an async request. IDs are 24-character hexadecimal strings; copy the returned value rather than constructing one.

curl --fail-with-body "https://api.pre.dev/spec-status/$SPEC_ID" \
  -H "Authorization: Bearer $PREDEV_API_KEY"

Status lifecycle

Status	Meaning	Action
`pending`	Accepted and waiting to start	Keep polling
`processing`	Generation is underway	Display progress and keep polling
`completed`	Generation finished	Read the specification artifacts
`failed`	Generation failed	Read `errorMessage`

Poll at a bounded interval, for example five seconds, with an application deadline. The response identifies the request as _id, while the async submission names that value specId. progress is a percentage and progressMessage is display text. Completed requests report progress 100; a failed request can report progress 0. Progress is not a substitute for checking status.

Result fields

Full results can include both specification variants as JSON and Markdown, download URLs, graphs, technology explanations, archives, estimates, and credit usage. See inputs and outputs. Optional fields can be absent or null until their artifacts exist. A successful status lookup is HTTP 200 even when the generation status is failed.

The project’s plan

Once a spec is completed, the response can also carry plan: the project’s verified plan, with what the app is for, each feature’s status from pre.dev’s checks, progress, Ready to launch, and where things live in the code. It is the same object get a project’s plan returns. plan is absent before the spec completes and while its project has nothing planned or built.

Errors

Status	When
`400`	`specId` is not a valid ID
`401`	Missing or invalid key, or a personal key without a paid plan
`404`	No specification with this ID in your account or organization
`500`	Unexpected error

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

Path Parameters

specId

string

required

24-character record ID.

Pattern: ^[a-fA-F0-9]{24}$

Response

Current spec record.

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:

pending,

processing,

completed,

failed

_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

Get specification status

Status lifecycle

Result fields

The project’s plan

Errors

Authorizations

Path Parameters

Response

​Status lifecycle

​Result fields

​The project’s plan

​Errors

Authorizations

Path Parameters

Response

Status lifecycle

Result fields

The project’s plan

Errors