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

# Get Project Status

> Retrieves the current status of a project and returns results when complete.

Retrieve the current status of a project and get results when generation is complete.

## Request

<RequestExample>
  ```bash theme={null}
  curl https://api.initrepo.com/v1/projects/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer ir_live_your_api_key" \
    -H "API-Version: v1.0"
  ```
</RequestExample>

## Path Parameters

<ParamField path="projectId" type="string" required>
  The unique identifier of the project to retrieve.
</ParamField>

## Response - In Progress

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "in_progress",
      "estimatedCompletionMs": 120000
    }
  }
  ```

  **Response Headers:**

  ```
  HTTP/1.1 200 OK
  API-Version: v1.0
  API-Supported-Versions: v1.0
  API-Latest-Version: v1.0
  X-Request-ID: req_1234567890
  X-RateLimit-Remaining: 98
  X-RateLimit-Reset: 1699123456
  ```
</ResponseExample>

## Response - Completed

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "project": {
        "name": "AI-Commerce Platform",
        "description": "Modern e-commerce platform with AI-powered recommendations",
        "type": "web",
        "questionnaire": {
          "targetAudience": "Small to medium online retailers",
          "monetization": "SaaS subscription model",
          "techStack": ["React", "Node.js", "PostgreSQL", "Redis"]
        },
        "documents": [
          {
            "type": "README",
            "filename": "README.md",
            "content": "# AI-Commerce Platform\n\nA modern e-commerce solution...",
            "generated_at": "2024-01-15T10:30:00Z",
            "stage": "project-brief",
            "tokens_used": 1200
          },
          {
            "type": "Product Requirements",
            "filename": "PRD.md",
            "content": "# Product Requirements Document\n\n## Overview...",
            "generated_at": "2024-01-15T10:32:00Z",
            "stage": "requirements",
            "tokens_used": 2100
          }
        ]
      },
      "metadata": {
        "creditsConsumed": 15000,
        "generationTimeMs": 165000,
        "documentsGenerated": 10
      }
    }
  }
  ```
</ResponseExample>

## Response - Failed

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "failed",
      "error": {
        "code": "generation_failed",
        "message": "Project generation failed due to AI service timeout. Credits refunded."
      }
    }
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="success" type="boolean">
  Indicates if the request was successful.
</ResponseField>

<ResponseField name="data.projectId" type="string">
  Unique identifier of the project.
</ResponseField>

<ResponseField name="data.status" type="string">
  Current status of the project. Values: `in_progress`, `completed`, `failed`.
</ResponseField>

<ResponseField name="data.estimatedCompletionMs" type="integer">
  Estimated time remaining in milliseconds (only present when in\_progress).
</ResponseField>

<ResponseField name="data.project" type="object">
  Complete project data (only present when completed).
</ResponseField>

<ResponseField name="data.project.name" type="string">
  Generated project name.
</ResponseField>

<ResponseField name="data.project.description" type="string">
  Generated project description.
</ResponseField>

<ResponseField name="data.project.type" type="string">
  Project type (web, mobile, mcp).
</ResponseField>

<ResponseField name="data.project.questionnaire" type="object">
  AI-generated project questionnaire data.
</ResponseField>

<ResponseField name="data.project.documents" type="array">
  Array of generated documents.
</ResponseField>

<ResponseField name="data.project.documents[].type" type="string">
  Document type (README, Product Requirements, etc.).
</ResponseField>

<ResponseField name="data.project.documents[].filename" type="string">
  Document filename.
</ResponseField>

<ResponseField name="data.project.documents[].content" type="string">
  Document content in markdown format.
</ResponseField>

<ResponseField name="data.project.documents[].generated_at" type="string">
  ISO 8601 timestamp of document generation.
</ResponseField>

<ResponseField name="data.project.documents[].stage" type="string">
  Generation stage (project-brief, requirements, etc.).
</ResponseField>

<ResponseField name="data.project.documents[].tokens_used" type="integer">
  AI tokens used to generate this document.
</ResponseField>

<ResponseField name="data.metadata" type="object">
  Generation metadata (only present when completed).
</ResponseField>

<ResponseField name="data.metadata.creditsConsumed" type="integer">
  Total credits consumed for this project.
</ResponseField>

<ResponseField name="data.metadata.generationTimeMs" type="integer">
  Total time spent generating in milliseconds.
</ResponseField>

<ResponseField name="data.metadata.documentsGenerated" type="integer">
  Number of documents generated.
</ResponseField>

<ResponseField name="data.error" type="object">
  Error details (only present when failed).
</ResponseField>

<ResponseField name="data.error.code" type="string">
  Error code identifier.
</ResponseField>

<ResponseField name="data.error.message" type="string">
  Human-readable error message.
</ResponseField>

## Error Responses

### Not Found Error (404)

<ErrorExample>
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "RESOURCE_NOT_FOUND",
      "message": "Project with specified ID does not exist",
      "request_id": "req_1234567890",
      "documentation": "https://docs.initrepo.com/api/get",
      "details": {
        "resource_type": "project",
        "resource_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }
  ```
</ErrorExample>

### Authentication Error (401)

<ErrorExample>
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "AUTHENTICATION_FAILED",
      "message": "Invalid API key provided",
      "request_id": "req_1234567890",
      "documentation": "https://docs.initrepo.com/api/authentication",
      "details": {
        "field": "authorization_header",
        "issue": "invalid_key"
      }
    }
  }
  ```
</ErrorExample>

### Rate Limit Exceeded (429)

<ErrorExample>
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded. Try again in 60 seconds.",
      "request_id": "req_1234567890",
      "documentation": "https://docs.initrepo.com/api/rate-limits",
      "details": {
        "retry_after": 60,
        "limit": 100,
        "window": "1 minute"
      }
    }
  }
  ```
</ErrorExample>

## Rate Limits

This endpoint is rate limited to 100 requests per minute per API key.

## Usage Notes

* **Polling**: For in-progress projects, poll this endpoint every 10-30 seconds
* **Exponential Backoff**: Implement exponential backoff for failed requests
* **Caching**: Cache completed project data to avoid unnecessary API calls
* **Error Handling**: Always handle rate limiting (429) and authentication errors (401)


## OpenAPI

````yaml GET /api/v1/projects/{projectId}
openapi: 3.1.0
info:
  title: InitRepo API
  description: >-
    InitRepo REST API for programmatic project generation with AI-powered
    workflows. Supports versioning via URL path, Accept header, or API-Version
    header.
  version: 1.0.0
  contact:
    name: InitRepo Support
    email: support@initrepo.com
    url: https://initrepo.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-logo:
    url: https://initrepo.com/logo.svg
servers:
  - url: https://api.initrepo.com/v1
    description: Production API
  - url: https://dev-api.initrepo.com/v1
    description: Development API
security:
  - bearerAuth: []
paths:
  /api/v1/projects/{projectId}:
    get:
      tags:
        - Projects
      summary: Get project status
      description: >-
        Retrieves the current status of a project and returns results when
        complete.
      operationId: getProjectStatus
      parameters:
        - name: projectId
          in: path
          required: true
          description: The unique identifier of the project
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Project status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectStatusResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Project doesn't exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ProjectStatusResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            projectId:
              type: string
              format: uuid
              example: 550e8400-e29b-41d4-a716-446655440000
            status:
              type: string
              enum:
                - in_progress
                - completed
                - failed
              example: completed
            estimatedCompletionMs:
              type: integer
              example: 120000
            project:
              type: object
              properties:
                name:
                  type: string
                  example: AI-Commerce Platform
                description:
                  type: string
                  example: Modern e-commerce platform with AI-powered recommendations
                type:
                  type: string
                  example: web
                documents:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        example: README
                      filename:
                        type: string
                        example: README.md
                      content:
                        type: string
                        example: |-
                          # AI-Commerce Platform

                          A modern e-commerce solution...
                      generated_at:
                        type: string
                        format: date-time
                        example: '2024-01-15T10:30:00Z'
                      stage:
                        type: string
                        example: project-brief
                      tokens_used:
                        type: integer
                        example: 1200
            metadata:
              type: object
              properties:
                creditsConsumed:
                  type: integer
                  example: 15000
                generationTimeMs:
                  type: integer
                  example: 165000
                documentsGenerated:
                  type: integer
                  example: 10
            error:
              type: object
              properties:
                code:
                  type: string
                  example: generation_failed
                message:
                  type: string
                  example: >-
                    Project generation failed due to AI service timeout. Credits
                    refunded.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - AUTHENTICATION_FAILED
                - RATE_LIMIT_EXCEEDED
                - INVALID_JSON
                - VALIDATION_ERROR
                - RESOURCE_NOT_FOUND
                - SECURITY_VIOLATION
                - INTERNAL_ERROR
              example: VALIDATION_ERROR
            message:
              type: string
              example: Required field missing
            request_id:
              type: string
              example: req_1234567890
            documentation:
              type: string
              format: uri
              example: https://docs.initrepo.com/api/errors
            details:
              type: object
              description: Additional error context specific to the error type
              additionalProperties: true
              example:
                missing_fields:
                  - projectIdea
                invalid_fields:
                  projectType: 'Must be one of: web, mobile, api, desktop'
          required:
            - code
            - message
            - request_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using API keys (ir_live_* or ir_test_*)

````