Architect quickstart

Generate a specification asynchronously, poll to completion, and read its Markdown and JSON.

By the end of this guide, you will have a saved specification ID and a completed implementation plan in Markdown and JSON.

Before you start

Copy your pre.dev API key from Integrations → Built-in in the dashboard: pre.dev/projects/integrations for your personal workspace, or the Integrations page of a team workspace. Workspace keys start with pdk_.

Make it available as PREDEV_API_KEY. Specification generation needs a plan that includes the Architect API; see API and MCP access.

1. Submit a specification

Use async mode so generation can continue without keeping your HTTP connection open:

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

The API returns HTTP 200 with an ID:

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

To request a deeper implementation breakdown, use /deep-spec with the same body. For feature work, include currentContext describing the existing stack and architecture. See inputs and outputs.

2. Poll the saved ID

Set SPEC_ID to the actual ID from your response:

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

Poll every few seconds with a deadline:

status	Meaning	Next step
pending	The request is saved	Keep polling the same ID
processing	Generation is running; progress and progressMessage describe the work	Keep polling; do not submit another spec to check progress
completed	The artifacts are ready	Stop polling and read the result
failed	Generation did not complete	Stop polling and read errorMessage; an HTTP 200 status response does not mean generation succeeded

3. Read the result

When status is completed, use:

Field	Purpose
codingAgentSpecMarkdown / codingAgentSpecJson	Implementation context for agents
humanSpecMarkdown / humanSpecJson	Human review, personas, roles, and estimates
userFlowGraph / architectureGraph	Nodes and edges for visualization
predevUrl	Open the project in the web workspace
creditsUsed	Actual specification credit usage

If status is failed, read errorMessage. Do not treat an HTTP 200 status response as proof of successful generation.

For a complete polling example, use the Python SDK guide or Node SDK guide.