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

# API reference

> Programmatic access to the Fotolabs image processing pipeline

## Base URLs

| Environment | URL                       |
| ----------- | ------------------------- |
| Production  | `https://api.fotolabs.co` |

## Authentication

All endpoints require an API key passed as a Bearer token.

```http theme={null}
Authorization: Bearer fl_<key>
```

Get your API key from the [Fotolabs dashboard](https://fotolabs.co).

## Typical flow

<Steps>
  <Step title="Create a project">
    `POST /v1/projects` — create a project for a listing.
  </Step>

  <Step title="Upload images">
    `POST /v1/images/upload-url` for each file → `PUT <uploadUrl>` directly to S3. Repeat for every image; no client-side grouping needed.
  </Step>

  <Step title="Trigger processing">
    `POST /v1/projects/{projectId}/process` — enqueues all jobs in one call. HDR bracket sets are detected automatically from EXIF metadata.
  </Step>

  <Step title="Poll for results">
    `GET /v1/projects/{projectId}` — check `status`. When it's `completed`, all `resultImageUrl` values are ready.
  </Step>
</Steps>

## Project lifecycle

Projects move through `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

| Plan                                     | API access                                                                              |
| ---------------------------------------- | --------------------------------------------------------------------------------------- |
| `free`                                   | 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 |

## HDR bracket detection

Upload all bracket exposures flat — no grouping needed on the client. When you call `POST /v1/projects/{projectId}/process`, images captured within `bracketWindowSeconds` of each other with an EV spread ≥ 0.5 stops are automatically grouped as HDR bracket sets.

## Processing time

Each job typically completes in **60–120 seconds**. HDR merge jobs may take slightly longer.