API docs
Book a demo

Content Enrichment API / Vision AI

List vision images

Page

POST /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.

Example request

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 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: First page of everything this project has submitted
{}
Example request: Only the analyzed images, two per page
{
  "Status": "completed",
  "Limit": 2,
  "Offset": 0
}
Example request: An offset beyond the last entry
{
  "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

Body

application/json 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.

    10 fields
    • 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.

      26 fields
      • 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
        [
          "sea_view",
          "balcony"
        ]
      • Mood array of string

        Vision-derived mood descriptors.

        Example
        [
          "bright",
          "calm"
        ]
      • Tags array of string

        Additional vision-derived tags.

        Example
        [
          "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
        {
          "CaptureDate": "2012-06-14",
          "Copyright": "© 2012 Hotel Sol S.A."
        }
        2 fields
        • 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
        {
          "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.

        1 field
        • 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.

        2 fields
        • 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
        {
          "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.

        3 fields
        • 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.

        2 fields
        • 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.

        3 fields
        • 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.

    3 fields
    • 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 response: Four images: one still being analyzed, two analyzed, one unreachable — three submitted without a hotel and one for a hotel
{
  "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 response: The two analyzed images, one page of two, and Total counts only what the filter matched
{
  "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 response: An empty page: Images is [], and Total still counts every match
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Status is not one of the three states
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "Status",
        "Message": "Status must be omitted or one of pending, completed, failed"
      }
    ]
  }
}
Example response: The request body is not valid JSON, or a field has the wrong type
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Invalid API key
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Missing required scope
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.catalog:read"
  }
}
Example response: Project access required
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Project or resource not found
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Limit exceeded
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Internal server error
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to load images"
  }
}