Sign InBook a Demo
Support

Search APIs

POSTVisual Search

Search products by uploading an image.

POSThttps://api.catalogix.ai/v1/visual-search
Search products by uploading an image. The image must be 32 MiB or smaller.

Authorization

Authorizationstringrequiredheader
Bearer token, Bearer <token>. Create one under Tokens in your workspace.

Query parameters

store_uuidstringrequired
Store identifier
Example: 69b3a770f5006c4b0be47c85
offsetintegerdefault: 0
Pagination offset
limitintegerdefault: 100
Maximum number of results
filtersstringdefault: "{}"
Filters as a JSON-encoded string. Example: '{"Category": "Tops", "Color": "Blue"}'. Must be valid JSON if provided, otherwise the request is rejected with 422.
Example: {"Category": "Tops", "Color": "Blue"}

Headers

X-Request-Idstring
Optional trace ID

Body

multipart/form-data required

imagefilerequired
Image file for visual search

Responses

200Successful response.
statusobject
Fields
codeinteger
0 = success, -1 = error
Example: 0
messagestring
Example: SUCCESS
request_idstring
Example: 8c8b2b7e-23d7-4c2a-91b0-2a7c4dfbb312
dataobject[]
List of visually similar products with relevance scores.
Item fields
product_codestring
Example: SKU001
scorenumber
Example: 0.92
image_urlstring
Example: https://cdn.example.com/img1.jpg
401Unauthorized – Bearer token missing or invalid
statusobject
Fields
codeinteger
Example: -1
messagestring
Example: Unauthorized – invalid or missing Bearer token
403The identity check rejected the caller: the token is not valid for this store
statusobjectrequired
Fields
codeinteger
Allowed: 1
Example: 1
messagestring
Example: Unable to verify caller identity
404No store with this `store_uuid`
statusobjectrequired
code is -1 and message explains the failure
Fields
codeintegerrequired
Status code of the operation. 1 means success. -1 means failure. 0 means process moved to background
Example: 0
messagestringrequired
Message describing the status
Example: success
request_idstring
Unique trace ID for the request. Echoed from X-Request-Id header or auto-generated.
Example: 8c8b2b7e-23d7-4c2a-91b0-2a7c4dfbb312
dataobjectrequired
Empty, except on a POST /v1/stores 502 where the store was created but a follow-up step failed: it then carries store_uuid and store_group so the store can be fixed with PUT or removed with DELETE.
Fields
store_uuidstring
Example: 699ec31355208b213e56059a
store_groupstring
Example: linked_store_id_abc
413The image is larger than 32 MiB
statusobjectrequired
code is -1 and message explains the failure
Fields
codeintegerrequired
Status code of the operation. 1 means success. -1 means failure. 0 means process moved to background
Example: 0
messagestringrequired
Message describing the status
Example: success
request_idstring
Unique trace ID for the request. Echoed from X-Request-Id header or auto-generated.
Example: 8c8b2b7e-23d7-4c2a-91b0-2a7c4dfbb312
dataobjectrequired
Empty, except on a POST /v1/stores 502 where the store was created but a follow-up step failed: it then carries store_uuid and store_group so the store can be fixed with PUT or removed with DELETE.
Fields
store_uuidstring
Example: 699ec31355208b213e56059a
store_groupstring
Example: linked_store_id_abc
422A parameter is missing or invalid
detailobject[]
Item fields
locstring | integer[]requireddefault: ["body",""]
msgstringrequireddefault: "Field Required"
typestringrequireddefault: "missing"
500Internal server error
statusobject
Fields
codeinteger
Example: -1
messagestring
Example: Internal server error. Please contact support@catalogix.ai
502The search service is unavailable or failed
statusobjectrequired
code is -1 and message explains the failure
Fields
codeintegerrequired
Status code of the operation. 1 means success. -1 means failure. 0 means process moved to background
Example: 0
messagestringrequired
Message describing the status
Example: success
request_idstring
Unique trace ID for the request. Echoed from X-Request-Id header or auto-generated.
Example: 8c8b2b7e-23d7-4c2a-91b0-2a7c4dfbb312
dataobjectrequired
Empty, except on a POST /v1/stores 502 where the store was created but a follow-up step failed: it then carries store_uuid and store_group so the store can be fixed with PUT or removed with DELETE.
Fields
store_uuidstring
Example: 699ec31355208b213e56059a
store_groupstring
Example: linked_store_id_abc
503Visual search is not set up for this store
statusobjectrequired
code is -1 and message explains the failure
Fields
codeintegerrequired
Status code of the operation. 1 means success. -1 means failure. 0 means process moved to background
Example: 0
messagestringrequired
Message describing the status
Example: success
request_idstring
Unique trace ID for the request. Echoed from X-Request-Id header or auto-generated.
Example: 8c8b2b7e-23d7-4c2a-91b0-2a7c4dfbb312
dataobjectrequired
Empty, except on a POST /v1/stores 502 where the store was created but a follow-up step failed: it then carries store_uuid and store_group so the store can be fixed with PUT or removed with DELETE.
Fields
store_uuidstring
Example: 699ec31355208b213e56059a
store_groupstring
Example: linked_store_id_abc

Something missing or unclear? Write to support@streamoid.com.

esc