> ## Documentation Index
> Fetch the complete documentation index at: https://api.superseeded.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Images API

> Resolve image availability and public image URLs for plant catalog items. This endpoint returns already available imagery and does not trigger new image generation.

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.

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

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

## Authentication

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

```bash theme={"theme":"github-dark"}
X-API-Key: sk-sup-v1*****************************************
```

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

## Register Site

Register a storefront origin before resolving images for that site.

```bash theme={"theme":"github-dark"}
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

```bash theme={"theme":"github-dark"}
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"
      }
    ]
  }'
```

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


## OpenAPI

````yaml POST /retail-images/resolve
openapi: 3.1.0
info:
  title: Superseeded API
  description: >-
    Modern nursery industry API for reconciling plant specifications, resolving
    equivalence and assessing logistical risks for plant stock.
  version: 1.0.0
  license:
    name: MIT
  contact:
    name: Superseeded Support
servers:
  - url: https://api.superseeded.ai/v1
    description: Production Server
security: []
tags:
  - name: Resolvers
    description: Endpoints for cleaning, normalizing, and interpreting messy nursery data.
  - name: Validation
    description: >-
      Endpoints for validating botanical species names against taxonomic
      databases.
  - name: Flowers
    description: >-
      Search flowers by color using spectral reflectance data from the Floral
      Reflectance Database (FReD).
  - name: System
    description: Health checks and service status.
  - name: Images
    description: Resolve public catalog image URLs for storefront and product integrations.
paths:
  /retail-images/resolve:
    post:
      tags:
        - Images
      summary: Resolve Catalog Images
      description: >-
        Resolve image availability and public image URLs for plant catalog
        items. This endpoint returns already available imagery and does not
        trigger new image generation.
      operationId: resolveCatalogImages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageResolveRequest'
      responses:
        '200':
          description: Image availability resolved for each item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResolveResponse'
        '400':
          description: Invalid request.
        '401':
          description: Missing API key.
        '403':
          description: Invalid API key or unregistered storefront origin.
        '500':
          description: Image service configuration error.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ImageResolveRequest:
      type: object
      required:
        - site_url
        - items
      properties:
        site_url:
          type: string
          format: uri
          description: Registered storefront URL for this request.
        items:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/ImageResolveItem'
    ImageResolveResponse:
      type: object
      required:
        - site_url
        - normalized_origin
        - results
      properties:
        site_url:
          type: string
          format: uri
        normalized_origin:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/ImageResolveResult'
    ImageResolveItem:
      type: object
      properties:
        product_id:
          type: integer
          nullable: true
          description: Optional catalog product ID echoed in the result.
        sku:
          type: string
          nullable: true
          description: Optional SKU echoed in the result.
        species_key:
          type: string
          nullable: true
          description: Plant identifier used by your catalog or integration.
        botanical_name:
          type: string
          nullable: true
          description: Botanical name to use when species_key is not provided.
        product_name:
          type: string
          nullable: true
          description: Optional product name for your own correlation.
    ImageResolveResult:
      type: object
      required:
        - status
        - source_status
      properties:
        product_id:
          type: integer
          nullable: true
        sku:
          type: string
          nullable: true
        species_key:
          type: string
          nullable: true
        species_hash:
          type: string
          nullable: true
          description: Stable opaque identifier for the resolved plant image.
        status:
          type: string
          enum:
            - available
            - missing
            - invalid
          description: Image availability status.
        image_url:
          type: string
          format: uri
          nullable: true
          description: Public image URL when status is available.
        thumbnail_url:
          type: string
          format: uri
          nullable: true
          description: Optional public thumbnail URL when available.
        version:
          type: string
          nullable: true
        source_status:
          type: string
          description: High-level source status for the resolved image.
        message:
          type: string
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Standard API Key authentication.

````