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

# Get specification status

> Retrieve generation progress, a failure message, or the complete specification artifacts.

Use the `specId` returned by an async request. IDs are 24-character hexadecimal strings; copy the returned value rather than constructing one.

```bash theme={null}
curl --fail-with-body "https://api.pre.dev/spec-status/$SPEC_ID" \
  -H "Authorization: Bearer $PREDEV_API_KEY"
```

## Status lifecycle

| Status       | Meaning                       | Action                            |
| ------------ | ----------------------------- | --------------------------------- |
| `pending`    | Accepted and waiting to start | Keep polling                      |
| `processing` | Generation is underway        | Display progress and keep polling |
| `completed`  | Generation finished           | Read the specification artifacts  |
| `failed`     | Generation failed             | Read `errorMessage`               |

Poll at a bounded interval, for example five seconds, with an application deadline. The response identifies the request as **`_id`**, while the async submission names that value **`specId`**.

`progress` is a percentage and `progressMessage` is display text. Completed requests report progress 100; a failed request can report progress 0. Progress is not a substitute for checking `status`.

## Result fields

Full results can include both specification variants as JSON and Markdown, download URLs, graphs, technology explanations, archives, estimates, and credit usage. See [inputs and outputs](/architect-agent/inputs-and-outputs). Optional fields can be absent or null until their artifacts exist.

A successful status lookup is HTTP `200` even when the generation status is `failed`. A malformed ID returns `400`; a missing or inaccessible request returns `404`.


## OpenAPI

````yaml api-reference/openapi.json GET /spec-status/{specId}
openapi: 3.1.0
info:
  title: pre.dev API
  description: >-
    Public REST API for software specifications, browser automation, proposal
    assessment, 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: Proposals
  - name: Account
paths:
  /spec-status/{specId}:
    get:
      tags:
        - Specifications
      summary: Get a spec
      description: >-
        Poll until status is completed or failed. Includes available artifacts;
        progress alone is not a completion signal.
      operationId: getSpecStatus
      parameters:
        - name: specId
          in: path
          required: true
          schema:
            type: string
            description: 24-character record ID.
            pattern: ^[a-fA-F0-9]{24}$
      responses:
        '200':
          description: Current spec record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid, or ineligible authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access or trial eligibility denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Record unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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'
      description: >-
        Full specification/status record. Fields may be absent or null until
        available. Terminal status is completed or failed. executionTime is
        milliseconds.
    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
    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
    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: Use a pre.dev API key from https://pre.dev/projects/key.
    xApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Alternative to Authorization: Bearer.'

````