Skip to main content
pre.dev
Changelogpre.devStart building
Start with pre.devBuild with pre.devAPI & SDKsLabs

Specs (Architect)

Get specification status

Retrieve generation progress, a failure message, or the complete specification artifacts.

gethttps://api.pre.dev/spec-status/{specId}Try it

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

StatusMeaningAction
pendingAccepted and waiting to startKeep polling
processingGeneration is underwayDisplay progress and keep polling
completedGeneration finishedRead the specification artifacts
failedGeneration failedRead 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

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

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

curl -X GET "https://api.pre.dev/spec-status/string"
fetch("https://api.pre.dev/spec-status/string", {  method: "GET"})
package mainimport (  "fmt"  "net/http"  "io/ioutil")func main() {  url := "https://api.pre.dev/spec-status/string"  req, _ := http.NewRequest("GET", url, nil)  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}
import requestsurl = "https://api.pre.dev/spec-status/string"response = requests.request("GET", url)print(response.text)
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.pre.dev/spec-status/string"))  .GET()  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}
using System;using System.Net.Http;using System.Text;var client = new HttpClient();var response = await client.GetAsync("https://api.pre.dev/spec-status/string");var responseBody = await response.Content.ReadAsStringAsync();
use reqwest::{Result, Client};async fn main() -> Result<()> {  let client = Client::new();  let url = "https://api.pre.dev/spec-status/string";  let res = client    .get(url)    .send()    .await?    .text()    .await?;  println!("{}", res);  Ok(())}
{  "_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}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

specId*string

24-character record ID.

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

Response Body

application/json

Current spec record.

TypeScript Definitions

Use the response body type in TypeScript.

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

application/json

application/json

application/json

application/json

application/json

Was this page helpful?

postGenerate a Deep Spec

Previous Page

getGet a project's plan

Next Page