# List vision images

Content Enrichment API / Vision AI

`POST https://api.ygo.ai/v2/project/content/vision/listImages`

List this project's submitted images, newest first, with the enriched image object for every image that is complete.

Analysis runs asynchronously, so an image listed as `pending` is still being worked on. An empty body `{}` returns the first page of everything this project has submitted.

- `Limit` defaults to 50, caps at 100; `Offset` defaults to 0.
- `Status` filters to `pending`, `completed` or `failed`; any other value returns 400.
- Ordered by `SubmittedAt` then `ImageID`, both descending.
- `Data` is the array itself; `Pagination.Total` counts the match.
- A `Status` filter covers your newest 10,000 submissions.
- 404 means Vision AI is not enabled for your project.
- 429 means the rate limit was hit; wait `Retry-After` seconds.

Exact spec (OpenAPI 3.0, JSON): https://docs.ygo.ai/reference/listVisionImages.json

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/vision/listImages' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Authorization

`Authorization: Bearer <key>`

Project-scoped API key

## Headers

- `X-Project-ID` (string (uuid), **required**)

  Project UUID. Required for all project-scoped endpoints.

  Example: `$YGO_PROJECT_ID`

## Request body

Required.

### application/json

Schema: object, `ListVisionImagesRequest`

Filter and page this project's submitted images. Every field is optional, so an empty body `{}` returns the first page of every image the project has submitted.

- `Status` (string)

  Restrict the list to one state; omit it to list every state. A filter covers your newest 10,000 submissions.

  Values: `pending`, `completed`, `failed`

  Example: `completed`
- `Limit` (integer)

  Page size. Defaults to 50 when omitted or 0; a value above 100 is reduced to 100 rather than refused.

  Default: `50`

  Example: `50`
- `Offset` (integer)

  Number of images to skip before this page, default 0. An offset past the last image returns an empty page.

  Default: `0`

  Example: `0`

#### Example request: noFilter. First page of everything this project has submitted

```json
{}
```

#### Example request: completedOnly. Only the analyzed images, two per page

```json
{
  "Status": "completed",
  "Limit": 2,
  "Offset": 0
}
```

#### Example request: pastTheEnd. An offset beyond the last entry

```json
{
  "Offset": 200
}
```

## Responses

### 200 OK

One page of this project's submitted images, newest first.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ListVisionImagesResponse`

List response envelope: Data is the page of submitted images and Pagination describes the whole matching set.

- `Data` (array of object, `ListVisionImage`, **required**)

  The page of submitted images, newest first. Always an array: an empty page is [] and never null.

  Each item: One submitted image: its state, when and how it was submitted, and the enriched image object once the analysis is complete.

  - `ImageID` (string (uuid), **required**)

    Image UUID, the same ID ingestVisionImages returned and getVisionImages polls.

    Example: `0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4`
  - `URL` (string (uri), **required**)

    The submitted image URL, normalized.

    Example: `https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/`
  - `Status` (string, **required**)

    Analysis state: `pending` still being analyzed, `completed` `Image` carries the result, `failed` the URL could not be fetched. `not_found` never appears here.

    Values: `pending`, `completed`, `failed`

    Example: `completed`
  - `SubmittedAt` (string (date-time), **required**)

    RFC 3339 timestamp of the submission. It is the sort key, descending; re-submitting the same URL refreshes it, which moves the image back to the top of the list.

    Example: `2026-09-09T16:04:12.550118Z`
  - `BatchID` (string (uuid), **required**)

    Identifier shared by every image submitted in the same ingestVisionImages request.

    Example: `0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33`
  - `HotelID` (string (uuid), **required**)

    UUID of the hotel this image is stored under.

    Example: `01a086e1-ffaf-7040-b032-76677278f0ae`
  - `HotelName` (string)

    Name of that hotel. Present for the placeholder hotel and for hotels that belong to your project, omitted otherwise.

    Example: `Vision AI API placeholder`
  - `IsPlaceholderHotel` (boolean)

    True when the image was submitted without a hotel and therefore sits on the project's placeholder hotel. Present only when it is true; omitted for an image submitted for a hotel.

    Example: `true`
  - `RoomRef` (string)

    The room code or name submitted with this image. Omitted when the image was submitted without one.

    Example: `DBL-SEA`
  - `Image` (object, `Image`)

    The enriched image object. Present only when Status is `completed`.

    - `ID` (string (uuid), **required**)

      Unique image UUID.

      Example: `0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4`
    - `URL` (string (uri), **required**)

      Image URL.

      Example: `https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/`
    - `Source` (string)

      Detected provenance of the pixels: `photo`, `render`, `illustration` or `ai_generated`. Omitted when the image carries no provenance assessment.

      Example: `photo`
    - `Category` (string)

      Vision-derived image category (e.g. exterior, room, pool, restaurant).

      Example: `room`
    - `Features` (array of string)

      Vision-derived feature tags depicted in the image.

      Example:

      ```json
      [
        "sea_view",
        "balcony"
      ]
      ```
    - `Mood` (array of string)

      Vision-derived mood descriptors.

      Example:

      ```json
      [
        "bright",
        "calm"
      ]
      ```
    - `Tags` (array of string)

      Additional vision-derived tags.

      Example:

      ```json
      [
        "sea_view"
      ]
      ```
    - `Flags` (array of string)

      Quality / content flags raised by vision analysis. Omitted when empty.
    - `AppealScore` (integer)

      Appeal score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.

      Example: `82`
    - `QualityScore` (integer)

      Technical quality score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.

      Example: `77`
    - `AppealScoreVersion` (string)

      Version stamp of the scorer that produced AppealScore, for example `app-v4`; it may name an earlier version. Absent when AppealScore is -1 or a legacy score from before stamps existed.

      Example: `app-v4`
    - `QualityScoreVersion` (string)

      Version stamp of the scorer that produced QualityScore, for example `qs-v4`; it may name an earlier version. Absent when QualityScore is -1, a legacy score, or a first-seen image's provisional score.

      Example: `qs-v4`
    - `Width` (integer)

      Image width in pixels.

      Example: `1600`
    - `Height` (integer)

      Image height in pixels.

      Example: `1067`
    - `Format` (string)

      Image format (e.g. jpeg, png, webp).

      Example: `jpeg`
    - `FileSize` (integer)

      File size in bytes.

      Example: `412000`
    - `DominantColor` (string)

      Dominant color as a hex string.

      Example: `#2E6F95`
    - `BlurHash` (string)

      BlurHash placeholder string for progressive loading.

      Example: `LEHV6nWB2yk8pyo0adR*`
    - `FileMetadata` (object)

      What the image file itself states in its embedded IPTC/EXIF/XMP metadata: capture date and copyright notice. Omitted when the file states neither; inside it, a value the file did not state has no key.

      Example:

      ```json
      {
        "CaptureDate": "2012-06-14",
        "Copyright": "© 2012 Hotel Sol S.A."
      }
      ```

      - `CaptureDate` (string)

        Date the photograph was taken, at the precision the file stated: `2012-06-14`, `2012-06` or `2012`. It carries no time of day and no timezone.

        Example: `2012-06-14`

        Limits: pattern ^\d{4}(-\d{2}(-\d{2})?)?$
      - `Copyright` (string)

        The copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.

        Example: `© 2012 Hotel Sol S.A.`
    - `Descriptions` (map of string to string)

      Neutral alt text describing what the image shows, not marketing copy, keyed by BCP 47 language tag. More locales may be added after an image is first analyzed.

      Example:

      ```json
      {
        "en-US": "Double room with a balcony overlooking the sea.",
        "de-DE": "Doppelzimmer mit Balkon und Meerblick."
      }
      ```
    - `Compliance` (object, `Compliance`)

      EU AI Act Article 50(2) marker for this image. Always present with `AIGenerated` true: the category, features, mood, tags, scores and descriptions are model output, `FileMetadata` is not.

      - `AIGenerated` (boolean)

        EU AI Act Art. 50(2) machine-readable marker: `true` when the text content of the enclosing object is AI-generated. Always stated explicitly when the envelope is present.

        Example: `true`
    - `Presence` (array of object, `PresenceDetection`)

      People and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement.

      Each item: One person or animal seen in the image.

      - `Label` (string, **required**)

        What was seen: `person`, `adult`, `child` or `animal`.

        Example: `adult`
      - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

        Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

        Example: `0.94`

        Limits: min 0, max 1
    - `Safety` (map of string to number (float))

      Safety confidences keyed by dimension, `Inappropriate` and `OffTopic`, each between 0 and 1 or null. Omitted when the image carries no safety measurement.

      Each value: nullable

      Example:

      ```json
      {
        "Inappropriate": 0.02,
        "OffTopic": null
      }
      ```

      Limits: each value: min 0, each value: max 1
    - `TextDetections` (array of object, `TextDetection`)

      Texts read off the image, each with its kind. Omitted when the image carries no text measurement.

      Each item: One text read off the image.

      - `Content` (string, **required**)

        The text as it appears on the image. A password or access code printed after a password label is masked.

        Example: `POOL BAR`
      - `Label` (string, **required**)

        Kind of text: `overlay`, `price`, `promotional`, `watermark`, `signage` or `document`.

        Example: `signage`
      - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

        Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

        Example: `0.94`

        Limits: min 0, max 1
    - `FeatureDetections` (array of object, `FeatureDetection`)

      The image's features with the confidence measured for each, running parallel to `Features`. Omitted when the image carries no feature measurement.

      Each item: One feature of the image with the confidence measured for it.

      - `Label` (string, **required**)

        The feature label, from the same vocabulary as Features.

        Example: `sea_view`
      - `Confidence` (number (float), `DetectionConfidence`, **required**, nullable)

        Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.

        Example: `0.94`

        Limits: min 0, max 1
    - `Nudity` (object)

      Nudity assessment: exposure score, reason and explicit flag, independent of `Safety.Inappropriate`. Omitted when the assessment did not run or the image's `Presence` shows no person.

      - `Score` (integer, **required**)

        Exposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.

        Example: `60`

        Limits: min 0, max 100
      - `Reason` (string, **required**)

        One model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.

        Example: `Adult in revealing swimwear by the pool.`
      - `Explicit` (boolean, **required**)

        True from a score of 90 up. Whether a child is in the picture is answered by `Presence`, not here.

        Example: `false`
- `Pagination` (object, `Pagination`, **required**)

  Pagination metadata for a list response.

  - `Total` (integer, **required**)

    Number of images matching the request across all pages, not the page size. With a `Status` filter it covers your newest 10,000 submissions.

    Example: `4`
  - `Limit` (integer, **required**)

    Page size actually applied, after the default and the cap.

    Example: `50`
  - `Offset` (integer, **required**)

    Number of images skipped before this page.

    Example: `0`

##### Example: noFilter. Four images: one still being analyzed, two analyzed, one unreachable — three submitted without a hotel and one for a hotel

```json
{
  "Data": [
    {
      "ImageID": "0199b2d0-11a5-7c5e-8f21-6d0e4f88b521",
      "URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/",
      "Status": "pending",
      "SubmittedAt": "2026-09-09T16:04:51.812433Z",
      "BatchID": "0199b2d0-11a4-7c5e-8f21-5c9d3e77a410",
      "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
      "HotelName": "Vision AI API placeholder",
      "IsPlaceholderHotel": true
    },
    {
      "ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
      "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
      "Status": "completed",
      "SubmittedAt": "2026-09-09T16:04:12.550118Z",
      "BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
      "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
      "HotelName": "Vision AI API placeholder",
      "IsPlaceholderHotel": true,
      "Image": {
        "ID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
        "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
        "Source": "photo",
        "Category": "restaurant",
        "Features": [
          "indoor_seating",
          "buffet"
        ],
        "Mood": [
          "warm",
          "inviting"
        ],
        "Tags": [
          "breakfast"
        ],
        "AppealScore": 74,
        "QualityScore": 81,
        "AppealScoreVersion": "app-v4",
        "QualityScoreVersion": "qs-v4",
        "Width": 2000,
        "Height": 1333,
        "Format": "jpeg",
        "FileSize": 611000,
        "DominantColor": "#8A6A48",
        "BlurHash": "L6PZfSjE.AyE_3t7t7R**0o#DgR4",
        "FileMetadata": {
          "CaptureDate": "2012-06-14",
          "Copyright": "© 2012 Hotel Sol S.A."
        },
        "Descriptions": {
          "en-US": "Restaurant with buffet counters and set tables.",
          "de-DE": "Restaurant mit Buffettheken und eingedeckten Tischen."
        },
        "Compliance": {
          "AIGenerated": true
        },
        "FeatureDetections": [
          {
            "Label": "buffet",
            "Confidence": 0.91
          },
          {
            "Label": "indoor_seating",
            "Confidence": 0.86
          }
        ]
      }
    },
    {
      "ImageID": "0199b2c4-8e31-77aa-9c02-1a4c60b8c7f1",
      "URL": "https://ucarecdn.com/7d4e9b21-6c3a-4f52-8e10-9b8a7c6d5e4f/",
      "Status": "failed",
      "SubmittedAt": "2026-09-09T16:04:12.550118Z",
      "BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
      "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
      "HotelName": "Vision AI API placeholder",
      "IsPlaceholderHotel": true
    },
    {
      "ImageID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
      "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
      "Status": "completed",
      "SubmittedAt": "2026-09-08T09:12:44.301882Z",
      "BatchID": "0199a51f-4c22-7de8-b3a9-0f1e2d3c4b5a",
      "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
      "HotelName": "Hotel Bahia Azul",
      "RoomRef": "DBL-SEA",
      "Image": {
        "ID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
        "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
        "Source": "photo",
        "Category": "room",
        "Features": [
          "sea_view",
          "balcony",
          "double_bed"
        ],
        "Mood": [
          "bright",
          "calm"
        ],
        "Tags": [
          "sea_view"
        ],
        "AppealScore": 82,
        "QualityScore": 77,
        "AppealScoreVersion": "app-v4",
        "QualityScoreVersion": "qs-v4",
        "Width": 1600,
        "Height": 1067,
        "Format": "jpeg",
        "FileSize": 412000,
        "DominantColor": "#2E6F95",
        "BlurHash": "LEHV6nWB2yk8pyo0adR*",
        "Descriptions": {
          "en-US": "Double room with a balcony overlooking the sea.",
          "de-DE": "Doppelzimmer mit Balkon und Meerblick."
        },
        "Compliance": {
          "AIGenerated": true
        },
        "Presence": [
          {
            "Label": "adult",
            "Confidence": 0.81
          }
        ],
        "Safety": {
          "Inappropriate": 0.02,
          "OffTopic": null
        },
        "FeatureDetections": [
          {
            "Label": "sea_view",
            "Confidence": 0.94
          },
          {
            "Label": "balcony",
            "Confidence": 0.88
          }
        ]
      }
    }
  ],
  "Pagination": {
    "Total": 4,
    "Limit": 50,
    "Offset": 0
  }
}
```

##### Example: completedOnly. The two analyzed images, one page of two, and Total counts only what the filter matched

```json
{
  "Data": [
    {
      "ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
      "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
      "Status": "completed",
      "SubmittedAt": "2026-09-09T16:04:12.550118Z",
      "BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
      "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
      "HotelName": "Vision AI API placeholder",
      "IsPlaceholderHotel": true,
      "Image": {
        "ID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
        "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
        "Source": "photo",
        "Category": "restaurant",
        "Features": [
          "indoor_seating",
          "buffet"
        ],
        "Mood": [
          "warm",
          "inviting"
        ],
        "Tags": [
          "breakfast"
        ],
        "AppealScore": 74,
        "QualityScore": 81,
        "AppealScoreVersion": "app-v4",
        "QualityScoreVersion": "qs-v4",
        "Width": 2000,
        "Height": 1333,
        "Format": "jpeg",
        "FileSize": 611000,
        "DominantColor": "#8A6A48",
        "BlurHash": "L6PZfSjE.AyE_3t7t7R**0o#DgR4",
        "Descriptions": {
          "en-US": "Restaurant with buffet counters and set tables.",
          "de-DE": "Restaurant mit Buffettheken und eingedeckten Tischen."
        },
        "Compliance": {
          "AIGenerated": true
        }
      }
    },
    {
      "ImageID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
      "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
      "Status": "completed",
      "SubmittedAt": "2026-09-08T09:12:44.301882Z",
      "BatchID": "0199a51f-4c22-7de8-b3a9-0f1e2d3c4b5a",
      "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
      "HotelName": "Hotel Bahia Azul",
      "RoomRef": "DBL-SEA",
      "Image": {
        "ID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
        "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
        "Source": "photo",
        "Category": "room",
        "Features": [
          "sea_view",
          "balcony",
          "double_bed"
        ],
        "Mood": [
          "bright",
          "calm"
        ],
        "Tags": [
          "sea_view"
        ],
        "AppealScore": 82,
        "QualityScore": 77,
        "AppealScoreVersion": "app-v4",
        "QualityScoreVersion": "qs-v4",
        "Width": 1600,
        "Height": 1067,
        "Format": "jpeg",
        "FileSize": 412000,
        "DominantColor": "#2E6F95",
        "BlurHash": "LEHV6nWB2yk8pyo0adR*",
        "Descriptions": {
          "en-US": "Double room with a balcony overlooking the sea.",
          "de-DE": "Doppelzimmer mit Balkon und Meerblick."
        },
        "Compliance": {
          "AIGenerated": true
        }
      }
    }
  ],
  "Pagination": {
    "Total": 2,
    "Limit": 2,
    "Offset": 0
  }
}
```

##### Example: pastTheEnd. An empty page: Images is [], and Total still counts every match

```json
{
  "Data": [],
  "Pagination": {
    "Total": 4,
    "Limit": 50,
    "Offset": 200
  }
}
```

### 400 Bad Request

Bad Request: the request body or the `Status` value is invalid. `Limit` and `Offset` are clamped to the accepted range, never rejected.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Status`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Status must be omitted or one of pending, completed, failed`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidStatus. Status is not one of the three states

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "Status",
        "Message": "Status must be omitted or one of pending, completed, failed"
      }
    ]
  }
}
```

##### Example: malformedBody. The request body is not valid JSON, or a field has the wrong type

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid request body"
  }
}
```

### 401 Unauthorized

Unauthorized: the API key is missing or invalid.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Status`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Status must be omitted or one of pending, completed, failed`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidKey. Invalid API key

```json
{
  "Error": {
    "Code": "UNAUTHORIZED",
    "Message": "Invalid API key"
  }
}
```

### 403 Forbidden

Forbidden: the API key may not act on this project, or does not carry the `content.catalog:read` permission this endpoint requires (`INSUFFICIENT_SCOPE`).

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Status`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Status must be omitted or one of pending, completed, failed`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: insufficientScope. Missing required scope

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.catalog:read"
  }
}
```

##### Example: noProjectAccess. Project access required

```json
{
  "Error": {
    "Code": "FORBIDDEN",
    "Message": "Project access required"
  }
}
```

### 404 Not Found

Not Found: Vision AI is not enabled for your project, or the project does not exist. A project with no submissions is an empty page, not a 404.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Status`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Status must be omitted or one of pending, completed, failed`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: notFound. Project or resource not found

```json
{
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Not found"
  }
}
```

### 429 Too Many Requests

Too Many Requests: the rate limit was exceeded. `Retry-After` carries the number of seconds to wait before retrying.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`
- `Retry-After` (integer)

  Number of seconds to wait before retrying the request. Present on 429 responses.

  Example: `30`

  Limits: min 1

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Status`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Status must be omitted or one of pending, completed, failed`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: rateLimited. Limit exceeded

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
  }
}
```

### 500 Internal Server Error

Internal Server Error: unexpected server error. Quote the `X-Trace-ID` response header when contacting support.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `Status`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `Status must be omitted or one of pending, completed, failed`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: internalError. Internal server error

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to load images"
  }
}
```
