Quickstarts
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.