Images API - SuperSeeded

Resolve public product image URLs for plant catalog items.

Overview

The Images API supports backend catalog and storefront integrations. Use it to register allowed storefront origins and resolve product image availability for plant items.

These endpoints are generic Images API endpoints. They are not specific to any one commerce platform or plugin.

Endpoints

Endpoint	Purpose
`POST /v1/retail-images/sites`	Register or update a storefront origin for your account.
`POST /v1/retail-images/resolve`	Resolve image availability and public image URLs for product items.
`POST /v1/retail-images/batches`	Submit a batch of up to five plants for background resolution.
`GET /v1/retail-images/batches/{job_id}`	Read saved status and results.

Authentication

Use your SuperSeeded API key in the X-API-Key header.

X-API-Key: sk-sup-v1*****************************************

Do not expose API keys in frontend code. Send requests from your backend or server-side integration.

Register Site

curl -X POST https://api.superseeded.ai/v1/retail-images/sites \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-sup-v1*****************************************" \
  -d '{
    "site_url": "https://example-garden-centre.com",
    "label": "Example Garden Centre"
  }'

Resolve Images

curl -X POST https://api.superseeded.ai/v1/retail-images/resolve \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-sup-v1*****************************************" \
  -d '{
    "site_url": "https://example-garden-centre.com",
    "items": [
      {
        "product_id": 15133,
        "sku": "ACM-200",
        "botanical_name": "Acacia melanoxylon"
      }
    ]
  }'

Asynchronous batch resolution

When enabled for the API deployment, POST /v1/retail-images/batches accepts one to five items using the same fields as /resolve, plus a client-generated UUID request_id. It saves the request and returns HTTP 202 with job_id, status, and retry_after_seconds. The request does not wait for identity matching or image-cache resolution. Reuse the same request_id when retrying a submission after a timeout. Reusing that ID with different content returns HTTP 409. A batch belongs to the submitting API key, merchant and registered storefront origin. Poll GET /v1/retail-images/batches/{job_id}?site_url=https%3A%2F%2Fexample-garden-centre.com with the same authentication. Polling reads saved results and does not perform image resolution. Batch status is queued, running, complete or failed. Only complete contains resolved item results. Completion of resolution does not mean every image is ready: individual items can still be generating or identity_pending and need a later resolution request. Failed worker invocations are retried up to three times. Completed and failed batches are retained for seven days. If a polling request returns HTTP 404 after retention, submit a new batch with a new request ID. HTTP 501 on submission means this deployment has not enabled batch resolution; integrations can use the synchronous /resolve endpoint until rollout is complete.

Status Values

Status	Description
`available`	`image_url` is present and can be used in a storefront.
`missing`	No image is available for the item. Use your fallback product image.
`invalid`	An image was found but could not be returned. Use your fallback product image.

Security Notes

Public image URLs are display URLs, not private download URLs.
Keep API keys server-side.
Register only storefront origins that belong to your account.
Do not depend on public image URL secrecy for authorization.

​Overview

​Endpoints

​Authentication

​Register Site

​Resolve Images

​Asynchronous batch resolution

​Status Values

​Security Notes

Overview

Endpoints

Authentication

Register Site

Resolve Images

Asynchronous batch resolution

Status Values

Security Notes