> ## Documentation Index > Fetch the complete documentation index at: https://predev.mintlify.site/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 . > 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: npx -y @predotdev/mcp setup adds it to every local coding agent with every pre.dev tool plus the user's own Chrome; the hosted server is https://api.pre.dev/mcp. Search these docs over MCP at https://docs.pre.dev/mcp. # Generate a Deep Spec > Generate a detailed implementation specification with milestones, stories, and granular subtasks. Deep Spec adds implementation detail to the planning pass. It accepts the same JSON and multipart fields as [Fast Spec](https://predev.mintlify.site/architect-agent/api/fast-spec.md). ## Example ```bash theme={null} curl --fail-with-body https://api.pre.dev/deep-spec \ -H "Authorization: Bearer $PREDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "Build an organization-scoped reporting platform with scheduled exports, audit logs, and role-based access.", "async": true }' ``` Save `specId` from the HTTP `200` response, then [poll its status](https://predev.mintlify.site/architect-agent/api/spec-status.md). Async submission is useful for detailed specifications because generation can outlast client and network timeouts. [Inputs and outputs](https://predev.mintlify.site/architect-agent/inputs-and-outputs.md) explains file uploads, existing context, JSON, Markdown, and graphs. Credit use is variable; inspect `creditsUsed` rather than assuming a fixed per-request price. Access and trial rules match [Fast Spec](https://predev.mintlify.site/architect-agent/api/fast-spec.md#access-and-cost). ## Errors | Status | When | | - | - | | `400` | No `input` or file, or `docURLs` is not an array of strings | | `401` | Missing or invalid key, or a personal key without a paid plan | | `402` | Not enough credits to start | | `403` | The specification trial is used up (Plus, or a team workspace without a plan), or the call came from a browser origin that is not allowed | | `500` | Generation failed. Check [history](https://predev.mintlify.site/architect-agent/api/list-specs.md) before retrying | Each status has an example body in the response examples. See [errors and retries](https://predev.mintlify.site/api-reference/errors.md). ## OpenAPI ````yaml api-reference/openapi.json POST /deep-spec openapi: 3.1.0 info: title: pre.dev API description: >- Public REST API for software specifications, browser automation, and credit balance. Base URL: https://api.pre.dev. MCP is documented separately at https://docs.pre.dev/mcp/tools. version: 1.1.0 contact: name: pre.dev Support url: https://pre.dev email: support@pre.dev license: name: Proprietary url: https://pre.dev/terms servers: - url: https://api.pre.dev description: Production API Server security: - apiKeyAuth: [] - xApiKey: [] tags: - name: Specifications - name: Browser Agents - name: Account paths: /deep-spec: post: tags: - Specifications summary: Generate a deep spec description: >- Supply JSON text or one multipart file. Use async=true for durable ID-based polling. Duplicate submissions create separate jobs; no idempotency key is supported. operationId: generateDeepSpec requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SpecRequest' example: input: >- Build a team task manager with projects, assignees, and due dates. async: true multipart/form-data: schema: $ref: '#/components/schemas/FileUploadRequest' responses: '200': description: >- Full result for synchronous requests; specId and pending status for asynchronous requests. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/SpecResponse' - type: object properties: status: type: string enum: - completed - $ref: '#/components/schemas/AsyncResponse' examples: submitted: summary: Async submission value: specId: 507f1f77bcf86cd799439011 status: pending completed: summary: Synchronous completion (illustrative) value: _id: 507f1f77bcf86cd799439011 endpoint: deep_spec status: completed success: true progress: 100 codingAgentSpecMarkdown: |- # Task manager Projects, assignments, and due dates. '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_input: summary: No input or file value: error: Invalid input message: >- Please provide either a file upload or input text describing your spec '401': description: Missing, invalid, or ineligible authentication. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_key: summary: No key sent value: error: Missing API key message: >- Please provide an API key via Authorization: Bearer header or x-api-key header invalid_key: summary: Unknown key value: error: Authentication failed message: Invalid API key no_subscription: summary: Personal key without a paid plan value: error: Authentication failed message: An active subscription is required for this endpoint '402': description: Insufficient balance or a billing gate. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Insufficient credits message: >- You have insufficient credits to generate a spec. Please purchase more credits or upgrade your plan. generationsAvailable: 0 '403': description: Access or trial eligibility denied. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Free trials exhausted message: >- You have used all 3 of your free API trials. Please subscribe to Solo Premium to continue. requiresSubscription: true trialsUsed: 3 maxTrials: 3 '500': description: Request failed. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Failed to generate deep spec message: Generation failed. Retry the request. x-codeSamples: - lang: cURL source: |- curl --fail-with-body https://api.pre.dev/deep-spec \ -H "Authorization: Bearer $PREDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "Build a team task manager with projects, assignees, and due dates.", "async": true }' components: schemas: SpecRequest: type: object required: - input properties: input: type: string description: >- Project requirements. Include goals, users, constraints, and acceptance criteria. minLength: 1 currentContext: type: string description: Existing system or specification as text; this is not a spec ID. docURLs: type: array items: type: string format: uri description: >- Public documentation URLs; retrieval and downloadable archives are best effort. async: type: boolean default: false description: >- Return {specId, status: pending} immediately. Poll GET /spec-status/{specId}. FileUploadRequest: type: object properties: file: type: string description: >- One PDF, DOC, DOCX, TXT, JPEG, or PNG file, at most 20 MiB. Send the matching MIME type. format: binary input: type: string description: Requirements, used alone or with the file. minLength: 1 currentContext: type: string description: Existing system context as text. docURLs: type: string description: JSON-encoded array of public documentation URLs. example: '["https://example.com/docs"]' async: type: boolean default: false anyOf: - required: - file - required: - input SpecResponse: type: object required: - status properties: _id: type: string description: 24-character record ID. pattern: ^[a-fA-F0-9]{24}$ created: type: string format: date-time endpoint: type: string enum: - fast_spec - deep_spec description: Which endpoint was used input: type: string description: Original input text provided status: type: string enum: - pending - processing - completed - failed success: type: boolean description: Whether the request succeeded uploadedFileShortUrl: anyOf: - type: string description: Short URL for uploaded file (if file was uploaded) - type: 'null' uploadedFileName: anyOf: - type: string description: Name of uploaded file (if file was uploaded) - type: 'null' humanSpecUrl: anyOf: - type: string format: uri description: >- URL where the human-readable spec is hosted (only when completed) - type: 'null' totalHumanHours: anyOf: - type: number description: >- Estimated total hours for a human to implement the spec (only when completed) - type: 'null' architectureInfographicUrl: anyOf: - type: string format: uri description: >- URL to a visual architecture infographic/diagram for the specification (only when completed) - type: 'null' codingAgentSpecUrl: anyOf: - type: string format: uri description: >- URL where the coding agent spec format is hosted (only when completed) - type: 'null' codingAgentSpecJson: anyOf: - $ref: '#/components/schemas/CodingAgentSpecJson' description: >- Structured JSON spec optimized for AI coding assistants (only when completed) - type: 'null' codingAgentSpecMarkdown: anyOf: - type: string description: >- Markdown spec optimized for AI coding assistants (only when completed) - type: 'null' humanSpecJson: anyOf: - $ref: '#/components/schemas/HumanSpecJson' description: >- Full structured JSON spec with hours, personas, and roles (only when completed) - type: 'null' humanSpecMarkdown: anyOf: - type: string description: >- Full markdown spec with all details for human review (only when completed) - type: 'null' executionTime: anyOf: - type: integer description: Processing time in milliseconds (only when completed or failed) - type: 'null' predevUrl: anyOf: - type: string format: uri description: pre.dev project URL (only when completed) - type: 'null' zippedDocsUrls: anyOf: - type: array description: >- Array of scraped documentation archives (only when completed). Empty array if no docURLs provided or scraping fails items: $ref: '#/components/schemas/ZippedDocsUrl' - type: 'null' errorMessage: anyOf: - type: string description: Error description (only when failed) - type: 'null' progress: anyOf: - type: number description: Completion percentage (0-100) while processing - type: 'null' creditsUsed: anyOf: - type: number description: Measured credit usage; estimates are not fixed charges. - type: 'null' userFlowGraph: anyOf: - $ref: '#/components/schemas/SpecGraph' description: >- User flow graph with nodes representing user stories/flows and edges showing navigation paths (only when completed) - type: 'null' architectureGraph: anyOf: - $ref: '#/components/schemas/SpecGraph' description: >- System architecture graph with C1/C2 level nodes and their relationships (only when completed) - type: 'null' enrichedTechStack: anyOf: - type: array items: $ref: '#/components/schemas/SpecEnrichedTechStackItem' description: >- Enriched tech stack with detailed reasons, descriptions, and alternatives for each technology (only when completed) - type: 'null' progressMessage: anyOf: - type: string description: >- Human-readable progress description (e.g. 'Generating architecture...') - type: 'null' currentContext: anyOf: - type: string description: Existing context supplied with generation. - type: 'null' specSource: anyOf: - type: string description: Origin of the request, such as api or mcp. - type: 'null' docURLs: anyOf: - type: array items: type: string format: uri - type: 'null' plan: $ref: '#/components/schemas/ProjectPlan' description: >- The project's verified plan, once the spec is completed and its project has something planned or built. Absent otherwise. description: >- Full specification/status record. Fields may be absent or null until available. Terminal status is completed or failed. executionTime is milliseconds. AsyncResponse: type: object required: - specId - status properties: specId: type: string description: 24-character record ID. pattern: ^[a-fA-F0-9]{24}$ status: type: string enum: - pending Error: type: object required: - error properties: error: type: string message: type: string description: Optional detail; not returned by every endpoint. code: type: string description: Machine-readable code when available. actionUrl: type: string format: uri requiresSubscription: type: boolean trialsUsed: type: integer maxTrials: type: integer additionalProperties: true CodingAgentSpecJson: type: object required: - executiveSummary - coreFunctionalities - techStack - milestones description: >- Simplified structured JSON for AI coding tools (excludes hours, personas, roles) properties: title: type: string description: Title of the specification executiveSummary: type: string description: Executive summary of the project coreFunctionalities: type: array items: $ref: '#/components/schemas/SpecCoreFunctionality' description: List of core functionalities techStack: type: array items: $ref: '#/components/schemas/SpecTechStackItem' description: Technology stack items techStackGrouped: type: object additionalProperties: type: array items: type: string description: Technology stack grouped by category milestones: type: array items: $ref: '#/components/schemas/CodingAgentMilestone' description: List of milestones HumanSpecJson: type: object required: - executiveSummary - coreFunctionalities - personas - techStack - milestones - totalHours - roles description: Full structured JSON with hours, personas, and roles for human review properties: title: type: string description: Title of the specification executiveSummary: type: string description: Executive summary of the project coreFunctionalities: type: array items: $ref: '#/components/schemas/SpecCoreFunctionality' description: List of core functionalities personas: type: array items: $ref: '#/components/schemas/SpecPersona' description: User personas techStack: type: array items: $ref: '#/components/schemas/SpecTechStackItem' description: Technology stack items techStackGrouped: type: object additionalProperties: type: array items: type: string description: Technology stack grouped by category milestones: type: array items: $ref: '#/components/schemas/HumanSpecMilestone' description: List of milestones with hours totalHours: type: number description: Total estimated hours for the project roles: type: array items: $ref: '#/components/schemas/SpecRole' description: Roles required for the project ZippedDocsUrl: type: object required: - platform - masterZipShortUrl properties: platform: type: string description: >- Hostname extracted from the documentation URL (e.g., 'stripe.com', 'docs.github.com') example: stripe.com masterZipShortUrl: type: string format: uri description: >- Short URL to download the zipped documentation archive for this platform masterMarkdownShortUrl: type: string format: uri description: Optional short URL to consolidated markdown file for this platform SpecGraph: type: object required: - nodes - edges properties: nodes: type: array items: $ref: '#/components/schemas/SpecGraphNode' description: Array of graph nodes edges: type: array items: $ref: '#/components/schemas/SpecGraphEdge' description: Array of graph edges SpecEnrichedTechStackItem: type: object required: - name - useFor - reason - description properties: name: type: string description: Name of the technology (e.g., React, PostgreSQL) useFor: type: string description: Category label (e.g., Frontend, Backend, Database) reason: type: string description: Why this technology was chosen for this specific project description: type: string description: Technical description of what the technology does link: type: string format: uri description: Official website or documentation URL helpfulLinks: type: array items: type: object properties: url: type: string format: uri description: URL to helpful resource description: type: string description: Description of the resource description: Array of helpful documentation and tutorial links alternatives: type: array items: type: object properties: name: type: string description: Name of the alternative technology link: type: string format: uri description: URL of the alternative technology description: type: string description: Description of the alternative description: Array of alternative technologies that could be used instead ProjectPlan: type: object description: >- A project's verified plan: what it is for, each feature's status from pre.dev's checks, progress, Ready to launch, where things live in the code, and the last change. required: - projectId - name - computedAt - codeVersion - intent - progress - features - readyToLaunch - appMap - lastRun properties: projectId: type: string pattern: ^[a-fA-F0-9]{24}$ name: anyOf: - type: string - type: 'null' computedAt: type: string format: date-time codeVersion: type: object required: - tree - short description: >- The code version the plan was computed at; null before any code exists. properties: tree: anyOf: - type: string - type: 'null' short: anyOf: - type: string - type: 'null' intent: anyOf: - type: object required: - text - proposedByPredev - removedSince properties: text: type: string description: What the app is for, in one paragraph. proposedByPredev: type: boolean description: >- Proposed by pre.dev from the request and not edited by the owner yet. removedSince: type: array items: type: string description: Taken out since, as the owner asked. - type: 'null' progress: type: object required: - basis - built - provenWorking - total - left - percent - proposed properties: basis: type: string enum: - features - stories - none built: type: integer provenWorking: type: integer description: Built and proven working by a check at the current code. total: type: integer left: type: integer percent: type: integer minimum: 0 maximum: 100 proposed: type: integer description: Suggested features, not counted until confirmed. features: type: array items: $ref: '#/components/schemas/ProjectPlanFeature' readyToLaunch: anyOf: - type: object required: - ready - items properties: ready: type: boolean items: type: array items: $ref: '#/components/schemas/ProjectPlanLaunchItem' - type: 'null' appMap: anyOf: - type: object required: - codeVersion - mappedAt - screens - endpoints - storage description: >- Where things live in the code. Each list holds at most 25 items; count is the full number. properties: codeVersion: anyOf: - type: string - type: 'null' mappedAt: anyOf: - type: string format: date-time - type: 'null' screens: type: object required: - count - items properties: count: type: integer items: type: array items: type: object required: - name - anchor - path properties: name: type: string anchor: anyOf: - type: string description: >- File and line in the code, for example server/routes.js:42, or the file alone. - type: 'null' path: anyOf: - type: string - type: 'null' endpoints: type: object required: - count - items properties: count: type: integer items: type: array items: type: object required: - name - anchor - writes properties: name: type: string anchor: anyOf: - type: string description: >- File and line in the code, for example server/routes.js:42, or the file alone. - type: 'null' writes: type: boolean description: The route changes stored data. storage: type: object required: - count - items properties: count: type: integer items: type: array items: type: object required: - name - anchor - kind - where properties: name: type: string anchor: anyOf: - type: string description: >- File and line in the code, for example server/routes.js:42, or the file alone. - type: 'null' kind: type: string where: type: string - type: 'null' lastRun: anyOf: - type: object required: - runId - kind - endedAt - codeVersion - filesChanged - appMap description: The last run that changed the code. properties: runId: type: string kind: type: string description: chat (an ask) or sprint (a build of planned work). endedAt: anyOf: - type: string format: date-time - type: 'null' codeVersion: type: object required: - before - after properties: before: anyOf: - type: string - type: 'null' after: anyOf: - type: string - type: 'null' filesChanged: type: object required: - count - paths properties: count: type: integer paths: type: array items: type: string appMap: anyOf: - type: object required: - added - removed - changed properties: added: type: array items: type: object required: - kind - name properties: kind: type: string name: type: string removed: type: array items: type: object required: - kind - name properties: kind: type: string name: type: string changed: type: array items: type: object required: - kind - name properties: kind: type: string name: type: string - type: 'null' - type: 'null' SpecCoreFunctionality: type: object required: - name - description properties: name: type: string description: Name of the core functionality description: type: string description: Description of the functionality priority: type: string enum: - High - Medium - Low description: Priority level of the functionality SpecTechStackItem: type: object required: - name - category properties: name: type: string description: Name of the technology category: type: string description: Category of the technology (e.g., Frontend, Backend, Database) CodingAgentMilestone: type: object required: - milestoneNumber - description - stories properties: milestoneNumber: type: integer description: Milestone number description: type: string description: Description of the milestone stories: type: array items: $ref: '#/components/schemas/CodingAgentStory' description: List of user stories in this milestone SpecPersona: type: object required: - title - description properties: title: type: string description: Title of the persona description: type: string description: Description of the persona primaryGoals: type: array items: type: string description: Primary goals of the persona painPoints: type: array items: type: string description: Pain points of the persona keyTasks: type: array items: type: string description: Key tasks of the persona HumanSpecMilestone: type: object required: - milestoneNumber - description - hours - stories properties: milestoneNumber: type: integer description: Milestone number description: type: string description: Description of the milestone hours: type: number description: Estimated hours for this milestone stories: type: array items: $ref: '#/components/schemas/HumanSpecStory' description: List of user stories in this milestone SpecRole: type: object required: - name - shortHand properties: name: type: string description: Full name of the role (e.g., Full Stack Developer) shortHand: type: string description: Short abbreviation for the role (e.g., FSD) SpecGraphNode: type: object required: - id - label properties: id: type: string description: Unique identifier for the node label: type: string description: Display label for the node type: type: string description: Node category; values depend on the graph. description: type: string description: Description of the node level: type: - number - string - 'null' description: >- Numeric flow depth or an architecture level such as C1 or C2, when available. hours: type: number description: Estimated hours for this node SpecGraphEdge: type: object required: - source - target properties: source: type: string description: Source node ID target: type: string description: Target node ID description: type: string description: Description of the relationship edgeType: type: string description: Type of edge relationship ProjectPlanFeature: type: object required: - id - name - status - statusText - scope - addedByAgent - stories - counted - removedParts properties: id: type: string name: type: string description: The feature in the owner's words. status: type: string enum: - works - built_not_checked - changed_since_check - needs_a_look - not_working - in_progress - planned - out_of_scope - removed description: >- From pre.dev's checks. works: a check of this feature passed at the current code. built_not_checked: the code is there, nothing has proven it. 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, not counted. removed: taken out because the owner asked, not counted. statusText: type: string description: The words pre.dev shows, for example "Works, checked 2 h ago". scope: type: string enum: - confirmed - proposed - out_of_scope description: >- proposed: suggested by pre.dev and not counted until the owner confirms it. addedByAgent: type: boolean stories: type: object required: - done - total properties: done: type: integer total: type: integer counted: type: boolean description: Counted in progress. removedParts: type: array items: type: string description: Parts the owner asked to take out of this feature. partOf: type: - object - 'null' required: - id - name properties: id: type: string name: type: string description: >- Set on work added to a feature that was already built: the feature it belongs to. The addition counts as its own item, listed right after that feature, until it is built, then folds back into the feature. null on a feature. ProjectPlanLaunchItem: type: object required: - id - label - state - detail - fix properties: id: type: string description: >- For example features_built, env_keys, data_persisted, sign_in, sample_data, publish_build, live_current, live_saves. label: type: string state: type: string enum: - ok - needs_fix - unknown - not_needed detail: anyOf: - type: string - type: 'null' fix: anyOf: - type: object required: - action - how properties: action: type: string how: type: string description: >- What to do in plain words: where to click on pre.dev, or what to ask a coding agent to do. - type: 'null' CodingAgentStory: type: object required: - title - subTasks properties: id: type: string description: Story identifier (e.g., US-001) title: type: string description: Title of the user story description: type: string description: Description of the user story acceptanceCriteria: type: array items: type: string description: List of acceptance criteria complexity: type: string description: Complexity estimate for the story subTasks: type: array items: $ref: '#/components/schemas/CodingAgentSubTask' description: List of subtasks for this story HumanSpecStory: type: object required: - title - hours - subTasks properties: id: type: string description: Story identifier (e.g., US-001) title: type: string description: Title of the user story description: type: string description: Description of the user story acceptanceCriteria: type: array items: type: string description: List of acceptance criteria hours: type: number description: Estimated hours for this story complexity: type: string description: Complexity estimate for the story subTasks: type: array items: $ref: '#/components/schemas/HumanSpecSubTask' description: List of subtasks for this story CodingAgentSubTask: type: object required: - description - complexity properties: id: type: string description: Subtask identifier description: type: string description: Description of the subtask complexity: type: string enum: - S - M - L - XL description: Complexity estimate HumanSpecSubTask: type: object required: - description - hours - complexity properties: id: type: string description: Subtask identifier description: type: string description: Description of the subtask hours: type: number description: Estimated hours for this subtask complexity: type: string description: Complexity estimate roles: type: array items: $ref: '#/components/schemas/SpecRole' description: Roles assigned to this subtask securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: API key description: >- Your pre.dev workspace API key (pdk_...) from Integrations, Built-in tab: https://pre.dev/projects/integrations?tab=built-in xApiKey: type: apiKey in: header name: x-api-key description: 'Alternative to Authorization: Bearer.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.