API Endpoints
API Endpoints
Section titled “API Endpoints”This section provides detailed documentation for all available Koral API endpoints.
Base URL
Section titled “Base URL”All API requests should be made to the following base URL:
https://search.koral.com/api/v1Available Endpoints
Section titled “Available Endpoints”Image Search
Section titled “Image Search”POST /search/imageUpload 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
Section titled “Detect objects”POST /detectSearch 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}Related Products
Section titled “Related Products”POST /relatedFind related products based on a reference image or product ID.
Request Body:
{ "imageData": "<base64_encoded_image_data>", "productId": "<customer product id>", "limit": 10, "offset": 0, "searchId": "<customer feed id>"}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 |
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...]Next Steps
Section titled “Next Steps”- See Examples for code samples and implementation guides
- Learn about Error Handling