Specs (Architect)
Get a project's plan
What a project is for, each feature's status from pre.dev's checks, progress, Ready to launch, and where things live in the code.
Every project a spec creates gets a verified plan as soon as the spec completes, and pre.dev keeps it current as the project is built. Read it before you change a project built with pre.dev: it says what is built, what is proven to work, what is left, and where to look in the code.
Pass exactly one of specId (from Fast Spec or Deep Spec) or projectId.
curl --fail-with-body "https://api.pre.dev/get-plan?specId=$SPEC_ID" \
-H "Authorization: Bearer $PREDEV_API_KEY"Add format=markdown to receive only the Markdown summary, ready to hand to a coding agent:
curl --fail-with-body "https://api.pre.dev/get-plan?projectId=$PROJECT_ID&format=markdown" \
-H "Authorization: Bearer $PREDEV_API_KEY"An organization key reads its organization’s projects; any other key reads only its own. Someone else’s ID returns 404, the same as an ID that does not exist.
What the plan says
| Field | Meaning |
|---|---|
intent | What the app is for, in one paragraph. proposedByPredev is true until the owner edits it. |
progress | built, provenWorking and total, plus left and percent. basis says what is counted: features, stories for a project whose tasks are not grouped into features yet, or none. Suggested features (proposed) are not counted until the owner confirms them. |
features | Each feature with its status, the words pre.dev shows for it, and its story counts. Work added to a feature that was already built is listed right after that feature with partOf naming it, and counts as its own item until it is built; on a feature, partOf is null. |
readyToLaunch | What is left before the app can go live, each item with a plain fix. |
appMap | Screens, API routes and stored data, each with its file and line (anchor). Each list holds at most 25 items; count is the full number. |
lastRun | The last run that changed the code: the files it changed and what it added, changed or removed. |
codeVersion | The code version the plan was computed at. |
A feature’s status comes from pre.dev’s checks:
| Status | Meaning |
|---|---|
works | A check of this feature passed at the current code |
built_not_checked | The code is there; nothing has proven it yet |
changed_since_check | Its files changed after its check passed |
needs_a_look | Its check failed the last time it ran |
not_working | Its check keeps failing |
in_progress, planned | Not built yet |
out_of_scope | Set outside the project’s scope; listed, not counted |
removed | Taken out because the owner asked; listed, not counted |
A spec that has just completed reads as all planned, with no appMap or lastRun until code exists. plan is null while a project has nothing planned or built yet. Keys appear by name only (for example, in a Ready to launch item that names a missing key), never their values.
Spec status carries the same plan once a spec is completed, and the MCP server has a matching get_plan tool.
Errors
| Status | When |
|---|---|
400 | Neither or both of specId and projectId, or an ID that is not valid |
401 | Missing or invalid key, or a personal key without a paid plan |
404 | An ID that is not yours, a spec with no project yet, or plans are turned off |
500 | Unexpected error |
Each status has an example body in the response examples. See errors and retries.
curl -X GET "https://api.pre.dev/get-plan"fetch("https://api.pre.dev/get-plan", { method: "GET"})package mainimport ( "fmt" "net/http" "io/ioutil")func main() { url := "https://api.pre.dev/get-plan" 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/get-plan"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/get-plan")) .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/get-plan");var responseBody = await response.Content.ReadAsStringAsync();use reqwest::{Result, Client};async fn main() -> Result<()> { let client = Client::new(); let url = "https://api.pre.dev/get-plan"; let res = client .get(url) .send() .await? .text() .await?; println!("{}", res); Ok(())}{ "projectId": "507f191e810c19729de860ea", "specId": null, "plan": { "projectId": "507f191e810c19729de860ea", "name": "Recipe Box", "computedAt": "2026-10-02T14:00:00.000Z", "codeVersion": { "tree": "a36fd496594c6417aa3ab8c6e534f2d7537d4a2e", "short": "a36fd49" }, "intent": { "text": "Recipe Box is for people who keep a small collection of recipes. They can browse recipes, add new ones, and mark a recipe as cooked.", "proposedByPredev": true, "removedSince": [] }, "progress": { "basis": "features", "built": 2, "provenWorking": 1, "total": 3, "left": 1, "percent": 67, "proposed": 0 }, "features": [ { "id": "feat_1a2b3c4d5e6f7a8b", "name": "Browse recipes", "status": "works", "statusText": "Works, checked 2 h ago", "scope": "confirmed", "addedByAgent": false, "stories": { "done": 2, "total": 2 }, "counted": true, "removedParts": [] }, { "id": "feat_2b3c4d5e6f7a8b9c", "name": "Add a recipe", "status": "built_not_checked", "statusText": "Built, not checked yet", "scope": "confirmed", "addedByAgent": false, "stories": { "done": 1, "total": 1 }, "counted": true, "removedParts": [] }, { "id": "feat_3c4d5e6f7a8b9c0d", "name": "Mark a recipe as cooked", "status": "planned", "statusText": "Planned, not built", "scope": "confirmed", "addedByAgent": false, "stories": { "done": 0, "total": 1 }, "counted": true, "removedParts": [] } ], "readyToLaunch": { "ready": false, "items": [ { "id": "features_built", "label": "Everything you asked for is built", "state": "needs_fix", "detail": "1 of 3 features is not built yet: Mark a recipe as cooked", "fix": null }, { "id": "data_persisted", "label": "Data is saved beyond one browser", "state": "ok", "detail": "Saved in a SQLite file on the server", "fix": null }, { "id": "live_current", "label": "Not published yet", "state": "needs_fix", "detail": null, "fix": { "action": "Publish", "how": "Publish the project from its page on pre.dev." } } ] }, "appMap": { "codeVersion": "a36fd49", "mappedAt": "2026-10-02T13:59:00.000Z", "screens": { "count": 2, "items": [ { "name": "Home", "path": "/", "anchor": "server/index.js:22" }, { "name": "New Recipe", "path": "/new", "anchor": "server/index.js:34" } ] }, "endpoints": { "count": 1, "items": [ { "name": "POST /new", "anchor": "server/index.js:38", "writes": true } ] }, "storage": { "count": 1, "items": [ { "name": "Recipes", "kind": "table (SQL)", "where": "in the database", "anchor": "server/db.js" } ] } }, "lastRun": { "runId": "6abfb8ac0e1670226a1ecd9b", "kind": "chat", "endedAt": "2026-10-02T13:56:00.000Z", "codeVersion": { "before": "e82c333", "after": "a36fd49" }, "filesChanged": { "count": 1, "paths": [ "server/views.js" ] }, "appMap": { "added": [ { "kind": "screen", "name": "/new" } ], "removed": [], "changed": [] } } }, "markdown": "# Plan for Recipe Box\n\nComputed 2026-10-02 14:00 UTC at code version a36fd49.\n\n## What it is for\n\nRecipe Box is for people who keep a small collection of recipes. ...\n\n## Progress\n\n2 of 3 features built (67%), 1 proven working by a check, 1 left.\n..."}Your pre.dev workspace API key (pdk_...) from Integrations, Built-in tab: https://pre.dev/projects/integrations?tab=built-in
In: header
Query Parameters
A specId from fast-spec or deep-spec.
^[a-fA-F0-9]{24}$A pre.dev project ID.
^[a-fA-F0-9]{24}$markdown returns the Markdown alone as text/markdown.
"json"Value in
- "json"
- "markdown"
Response Body
The plan, or plan null while the project has none yet.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Invalid request.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Missing, invalid, or ineligible authentication.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Not your project, no project yet, or plans are turned off.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Request failed.
TypeScript Definitions
Use the response body type in TypeScript.