API Endpoints

This section provides detailed documentation for all available Koral API endpoints.

Base URL

All API requests should be made to the following base URL:

https://search.koral.nu/api/v1

Available Endpoints

Image Search

POST /search/image

Upload an image to find visually similar images.

Request Body:

{
  "imageData": "<base64_encoded_image_data>",
  "limit": 10,
  "offset": 0,
  "searchId": "<customer feed id>"
}

Parameters:

Parameter	Type	Required	Description
`imageData`	string	Yes	Base64-encoded image data
`limit`	integer	Yes	Maximum number of results (default: 10, max: 100)
`offset`	integer	Yes	Offset for pagination (default: 0)
`searchId`	string	Yes	Customer feed id

Response:

[
    {
        "feed_id": "<customer feed id>",
        "item_group_id": "product item group id",
        "product_id": "Customer product id",
        "title": "Product title",
        "description": "Product description",
        "age_group": "The age group of the product",
        "availability": "in_stock | out_of_stock",
        "brand": "Product brand",
        "color": "Any color of the product",
        "condition": "new | used | refurbished",
        "gender": "The gender of the product",
        "category": "Product category",
        "gtin": "Global Trade Item Number",
        "image_link": "URL of the product image",
        "material": "Any material of the product",
        "mpn": "Manufacturer Part Number",
        "price": 30000, // Price in cents
        "product_highlight": [
            "Product highlight 1",
            "Product highlight 2"
        ],
        "product_type": "Tilbehør > Caps og kasketter", // Product type, google taxonomy
        "sale_price": 30000, // Sale price in cents
        "shipping_price": 3500, // Shipping price in cents
        "shipping_country": "DK", // Shipping country
        "shipping_weight": "", // Shipping weight
        "short_title": "Product short title",
        "size": "ONESIZE", // Product size
        "link": "URL of the product page",
        "product_updated_at": "", // Product updated at, provided by the customer
        "currency": "DKK", // Currency of the product price
        "shipping_currency": "DKK", // Currency of the shipping price
        "score": 0.52604675, // Similarity score
        "variants": [
            {
                "product_id": "Product id",
                "color": "Color of the product variant",
                "size": 46, // Size of the product variant
                "price": 35000, // Price in cents
                "currency": "DKK", // Currency of the product variant price
                "sale_price": 35000, // Sale price in cents
                "image_link": "URL of the product variant image",
                "availability": "in_stock | out_of_stock",
                "link": "URL of the product variant page",
            }
        ],
        "variant_count": 1
    },
    // More results...
]

Detect objects

POST /detect

Search for similar images using an image URL.

Request Body:

{
  "imageData": "<base64_encoded_image_data>",
  "searchId": "<customer feed id>",
  "action": "OD"
}

Parameters:

Parameter	Type	Required	Description
`imageData`	string	Yes	Base64-encoded image data
`searchId`	integer	Yes	Customer feed id
`action`	object	No	Optional specifies the actions to perform

Response: Same as Search by Image

{
  "action": "<OD>",
  "searchId": "<customer feed id>",
  "results": {
    "objects": [
      {
        "box": [120, 45, 280, 190],
        "label": "person",
        "score": 0.92
      },
      {
        "box": [320, 150, 450, 280],
        "label": "chair",
        "score": 0.87
      },
      {
        "box": [50, 200, 180, 350],
        "label": "potted plant",
        "score": 0.78
      }
    ]
  },
  "processTimeSeconds": 1.25
}

POST /related

Find related products based on a reference image or product ID.

Request Body:

{
  "productId": "PROD123456",
  "searchId": "a9824e86-8676-4263-b0ae-bef9fce23549",
  "limit": 15,
  "offset": 0,
  "fallback": "base64 image",
  "context": {
    "category": "Women > Clothing > Tops > Short Sleeve T-shirts",
    "domain": "www.example.com",
    "pageUrl": "https://www.example.com/product/PROD123456.html",
    "type": "related"
  }
}

Parameters:

Parameter	Type	Required	Description
`imageData`	string	No	Base64-encoded image data, if not provided product id is required
`productId`	string	No	Customer product id, if not provided image data is required
`limit`	integer	Yes	Maximum number of results (default: 10, max: 100)
`offset`	integer	Yes	Offset for pagination (default: 0)
`searchId`	string	Yes	Customer feed id
`filters`	array	No	Array of filter objects with `key` and `value` properties to filter results
`fallback`	string	No	Fallback behavior configuration
`context`	object	No	Context information including `category`, `domain`, `pageUrl`, and `type`

Response:

[
    {
        "id": "uuid-string",
        "feed_id": "<customer feed id>",
        "item_group_id": "product item group id",
        "product_id": "PROD123456",
        "title": "Classic Cotton T-Shirt",
        "description": "Short sleeve cotton t-shirt",
        "short_title": "Cotton Tee",
        "age_group": "adult",
        "availability": "in stock",
        "brand": "Example Brand",
        "color": "Blue",
        "condition": "new",
        "gender": "Female",
        "category": "Apparel & Accessories > Clothing > Tops",
        "product_type": "Women > Clothing > Tops > Short Sleeve T-shirts",
        "gtin": "1234567890123",
        "image_link": "https://example.com/images/product-main.jpg",
        "additional_image_links": "https://example.com/images/product-alt.jpg",
        "sb_image_url": "",
        "material": "Cotton",
        "mpn": "MPN123456",
        "size": "M",
        "price": 2999, // Price in cents
        "sale_price": 1999, // Sale price in cents
        "currency": "USD",
        "shipping_price": 0, // Shipping price in cents
        "shipping_country": "US",
        "shipping_currency": "USD",
        "shipping_weight": "200g",
        "link": "https://example.com/products/PROD123456",
        "product_highlight": "Soft and comfortable",
        "metadata": {
            "customLabel": "sale",
            "discount": "33%",
            "campaign": "Summer Sale"
        },
        "score": 0.91656494, // Similarity score
        "update_hash": "3adaf64f18cad3e8605de9cf9e4ee881",
        "product_updated_at": "",
        "updated_at": "2025-10-09T18:18:07+02:00",
        "created_at": "2025-09-01T21:21:04+02:00",
        "version": 13535319,
        "variants": [
            {
                "id": "variant-uuid-string",
                "product_id": "PROD123457",
                "item_group_id": "product item group id",
                "color": "Blue",
                "size": "S",
                "price": 2999, // Price in cents
                "currency": "USD",
                "sale_price": 1999, // Sale price in cents
                "image_link": "https://example.com/images/product-variant.jpg",
                "additional_image_links": "https://example.com/images/product-variant-alt.jpg",
                "availability": "in stock",
                "link": "https://example.com/products/PROD123457",
                "metadata": {
                    "discount": "33%",
                    "customLabel": "sale",
                    "campaign": "Summer Sale"
                }
            }
        ],
        "variant_count": 3
    }
    // More results...
]

Matching Set

GET /search/matching-set
POST /search/matching-set

Find all products that belong to the same matching set as a given product. A matching set groups products that are curated to be worn or used together.

Both methods accept the same parameters — as query parameters for GET, or as a JSON body for POST. Results are cached for 6 hours.

Parameters:

Parameter	Type	Required	Description
`productId`	string	Yes	The ID of the product to find matching set members for. Accepts a product ID or a variant ID — variant IDs are automatically resolved to their product
`feedId`	string	Yes	The customer feed ID
`idField`	string	No	Which ID to return for each match: `product_id` (default), `item_group_id`, or `variant_id`
`ignoreCache`	boolean	No	Set to `true` to bypass the cache and fetch fresh results

Example Requests:

curl 'https://search.koral.nu/api/v1/search/matching-set?productId=<product_id>&feedId=<feed_id>'

curl -X POST 'https://search.koral.nu/api/v1/search/matching-set' \
  -H 'Content-Type: application/json' \
  -d '{
    "productId": "<product_id>",
    "feedId": "<feed_id>",
    "idField": "item_group_id"
  }'

Response:

Returns the IDs of the products in the same matching set, using the field selected by idField. When idField is item_group_id, duplicate group IDs are removed.

{
  "matches": [
    "231956529",
    "231955952"
  ]
}

An empty matches array is returned when the product has no matching set members. Requests missing productId or feedId return 400. 404 is returned when the product or feed is unknown, or matching sets are not enabled for the account.

Complementary Products

GET /search/complementary
POST /search/complementary

Find products that complement a given product — items from other categories that go well together with it (for example a belt or shoes to go with a pair of trousers), rather than the curated set the product belongs to.

The endpoint works exactly like Matching Set: both methods accept the same parameters — as query parameters for GET, or as a JSON body for POST. Results are cached for 6 hours, separately from matching set results.

Parameters:

Parameter	Type	Required	Description
`productId`	string	Yes	The ID of the product to find complementary products for. Accepts a product ID or a variant ID — variant IDs are automatically resolved to their product
`feedId`	string	Yes	The customer feed ID
`idField`	string	No	Which ID to return for each match: `product_id` (default), `item_group_id`, or `variant_id`
`ignoreCache`	boolean	No	Set to `true` to bypass the cache and fetch fresh results

Example Requests:

curl 'https://search.koral.nu/api/v1/search/complementary?productId=<product_id>&feedId=<feed_id>'

curl -X POST 'https://search.koral.nu/api/v1/search/complementary' \
  -H 'Content-Type: application/json' \
  -d '{
    "productId": "<product_id>",
    "feedId": "<feed_id>",
    "idField": "item_group_id"
  }'

Response:

Returns the IDs of the complementary products, using the field selected by idField. When idField is item_group_id, duplicate group IDs are removed.

{
  "matches": [
    "231956529",
    "231955952"
  ]
}

An empty matches array is returned when the product has no complementary products. Requests missing productId or feedId return 400. 404 is returned when the product or feed is unknown, or complementary products are not enabled for the account.

Next Steps

See Examples for code samples and implementation guides
Learn about Error Handling

API Endpoints

API Endpoints

Base URL

Available Endpoints

Image Search

Detect objects

Related Products

Matching Set

Complementary Products

Next Steps