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

# Create a project

> Creates a new project (listing). Returns a `projectId` to use in subsequent upload and process calls.
New projects start in `pending` status.




## OpenAPI

````yaml POST /v1/projects
openapi: 3.1.0
info:
  title: Fotolabs API
  version: 1.0.0
  description: >
    Programmatic access to the Fotolabs image processing pipeline.


    **Base URL:** `https://api.fotolabs.co` (prod) ·
    `https://api-staging.fotolabs.co` (staging)


    **Authentication:** Pass your API key as a Bearer token on every request.

    ```

    Authorization: Bearer fl_<key>

    ```


    **Typical flow:**

    1. `POST /v1/projects` — create a project

    2. `POST /v1/images/upload-url` + `PUT <uploadUrl>` — repeat for each image
    (no grouping needed)

    3. `POST /v1/projects/{projectId}/process` — process the whole project in
    one call

    4. `GET /v1/projects/{projectId}` — poll until `status` is `completed`;
    response includes all images and their result URLs


    **Project lifecycle:** `pending` → `processing` → `completed`

    - Images can only be uploaded to a `pending` project.

    - Processing can only be triggered on a `pending` project.

    - Once processing starts the project is locked — create a new project for
    additional images.


    **Plans:**

    - `free` — API access blocked.

    - `essential` / `ultimate` (PAYG) — charged once per project at the plan
    rate.

    - `essential_monthly` / `ultimate_monthly` — deducts one listing from your
    monthly quota; overage rate applies if quota is exhausted.
servers:
  - url: https://api.fotolabs.co
    description: Production
  - url: https://api-staging.fotolabs.co
    description: Staging
security:
  - ApiKeyAuth: []
paths:
  /v1/projects:
    post:
      summary: Create a project
      description: >
        Creates a new project (listing). Returns a `projectId` to use in
        subsequent upload and process calls.

        New projects start in `pending` status.
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 200
                  description: Property address or display name.
                  example: 233 Broadway, New York, NY
                templateId:
                  type: string
                  enum:
                    - original
                    - twilight
                    - virtual-stage
                  default: original
                  description: |
                    Default AI enhancement style for this project.
                    Can be overridden when calling process.
            example:
              name: 233 Broadway, New York, NY
              templateId: original
      responses:
        '200':
          description: Project created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
              example:
                projectId: ca5f09f7-6838-459c-ac0f-7be03c60de24
                name: 233 Broadway, New York, NY
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingName:
                  value:
                    error: name is required
                nameTooLong:
                  value:
                    error: name must be 200 characters or fewer
                badTemplate:
                  value:
                    error: >-
                      Invalid templateId. Allowed: original, twilight,
                      virtual-stage
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API access not available on the free plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  API access requires an Essential or Ultimate plan. Upgrade at
                  fotolabs.co
components:
  schemas:
    Project:
      type: object
      required:
        - projectId
        - name
      properties:
        projectId:
          type: string
          format: uuid
          example: ca5f09f7-6838-459c-ac0f-7be03c60de24
        name:
          type: string
          example: 233 Broadway, New York, NY
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: >-
            No payment method on file. Please add one at fotolabs.co before
            processing images.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: API key with `fl_` prefix, issued from the Fotolabs dashboard

````