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

# Create Project

> Creates a new project for AI-powered generation. This is an asynchronous operation.

Create a new project for AI-powered generation. This endpoint initiates an asynchronous process that generates comprehensive project documentation.

## Request

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.initrepo.com/v1/projects \
    -H "Authorization: Bearer ir_live_your_api_key" \
    -H "Content-Type: application/json" \
    -H "API-Version: v1.0" \
    -d '{
      "projectIdea": "Build a modern e-commerce platform with AI recommendations",
      "projectType": "web",
      "features": [
        {
          "name": "Product Catalog",
          "description": "Display products with search and filtering capabilities"
        },
        {
          "name": "Shopping Cart",
          "description": "Add/remove items, calculate totals, apply discounts"
        }
      ],
      "integrations": ["stripe", "sendgrid"],
      "format": "full",
      "webhookUrl": "https://your-app.com/webhooks/initrepo",
      "design": {
        "description": "Modern, clean design with dark mode support",
        "figmaUrl": "https://figma.com/design/your-design-link"
      }
    }'
  ```
</RequestExample>

## Request Body

<ParamField body="projectIdea" type="string" required>
  Project description (10-1000 characters). Should clearly describe what you want to build.
</ParamField>

<ParamField body="projectType" type="enum" required>
  Type of project to create. Options: `web`, `mobile`, `mcp`.
</ParamField>

<ParamField body="features" type="array">
  Array of project features (max 20). Each feature should have a `name` and `description`.
</ParamField>

<ParamField body="integrations" type="array">
  Array of integration names (max 10). Valid integrations include payment processors, email services, etc.
</ParamField>

<ParamField body="format" type="enum" default="full">
  Response format level. Options: `full`, `summary`, `minimal`.
</ParamField>

<ParamField body="webhookUrl" type="string">
  HTTPS webhook URL for completion notifications. Must be HTTPS and not a private IP.
</ParamField>

<ParamField body="design" type="object">
  Design requirements including description and Figma links.
</ParamField>

## Response

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

  **Response Headers:**

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

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

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

<ResponseField name="data.status" type="string">
  Current status of the project (always "in\_progress" for new projects).
</ResponseField>

<ResponseField name="data.estimatedCompletionMs" type="integer">
  Estimated time in milliseconds until project completion.
</ResponseField>

## Error Responses

### Validation Error (422)

<ErrorExample>
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Required field missing or invalid",
      "request_id": "req_1234567890",
      "documentation": "https://docs.initrepo.com/api/create",
      "details": {
        "missing_fields": ["projectIdea"],
        "invalid_fields": {
          "projectType": "Must be one of: web, mobile, mcp"
        }
      }
    }
  }
  ```
</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": "malformed_key"
      }
    }
  }
  ```
</ErrorExample>

### Insufficient Credits (402)

<ErrorExample>
  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "PAYMENT_REQUIRED",
      "message": "Insufficient credits. This operation requires 15,000 credits.",
      "request_id": "req_1234567890",
      "documentation": "https://docs.initrepo.com/billing",
      "details": {
        "required_credits": 15000,
        "available_credits": 5000
      }
    }
  }
  ```
</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.

## Cost

This operation consumes 15,000 credits for live keys. Test keys consume no credits.


## OpenAPI

````yaml POST /api/v1/projects
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:
    post:
      tags:
        - Projects
      summary: Create a new project
      description: >-
        Creates a new project for AI-powered generation. This is an asynchronous
        operation.
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '202':
          description: Project creation started successfully
          headers:
            API-Version:
              description: Current API version
              schema:
                type: string
                example: v1.0
            X-Request-ID:
              description: Unique request identifier
              schema:
                type: string
                example: req_1234567890
            X-RateLimit-Remaining:
              description: Requests remaining in current window
              schema:
                type: integer
                example: 95
            X-RateLimit-Reset:
              description: Unix timestamp when rate limit resets
              schema:
                type: integer
                example: 1699123456
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCreatedResponse'
        '400':
          description: Bad Request - Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - Insufficient credits
          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:
    CreateProjectRequest:
      type: object
      required:
        - projectIdea
        - projectType
      properties:
        projectIdea:
          type: string
          description: Project description (10-1000 characters)
          minLength: 10
          maxLength: 1000
          example: Build a modern e-commerce platform with AI recommendations
        projectType:
          type: string
          enum:
            - web
            - mobile
            - mcp
          description: Type of project to create
          example: web
        features:
          type: array
          maxItems: 20
          description: Array of project features (optional)
          items:
            type: object
            properties:
              name:
                type: string
                maxLength: 100
                description: Feature name
                example: User Authentication
              description:
                type: string
                maxLength: 500
                description: Feature description
                example: Secure login and registration system
        integrations:
          type: array
          maxItems: 10
          description: Array of integration names (optional)
          items:
            type: string
          example:
            - stripe
            - sendgrid
        format:
          type: string
          enum:
            - full
            - summary
            - minimal
          default: full
          description: Response format level
          example: full
        webhookUrl:
          type: string
          format: uri
          description: HTTPS webhook URL for completion notifications (optional)
          pattern: ^https://
          example: https://your-app.com/webhooks/initrepo
        design:
          type: object
          description: Design requirements (optional)
          properties:
            description:
              type: string
              description: Design description
              example: Modern, clean design with dark mode support
            figmaUrl:
              type: string
              format: uri
              description: Figma design link
              example: https://figma.com/design/your-design-link
    ProjectCreatedResponse:
      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
              example: in_progress
            estimatedCompletionMs:
              type: integer
              example: 180000
    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_*)

````