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.com/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 group id, used to group variants",
        "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": "GROUP123",
        "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",
                "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...
]

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

Next Steps