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

# Generate a Fast Spec

> Generate a specification with architecture, milestones, user stories, and acceptance criteria.

Fast Spec is a concise planning pass. [Compare Fast and Deep](/coding-agent/specifications/fast-vs-deep), or read [inputs and outputs](/architect-agent/inputs-and-outputs) for context, uploads, and artifact formats.

## Example

```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": "Add CSV exports to the reporting dashboard.",
    "currentContext": "Existing TypeScript app with a reports API and organization-scoped access.",
    "async": true
  }'
```

With `async: true`, HTTP `200` returns `{ "specId": "…", "status": "pending" }`. Poll [spec status](/architect-agent/api/spec-status) using the returned ID. With async omitted or false, the connection waits for the completed specification; long requests can exceed your client's timeout.

## Access and failures

An accepted API key is required. Eligible accounts can use a limited specification trial; paid generation requires available credits. Trial exhaustion returns `403`, insufficient credits `402`, and invalid inputs `400`. See [authentication](/api-reference/authentication) and [errors](/api-reference/errors).

Generation cost varies with the request. The completed result includes `creditsUsed` when available. A network timeout does not prove generation stopped; check history before creating another spec.


## OpenAPI

````yaml api-reference/openapi.json POST /fast-spec
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:
  /fast-spec:
    post:
      tags:
        - Specifications
      summary: Generate a fast 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: generateFastSpec
      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: fast_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'
        '401':
          description: Missing, invalid, or ineligible authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient balance or a billing gate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access or trial eligibility denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: cURL
          source: |-
            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, 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'
      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
    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.'

````