API docs
Book a demo

Content Enrichment API / Vision AI

Get vision images

Page

POST /v2/project/content/vision/getImages

Fetch the analysis state of submitted images by image ID, with the enriched image object for every image that is complete.

Analysis runs asynchronously after ingestVisionImages, so an image reports pending until it finishes. Poll every 30 to 60 seconds until each ID reaches completed, failed or not_found.

  • 1 to 100 image IDs per request.
  • One entry per requested ID, in request order, so entries can be matched positionally.
  • Status is pending, completed, failed or not_found; only completed carries Image.
  • An ID this project never submitted reports not_found, never an error.
  • 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/getImages' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "ImageIDs": [
    "0192fb20-1aa2-7def-9abc-1122334455aa",
    "0192fb21-2bb3-7def-9abc-2233445566bb",
    "0192fb22-3cc4-7def-9abc-3344556677cc",
    "0192fb99-9ff9-7def-9abc-999999999999"
  ]
}'

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 GetVisionImagesRequest

Request body for polling submitted images by image ID.

  • ImageIDs array of string (uuid) required

    Image UUIDs returned by ingestVisionImages, between 1 and 100 per request. The response returns one entry per ID, in this order.

    Example
    [
      "0192fb20-1aa2-7def-9abc-1122334455aa",
      "0192fb21-2bb3-7def-9abc-2233445566bb"
    ]
    Limits
    min items 1, max items 100
Example request: Poll four image IDs from an in-flight batch
{
  "ImageIDs": [
    "0192fb20-1aa2-7def-9abc-1122334455aa",
    "0192fb21-2bb3-7def-9abc-2233445566bb",
    "0192fb22-3cc4-7def-9abc-3344556677cc",
    "0192fb99-9ff9-7def-9abc-999999999999"
  ]
}
Example request: Poll two image IDs whose analysis has finished
{
  "ImageIDs": [
    "0192fb21-2bb3-7def-9abc-2233445566bb",
    "0192fb23-4dd5-7def-9abc-4455667788dd"
  ]
}

Responses

200 OK

One entry per requested image ID, in request order.

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 GetVisionImagesResponse

Single-object response envelope wrapping the polled image states.

  • Data object GetVisionImagesResult required

    The state of every polled image.

    1 field
    • Images array of object VisionImageState required

      One entry per requested image ID, in request order.

      Each item

      The analysis state of one polled image, with the enriched image object once the analysis is complete.

      4 fields
      • ImageID string (uuid) required

        The requested image UUID.

        Example
        0192fb21-2bb3-7def-9abc-2233445566bb
      • Status string required

        Analysis state: pending keep polling, completed Image carries the result, failed stop polling and submit a working URL, not_found the ID is unknown for this project.

        Values
        pending completed failed not_found
        Example
        completed
      • 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
          0192fb21-2bb3-7def-9abc-2233445566bb
        • URL string (uri) required

          Image URL.

          Example
          https://images.example-client.com/1234567/room-dbl-sea-1.jpg
        • 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
Example response: One completed image, one still being analyzed, one unreachable URL and one unknown ID
{
  "Data": {
    "Images": [
      {
        "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
        "Status": "pending"
      },
      {
        "ImageID": "0192fb21-2bb3-7def-9abc-2233445566bb",
        "Status": "completed",
        "RoomRef": "DBL-SEA",
        "Image": {
          "ID": "0192fb21-2bb3-7def-9abc-2233445566bb",
          "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
          },
          "FeatureDetections": [
            {
              "Label": "sea_view",
              "Confidence": 0.94
            },
            {
              "Label": "balcony",
              "Confidence": 0.88
            }
          ]
        }
      },
      {
        "ImageID": "0192fb22-3cc4-7def-9abc-3344556677cc",
        "Status": "failed",
        "RoomRef": "SUITE-1"
      },
      {
        "ImageID": "0192fb99-9ff9-7def-9abc-999999999999",
        "Status": "not_found"
      }
    ]
  }
}
Example response: Both images analyzed, one of them carrying the measured detection domains
{
  "Data": {
    "Images": [
      {
        "ImageID": "0192fb21-2bb3-7def-9abc-2233445566bb",
        "Status": "completed",
        "RoomRef": "DBL-SEA",
        "Image": {
          "ID": "0192fb21-2bb3-7def-9abc-2233445566bb",
          "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
          },
          "FeatureDetections": [
            {
              "Label": "sea_view",
              "Confidence": 0.94
            },
            {
              "Label": "balcony",
              "Confidence": 0.88
            }
          ]
        }
      },
      {
        "ImageID": "0192fb23-4dd5-7def-9abc-4455667788dd",
        "Status": "completed",
        "Image": {
          "ID": "0192fb23-4dd5-7def-9abc-4455667788dd",
          "URL": "https://images.example-client.com/1234567/exterior-pool.jpg",
          "Source": "photo",
          "Category": "pool",
          "Features": [
            "outdoor_pool",
            "sun_loungers"
          ],
          "Mood": [
            "relaxing"
          ],
          "Tags": [
            "sunset"
          ],
          "Flags": [
            "people_present"
          ],
          "AppealScore": 91,
          "QualityScore": 88,
          "AppealScoreVersion": "app-v4",
          "QualityScoreVersion": "qs-v4",
          "Width": 2048,
          "Height": 1365,
          "Format": "jpeg",
          "FileSize": 738000,
          "DominantColor": "#1F5D7A",
          "BlurHash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH",
          "FileMetadata": {
            "CaptureDate": "2012-06-14",
            "Copyright": "© 2012 Hotel Sol S.A."
          },
          "Descriptions": {
            "en-US": "Outdoor pool with sun loungers at dusk.",
            "de-DE": "Außenpool mit Sonnenliegen in der Abenddämmerung."
          },
          "Compliance": {
            "AIGenerated": true
          },
          "Presence": [
            {
              "Label": "adult",
              "Confidence": 0.81
            },
            {
              "Label": "child",
              "Confidence": null
            }
          ],
          "Safety": {
            "Inappropriate": 0.02,
            "OffTopic": null
          },
          "TextDetections": [
            {
              "Content": "POOL BAR",
              "Label": "signage",
              "Confidence": 0.76
            }
          ],
          "FeatureDetections": [
            {
              "Label": "outdoor_pool",
              "Confidence": 0.97
            },
            {
              "Label": "sun_loungers",
              "Confidence": 0.83
            }
          ]
        }
      }
    ]
  }
}
400 Bad Request

Bad Request: the request body or an image ID is 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. Per-entry errors carry the entry's position, for example ImageIDs[2].

        Example
        ImageIDs[2]
      • Message string required

        Human-readable validation error message for this field.

        Example
        ImageID must be a valid UUID
      • 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: No image IDs provided
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ImageIDs",
        "Message": "ImageIDs must contain at least one image id"
      }
    ]
  }
}
Example response: More than 100 image IDs in one request
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ImageIDs",
        "Message": "ImageIDs cannot exceed 100 entries"
      }
    ]
  }
}
Example response: An entry is not a valid UUID
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ImageIDs[2]",
        "Message": "ImageID must be a valid UUID"
      }
    ]
  }
}
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. Per-entry errors carry the entry's position, for example ImageIDs[2].

        Example
        ImageIDs[2]
      • Message string required

        Human-readable validation error message for this field.

        Example
        ImageID must be a valid UUID
      • 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. Per-entry errors carry the entry's position, for example ImageIDs[2].

        Example
        ImageIDs[2]
      • Message string required

        Human-readable validation error message for this field.

        Example
        ImageID must be a valid UUID
      • 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. An unknown image ID is not a 404; it is reported per image as not_found.

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. Per-entry errors carry the entry's position, for example ImageIDs[2].

        Example
        ImageIDs[2]
      • Message string required

        Human-readable validation error message for this field.

        Example
        ImageID must be a valid UUID
      • 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. Per-entry errors carry the entry's position, for example ImageIDs[2].

        Example
        ImageIDs[2]
      • Message string required

        Human-readable validation error message for this field.

        Example
        ImageID must be a valid UUID
      • 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. Per-entry errors carry the entry's position, for example ImageIDs[2].

        Example
        ImageIDs[2]
      • Message string required

        Human-readable validation error message for this field.

        Example
        ImageID must be a valid UUID
      • 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"
  }
}