> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pre.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agents: start with https://docs.pre.dev/agents.md, which has complete recipes, plan access, polling rules, errors and limits.
> Authenticate with the workspace API key (pdk_…) from Integrations → Built-in, sent as Authorization: Bearer <key>.
> REST API: https://api.pre.dev (OpenAPI: https://docs.pre.dev/api-reference/openapi.json). AI Gateway: https://api.pre.dev/v1, OpenAI-compatible (OpenAPI: https://docs.pre.dev/api-reference/ai-gateway.openapi.json).
> pre.dev MCP server: https://api.pre.dev/mcp. Search these docs over MCP at https://docs.pre.dev/mcp.

# 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](https://pre.dev/projects/integrations?tab=built-in) 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](/coding-agent/plans-and-credits#api-and-mcp-access).

## 1. Submit a specification

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

```bash theme={null}
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:

```json theme={null}
{
  "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](/architect-agent/inputs-and-outputs).

## 2. Poll the saved ID

Set `SPEC_ID` to the actual ID from your response:

```bash theme={null}
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](/architect-agent/sdks/python) or [Node SDK guide](/architect-agent/sdks/node).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.