Navbar
Logo retina
http shell

Introduction

welcome

Welcome to the official documentation for Markable Lens API - for developers. This serves as a guide for developers integrate with Markable’s visual search platform API, illustrated using API specifications and API integration code examples.

To be able to use/access this API you will need to be a verified developer, please signup to get started. We’ll get back to you with your user credentials.

This API and documentation is subject to modifications.

Getting Started

To be able to use/access this API you will need to be a verified developer, please signup to get started. We’ll get back to you with your user credentials.

  1. Then, login with your user credentials.

  2. Once you have logged in, you will get your user_access_token. With this token, get your default Client we have created for you.

  3. Then, authenticate your Client to get your client_access_token.

  4. Make your first visual search. You will be using your client_access_token from above.

Rate Limits

For have fair usage of our APIs, we have enforced rate limits to the number of search results one can perform per minute. For each client,

Depending on your use case, you can get in touch to have your limits increased.

Errors

Markable uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error due to information provided (e.g., a required parameter was omitted or incorrectly formatted, a catalog item operation failed, etc.), and codes in the 5xx range indicate an error with our servers.

HTTP Error Codes

Code Description
400 Bad Request - The request format or JSON is invalid.
401 Unauthorized - The API key is wrong.
403 Forbidden - The specified resource is hidden for admins only.
404 Not Found - The specified specified could not be found.
405 Method Not Allowed - The request method is invalid for specified resource.
408 Timeout - The request has timed out.
409 Conflict Error - Duplicate resource prohibited.
413 Entity Too Large - The request exceeds size limit.
422 Validation Error - The request fails schema specifications.
429 Too Many Requests - You have reached your request per minute limit.
500 Internal Server Error - We had a problem with our server. Please try again later.
503 Service Unavailable - We’re temporarially offline for maintanance. Please try again later.

The Error Object

Example: Error Response

{
    "errors": [
        {
            "title": "Unauthorized",
            "id": "3f649f325620e5ddfa66f98c3945a7f7",
            "status": 401,
            "code": 401,
            "detail": "Authentication Error",
            "meta": {
                "timestamp": 1551820965551,
                "datetime": "2019-03-05T21:22:45.551Z"
            }
        }
    ]
}

A failed request will return a list of error objects according to the JSON API Specification.

An error object MAY have the following properties:

Attribute Description
title A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
id A unique identifier for this particular occurrence of the problem.
status The HTTP status code applicable to this problem, expressed as a string value.
code An application-specific error code, expressed as a string value.
detail A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
links A links object containing the following members.
source An object containing references to the source of the error.
meta An object containing non-standard information about the error.

Objects

The object defintions to be aware of when working with Markable Lens API.

catalog_icon Catalog

Example: Catalog Object

{
    "_type": "Catalog",
    "_id": "catalog_id_1"
    "schema": "product",
    "size": 0,
    "updated_at": "2019-03-07T22:06:51.885Z",
    "name": "catalog-1",
    "description": "my_first_catalog",
    "created_at": "2019-03-07T22:06:51.859Z",
    "access": "public",
    "user": {
        "_type": "User",
        "_id": "user_id_1"
    }, 
}

Schema: Catalog Object

{
    "title": "Catalog",
    "description": "A markable API catalog",
    "type": "object",
    "required": [
        "schema",
        "name",
        "user"
    ],
    "additionalProperties": false,
    "properties": {
        "_type": {
            "type": "string",
            "default": "Catalog",
            "readOnly": true
        },
        "meta": {
            "title": "Meta Information",
            "description": "Meta data for model",
            "type": "object"
        },
        "_id": {
            "title": "ID",
            "description": "Primary key",
            "type": "string"
        },
        "schema": {
            "title": "Schema",
            "description": "Determines type of catalog",
            "type": "string",
            "enum": [
                "product",
                "style"
            ]
        },
        "name": {
            "title": "Catalog name",
            "description": "Catalog name without spaces",
            "type": "string",
            "pattern": "^[a-zA-Z0-9_-]{4,}$"
        },
        "description": {
            "title": "Catalog description",
            "description": "Description of the catalog",
            "type": "string"
        },
        "access": {
            "title": "Catalog Access",
            "description": "Accessibility option of catalog",
            "type": "string",
            "enum": [
                "public",
                "private"
            ],
            "default": "private"
        },
        "priority": {
            "title": "Indexing priority",
            "type": "integer",
            "description": "Indexing priority of catalog",
            "default": 0
        },
        "enabled": {
            "title": "",
            "type": "boolean",
            "description": "",
            "default": true
        },
        "user": {
            "title": "User",
            "description": "User account that created catalog",
            "type": "object",
            "required": [
                "_id"
            ],
            "properties": {
                "_id": {
                    "title": "ID",
                    "description": "User ID",
                    "readOnly": true
                }
            }
        },
        "size": {
            "title": "Size",
            "description": "Catalog Size",
            "type": "integer"
        },
        "status": {
            "title": "Indexing Status",
            "description": "catalog indexing status",
            "type": "string",
            "enum": [
                "cv_active",
                "nn_active",
                "cv_pending",
                "nn_pending",
                "hold",
                "successful"
            ]
        },
        "error": {
            "title": "Error",
            "description": "Indexing errors",
            "type": "string",
            "default": null
        },
        "created_at": {
            "title": "Created At",
            "description": "Catalog created at timestamp",
            "type": "string",
            "format": "date-time"
        },
        "updated_at": {
            "title": "Updated At",
            "description": "Catalog updated at timestamp",
            "type": "string",
            "format": "date-time"
        },
        "deleted_at": {
            "title": "Deleted At",
            "description": "Catalog deleted at timestamp",
            "type": [
                "string",
                "null"
            ],
            "format": "date-time"
        },
        "indexing_started_at": {
            "title": "Indexing started at",
            "description": "Catalog indexing start timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "title": "cv indexing started at",
                    "description": "time cv indexing started",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                },
                "nn": {
                    "title": "nn indexing started at",
                    "description": "time nn indexing start",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                }
            }
        },
        "indexing_ended_at": {
            "title": "Indexing ended at",
            "description": "Catalog indexing end timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "title": "cv indexing ended at",
                    "description": "time cv indexing ended",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                },
                "nn": {
                    "title": "nn indexing ended at",
                    "description": "time nn indexing ended",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                }
            }
        }
    }
}

A Catalog defines a catalog/group of visual objects/items (e.g. products), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s). For us to be able to find what you looking for in your images/videos, the items (exact or similar) must be known to Markable‘s visual search engine, either using existing catalogs or custom defined catalogs.

Attribute Type Description
_type string Object type
meta object Meta Information
_id string A unique identifier
schema string The schema used for catalog’s items:
product or style
name string A custom name for the catalog
description string A custom description
access string Catalog accecssibility:
public or private
priority integer Indexing queue priority
enabled boolean Catalog indexing flag
user object Catalog owner reference
size integer Number or items in catalog
status string Catalog indexing status
error string Indexing Errors
created_at string (date-time) Creation of date/time.
updated_at string (date-time) Updated date/time
deleted_at string (date-time) Deleted date/time
indexing_started_at object Indexing operation start date/time
indexing_ended_at object Indexing oepration end date/time

catalog-item_icon Catalog Item

Example: Catalog Item Object

{
    "_id": "catalogitem-1",
    "images": [
        {
            "uri": "https://image_url_1.jpg",
            "_type": "Image",
            "status": "pending",
            "error": null
        },
        {
            "uri": "https://image_url_2.jpg",
            "_type": "Image",
            "status": "pending",
            "error": null
        },
    ],
    "data": {
        "stock": true,
        "name": "product name",
        "gender": "women",
        "price": 200,
        "brand": "new brand",
        "vendor": "new vendor",
        "country": "US",
        "sku": "2153608405:sweaters",
        "url": "https://productpage.com",
        "category": "sweaters",
    },
    "category": {
        "name": "sweaters",
        "id": "sweaters"
    },
    "_type": "CatalogItem",
    "created_at": "2019-03-11T20:41:35.105Z",
    "updated_at": "2019-03-11T20:41:35.106Z",
    "status": "cv_pending",
    "catalog": {
        "_type": "Catalog",
        "_id": "1",
        "name": "catalog-1"
    },
    "schema": "product",
    "fingerprint": "580498c0f46e206f13a8ed8ebfb3595a"
}

Schema: Catalog Item Object (Product)

{
    "title": "Catalog Item",
    "description": "A markable API product catalog item",
    "type": "object",
    "properties": {
        "meta": {
            "title": "Meta Information",
            "description": "Meta data for model",
            "type": "object"
        },
        "_type": {
            "type": "string",
            "default": "CatalogItem"
        },
        "_id": {
            "title": "ID",
            "description": "Primary key",
            "type": "string"
        },
        "fingerprint": {
            "title": "Fingerprint",
            "description": "Unique catalaog item hash",
            "type": "string"
        },
        "schema": {
            "title": "Schema",
            "description": "Determines type of catalog",
            "type": "string",
            "enum": [
                "product",
                "style"
            ],
            "default": "product"
        },
        "schema_version": {
            "title": "Schema Version",
            "description": "Version",
            "type": "string",
            "default": "null"
        },
        "catalog": {
            "title": "Catalog",
            "description": "Catalog to which item belogs to",
            "type": "object",
            "properties": {
                "_type": {
                    "type": "string",
                    "default": "Catalog"
                },
                "_id": {
                    "title": "ID",
                    "description": "Catalog ID"
                },
                "name": {
                    "title": "Name",
                    "description": "Catalog name",
                    "type": "string"
                }
            },
            "required": [
                "_id",
                "name"
            ]
        },
        "images": {
            "title": "Images",
            "description": "Images in catalog item",
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
                "$ref": "#/definitions/image"
            }
        },
        "category": {
            "title": "Category",
            "description": "Catalog Item Category",
            "type": [
                "string",
                "null"
            ],
            "default": "null"
        },
        "attributes": {
            "title": "Attributes",
            "description": "Catalog Item Attributes",
            "type": [
                "object",
                "null"
            ]
        },
        "data": {
            "title": "Data",
            "description": "Catalog item data properties",
            "type": "object",
            "properties": {
                "id": {
                    "title": "ID",
                    "description": "Catalog Item ID",
                    "type": "string"
                },
                "url": {
                    "title": "URL",
                    "description": "Catalog Item URL",
                    "type": "string",
                    "pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
                },
                "sku": {
                    "title": "SKU",
                    "description": "Catalog Item Stock Keeping Unit",
                    "type": "string"
                },
                "description": {
                    "title": "Description",
                    "description": "Catalog Item Description",
                    "type": "string"
                },
                "name": {
                    "title": "Name",
                    "description": "Catalog Item Name",
                    "type": "string"
                },
                "brand": {
                    "title": "Brand",
                    "description": "Catalog Item Brand",
                    "type": "string"
                },
                "vendor": {
                    "title": "Vendor",
                    "description": "Catalog Item Vendor",
                    "type": "string"
                },
                "category": {
                    "title": "Category",
                    "description": "Normalized Catalog Item Category",
                    "type": "string"
                },
                "gender": {
                    "title": "Gender",
                    "description": "Catalog Item Gender",
                    "enum": [
                        "men",
                        "women",
                        "unisex"
                    ]
                },
                "color": {
                    "title": "Color",
                    "description": "Catalog Item Color",
                    "type": "string"
                },
                "price": {
                    "title": "Price",
                    "description": "Catalog Item Price",
                    "type": "number"
                },
                "currency": {
                    "title": "Currency",
                    "description": "Catalog Item Currency",
                    "type": "string",
                    "default": "USD"
                }
            },
            "required": [
                "url"
            ],
            "additionalProperties": true
        },
        "status": {
            "title": "Status",
            "description": "Catalog Item Indexing Status",
            "type": "string",
            "enum": [
                "cv_pending",
                "nn_pending",
                "successful",
                "nodetections",
                "failed"
            ]
        },
        "error": {
            "title": "Error",
            "description": "Errors produced during indexing",
            "type": "object",
            "default": "null"
        },
        "failed_count": {
            "title": "Data",
            "description": "Catalog item data properties",
            "type": "object",
            "properties": {
                "cv": {
                    "type": "integer",
                    "default": 0
                },
                "nn": {
                    "type": "integer",
                    "default": 0
                }
            }
        },
        "created_at": {
            "title": "Created At",
            "description": "Catalog Item created at timestamp",
            "type": "string",
            "format": "date-time"
        },
        "updated_at": {
            "title": "Updated At",
            "description": "Catalog Item updated timestamp",
            "type": "string",
            "format": "date-time"
        },
        "indexed_started_at": {
            "title": "Indexed Start At",
            "description": "Catalog Item indexing start timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "type": "string",
                    "format": "date-time"
                },
                "nn": {
                    "type": "string",
                    "format": "date-time"
                }
            }
        },
        "indexed_ended_at": {
            "title": "Indexed End At",
            "description": "Catalog item indexing end timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "type": "string",
                    "format": "date-time"
                },
                "nn": {
                    "type": "string",
                    "format": "date-time"
                }
            }
        }
    },
    "additionalProperties": false,
    "if": {
        "properties": {
            "schema": {
                "enum": [
                    "product"
                ]
            }
        },
        "required": [
            "schema"
        ]
    },
    "then": {
        "required": [
            "category",
            "images",
            "data"
        ]
    },
    "else": {
        "required": [
            "images",
            "data"
        ]
    },
    "definitions": {
        "image": {
            "title": "Image",
            "description": "Image",
            "type": "object",
            "properties": {
                "_type": {
                    "type": "string",
                    "default": "Image"
                },
                "_id": {
                    "title": "Upload ID",
                    "type": "string"
                },
                "hash": {
                    "title": "Hash",
                    "description": "Unique image hash",
                    "type": "string"
                },
                "uri": {
                    "title": "URI",
                    "description": "Image URI",
                    "type": "string",
                    "pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
                },
                "width": {
                    "title": "Width",
                    "description": "Image width",
                    "type": [
                        "number",
                        "null"
                    ],
                    "default": null,
                    "minimum": 0
                },
                "height": {
                    "title": "Height",
                    "description": "Image height",
                    "type": [
                        "number",
                        "null"
                    ],
                    "default": null,
                    "minimum": 0
                },
                "thumbnail": {
                    "title": "Thumbnail",
                    "description": "Thumbnail Upload",
                    "type": "object",
                    "properties": {
                        "uri": {
                            "title": "Thumbnail URI",
                            "type": "string",
                            "pattern": "^(http://?|https://?)"
                        },
                        "width": {
                            "title": "Width",
                            "description": "Image width",
                            "type": [
                                "number",
                                "null"
                            ],
                            "default": null,
                            "minimum": 0
                        },
                        "height": {
                            "title": "Height",
                            "description": "Image height",
                            "type": [
                                "number",
                                "null"
                            ],
                            "default": null,
                            "minimum": 0
                        }
                    }
                },
                "snapshot": {
                    "title": "Snapshot",
                    "type": "object",
                    "properties": {
                        "uri": {
                            "title": "URI",
                            "type": "string",
                            "pattern": "^(http://?|https://?)"
                        },
                        "path": {
                            "title": "Path",
                            "type": "string",
                            "pattern": "^file://"
                        }
                    }
                },
                "status": {
                    "title": "Image Indexing Status",
                    "type": "string",
                    "enum": [
                        "pending",
                        "error",
                        "success"
                    ]
                },
                "error": {
                    "title": "Error",
                    "description": "Indexing errors",
                    "type": [
                        "object",
                        "null"
                    ]
                },
                "stats": {
                    "title": "Statistics",
                    "description": "Image processing statistics",
                    "type": "object"
                },
                "model": {
                    "title": "Model",
                    "description": "Image model used in detection",
                    "type": "string"
                },
                "detections": {
                    "title": "Detections",
                    "description": "Image cv detections",
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/detection"
                    }
                }
            },
            "required": [
                "uri"
            ],
            "additionalProperties": false
        },
        "detection": {
            "title": "Detection",
            "description": "Detected item",
            "type": "object",
            "properties": {
                "_id": {
                    "title": "ID",
                    "description": "Detection ID",
                    "type": "string"
                },
                "bounding_box": {
                    "title": "Bounding Box",
                    "description": "Detection bounding box specifications",
                    "type": "object",
                    "properties": {
                        "x": {
                            "title": "X-coordinate",
                            "description": "bounding box x coordinate",
                            "type": "integer"
                        },
                        "y": {
                            "title": "Y-coordinate",
                            "description": "bounding box y coordinate",
                            "type": "integer"
                        },
                        "width": {
                            "title": "Width",
                            "description": "bounding box width",
                            "type": "integer"
                        },
                        "height": {
                            "title": "Height",
                            "description": "bounding box height",
                            "type": "integer"
                        }
                    },
                    "required": [
                        "x",
                        "y",
                        "width",
                        "height"
                    ],
                    "additionalProperties": false
                },
                "category": {
                    "title": "Category",
                    "description": "Detected category",
                    "type": "string"
                },
                "score": {
                    "title": "Score",
                    "description": "Detection confidence",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                },
                "attributes": {
                    "title": "Attributes",
                    "description": "Detection attributes",
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/attribute"
                    }
                },
                "feature": {
                    "type": "object",
                    "title": "Feature Vector",
                    "description": "Detection Feature Vectors",
                    "properties": {
                        "hash": {
                            "title": "Hash",
                            "description": "MD5 Hash of Feature Vectors",
                            "type": "string",
                            "minLength": 32
                        },
                        "vector": {
                            "title": "Vector",
                            "description": "Detection Feature Vectors",
                            "type": "array",
                            "minLength": 128,
                            "maxItems": 128
                        }
                    },
                    "required": [
                        "hash",
                        "vector"
                    ]
                }
            },
            "required": [
                "bounding_box",
                "category",
                "score",
                "feature"
            ],
            "additionalProperties": false
        },
        "attribute": {
            "title": "Attribute",
            "description": "Detection Attribute Type",
            "type": "object",
            "properties": {
                "name": {
                    "title": "Name",
                    "description": "Attribute Name",
                    "type": "string",
                    "minLength": 1
                },
                "values": {
                    "title": "Values",
                    "description": "Attribute Values",
                    "type": "array",
                    "items": {
                        "title": "Value",
                        "description": "Label and Score",
                        "type": "object",
                        "properties": {
                            "value": {
                                "title": "Value",
                                "description": "Attribute Value Label",
                                "type": "string",
                                "minLength": 1
                            },
                            "score": {
                                "title": "Score",
                                "description": "Attribute Confidence Score",
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1
                            }
                        }
                    }
                }
            },
            "required": [
                "name",
                "value",
                "score"
            ],
            "additionalProperties": false
        }
    }
}

A Catalog Item defines an visual object/item (e.g. product), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s).

Attribute Type Description
_type string Object type
meta object Meta Information
_id string A unique identifier
fingerprint string Unique catalog item hash
schema string The schema used for catalog’s items:
product or style
schema_version string Schema Version Tag
catalog object Catalog reference
images array Visual representation of this item
category string Taxonomic classification of item
data object Custom - semantic representation of item
status string Indexing status of item
cv_pending, nn_pending, successful, nodetections, failed
error object Errors produced during indexing operations
failed_count object Count of failures during indexing operations
created_at string (date-time) Creation date/time
updated_at string (date-time) Updated date/time
indexing_started_at object Indexing operation start date/time
indexing_ended_at object Indexing oepration end date/time

Authentication

To access Markable Lens API you will need to be a registered developer, if you are not already you need to signup and get verified first.

User

Once you have your user account setup, (ie) your email and password ready, you can get your user_access_token.

These user access tokens can be further used to create Clients. Clients have access tokens of their own.

Example: User Credentials Object

{
    "email": "developer@client.com",
    "password": "password"
}

User Authentication

Example: Request

POST https://auth.markable.ai/auth/user/authorize HTTP/1.1
{
    "data": {
        "email": "developer@client.com",
        "password": "password"
    }
}
curl -X POST https://auth.markable.ai/auth/user/authorize \
-H 'Content-Type: application/json' \
-d '
{
    "data": {
        "email": "developer@client.com",
        "password": "password"
    }
}
'

Example: Response with User Access Token

{ 
    "data": {
        "user_id": "1",
        "created_at": "2019-03-11T20:39:41.998Z",
        "deleted_at": null,
        "type": "Token",
        "updated_at": "2019-03-11T20:39:42.010Z",
        "access_token": "5c86c78e059dc998f2c80278",
        "expires_at": "2024-03-09T20:39:41.998Z"
    }
}

Create authorization (authentication token) for a user.

HTTP Request

POST https://auth.markable.ai/auth/user/authorize

HTTP Headers

Standard

Query Parameters

None

Body

Attribute Type Description
data UserCredentials A valid user credentials object.

Get User and Client

This request gives you user information and further the default client we have created for you. Note that scopes are a concern of tokens and not clients.

GET https://auth.markable.ai/auth/users/ HTTP/1.1
Authorization: Bearer usertoken123abc
curl -X GET https://auth.markable.ai/auth/users/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer usertoken123abc'

Example: Response


{
    "data": {
        "name": "Developer at Client",
        "website": "http://client.website.com",
        "role": "user",
        "email": "developer@client.com",
        "company": "company_name",
        "created_at": "2019-03-11T20:39:34.690Z",
        "type": "User",
        "updated_at": "2019-03-11T20:39:34.781Z",
        "user_id": "user_id_1",
        "clients": [
            {
                "client_secret": "client_secret_1",
                "user_id": "user_id_1",
                "domain": "http://localhost",
                "created_at": "2019-03-11T20:39:34.789Z",
                "type": "Client",
                "updated_at": "2019-03-11T20:39:34.801Z",
                "client_id": "client_id_1"
            }
        ]
    }
}

HTTP Request

GET https://auth.markable.ai/auth/users

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :user_access_token, where user_access_token is given by Authentication. required

Client Authentication

To start out with, we have created a default client for you as a user.

For the Lens API, you will be using your client acccess token with every request.

The Client Credentials Object

Example: Client Credentials Object

{
  "client_id": "client_id_1",
  "client_secret": "client_secret_1",
  "scope": "default"
}

The Client Credentials (object) refers to an object that holds your Markable Lens API credentials, i.e. key token (client_id) and secret token (client_secret). These credentials will be available to any verified developer.

Attribute Description
client_id Client ID - i.e. “API key”. required
client_secret Client secret - i.e. “API secret”. required
scope The scope of how the client can be used. Currently ['default', 'search']

Example: Request

POST https://auth.markable.ai/auth/client/authorize HTTP/1.1
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "default"
  }
}
curl -X POST https://auth.markable.ai/auth/client/authorize \
-H 'Content-Type: application/json' \
-d '
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "default"
  }
}
'

Example: Request for Search only tokens that can be Published

POST https://auth.markable.ai/auth/client/authorize HTTP/1.1
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "search"
  }
}
curl -X POST https://auth.markable.ai/auth/client/authorize \
-H 'Content-Type: application/json' \
-d '
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "search"
  }
}
'

Example: Response Client Access Token

{
    "data": {
        "user_id": "user_id_1",
        "client_id": "client_id_1",
        "scope": "default",
        "created_at": "2019-03-11T20:40:12.710Z",
        "type": "Token",
        "updated_at": "2019-03-11T20:40:12.723Z",
        "access_token": "5c86c7ac1fa31898e65269fc",
        "expires_at": "2024-03-09T20:40:12.710Z"
    }
}

Create authorization (authentication token) for a client.

Security

With the search scope, the resulting client access tokens can be published on the web and will only allow you to do searches. The default tokens on the other hand allow all operations.

HTTP Request

POST https://auth.markable.ai/auth/client/authorize

HTTP Headers

Standard

Query Parameters

None

Body

Attribute Type Description
data ClientCredentials A valid client credentials object.

Catalogs Catalogs

catalog_icon The Catalog Object

A Catalog (object) defines a catalog/group of visual items (e.g. products), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s). For us to be able to find what you looking for in your images/videos the items (exact or similar) must be known to Markable‘s visual search engine, either using existing catalogs or your customly defined catalogs.

Catalogs can be of two different schemas: product and style.

Product Catalogs

Product catalogs can be a list of products sold online in a retail store. Each CatalogItem in the catalog contains images, category, a url that links to the product at the store, and gender associated associated with the item, e.g, men, women, unisex.

Style Catalogs

Style catalogs, however, are free form catalogs with just images and a designated gender. Style catalogs for example, can be comprised of a list of street images.

Example: Catalog Object

{
    "_type": "Catalog",
    "_id": "catalog_id_1",
    "schema": "product",
    "name": "catalog_name_1",
    "description": "My product catalog",
    "size": 5,
    "access": "public",
    "created_at": "2018-12-06T22:11:51.391Z",
    "updated_at": "2019-03-09T03:09:17.309Z",
    "user": {
        "_type": "User",
        "_id": "user_id_1"
    },
},
{
    "_type": "Catalog",
    "_id": "catalog_id_2",
    "schema": "style",
    "name": "catalog_name_2",
    "description": "My style catalog",
    "size": 10,
    "access": "public",
    "created_at": "2018-12-06T22:11:51.391Z",
    "updated_at": "2019-03-09T03:09:17.309Z",
    "user": {
        "_type": "User",
        "_id": "user_id_1"
    },
},

Schema: Catalog Object

{
    "title": "Catalog",
    "description": "A markable API catalog",
    "type": "object",
    "required": [
        "schema",
        "name",
        "user"
    ],
    "additionalProperties": false,
    "properties": {
        "_type": {
            "type": "string",
            "default": "Catalog",
            "readOnly": true
        },
        "meta": {
            "title": "Meta Information",
            "description": "Meta data for model",
            "type": "object"
        },
        "_id": {
            "title": "ID",
            "description": "Primary key",
            "type": "string"
        },
        "schema": {
            "title": "Schema",
            "description": "Determines type of catalog",
            "type": "string",
            "enum": [
                "product",
                "style"
            ]
        },
        "name": {
            "title": "Catalog name",
            "description": "Catalog name without spaces",
            "type": "string",
            "pattern": "^[a-zA-Z0-9_-]{4,}$"
        },
        "description": {
            "title": "Catalog description",
            "description": "Description of the catalog",
            "type": "string"
        },
        "access": {
            "title": "Catalog Access",
            "description": "Accessibility option of catalog",
            "type": "string",
            "enum": [
                "public",
                "private"
            ],
            "default": "private"
        },
        "priority": {
            "title": "Indexing priority",
            "type": "integer",
            "description": "Indexing priority of catalog",
            "default": 0
        },
        "enabled": {
            "title": "",
            "type": "boolean",
            "description": "",
            "default": true
        },
        "user": {
            "title": "User",
            "description": "User account that created catalog",
            "type": "object",
            "required": [
                "_id"
            ],
            "properties": {
                "_id": {
                    "title": "ID",
                    "description": "User ID",
                    "readOnly": true
                }
            }
        },
        "size": {
            "title": "Size",
            "description": "Catalog Size",
            "type": "integer"
        },
        "status": {
            "title": "Indexing Status",
            "description": "catalog indexing status",
            "type": "string",
            "enum": [
                "cv_active",
                "nn_active",
                "cv_pending",
                "nn_pending",
                "hold",
                "successful"
            ]
        },
        "error": {
            "title": "Error",
            "description": "Indexing errors",
            "type": "string",
            "default": null
        },
        "created_at": {
            "title": "Created At",
            "description": "Catalog created at timestamp",
            "type": "string",
            "format": "date-time"
        },
        "updated_at": {
            "title": "Updated At",
            "description": "Catalog updated at timestamp",
            "type": "string",
            "format": "date-time"
        },
        "deleted_at": {
            "title": "Deleted At",
            "description": "Catalog deleted at timestamp",
            "type": [
                "string",
                "null"
            ],
            "format": "date-time"
        },
        "indexing_started_at": {
            "title": "Indexing started at",
            "description": "Catalog indexing start timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "title": "cv indexing started at",
                    "description": "time cv indexing started",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                },
                "nn": {
                    "title": "nn indexing started at",
                    "description": "time nn indexing start",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                }
            }
        },
        "indexing_ended_at": {
            "title": "Indexing ended at",
            "description": "Catalog indexing end timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "title": "cv indexing ended at",
                    "description": "time cv indexing ended",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                },
                "nn": {
                    "title": "nn indexing ended at",
                    "description": "time nn indexing ended",
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                }
            }
        }
    }
}
Attribute Type Description
_type string Object type
meta object Meta Information
_id string A unique identifier
schema string The schema used for catalog’s items:
product or style
name string A custom name for the catalog
description string A custom description
access string Catalog accecssibility:
public or private
priority integer Indexing queue priority
enabled boolean Catalog indexing flag
user object Catalog owner reference
size integer Number or items in catalog
status string Catalog indexing status
error string Indexing Errors
created_at string (date-time) Creation of date/time.
updated_at string (date-time) Updated date/time
deleted_at string (date-time) Deleted date/time
indexing_started_at object Indexing operation start date/time
indexing_ended_at object Indexing oepration end date/time

create-catalog_icon Create catalog

Example: Request

POST https://catalog.markable.ai/catalogs HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "access": "public"
    }
}
curl -X POST https://catalog.markable.ai/catalogs \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "access": "public"
    }
}
'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "catalog_id_1"
        "schema": "product",
        "name": "catalog_1",
        "description": "My new catalog",
        "size": 0,
        "access": "public",
        "created_at": "2019-03-11T20:40:36.726Z",
        "updated_at": "2019-03-11T20:40:36.753Z",
        "user": {
            "_type": "User",
            "_id": "user_id_1"
        },
    }
}

Create a new catalog.

HTTP Request

POST https://catalog.markable.ai/catalogs

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

None

Body

Attribute Type Description
data Catalog A valid catalog object.

update-catalog_icon Update catalog

Example: Request

PUT https://catalog.markable.ai/catalogs/catalog_id_1 HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "name": "new_name_1",
        "description": "Revised catalog description"
    }
}
curl -X PUT https://catalog.markable.ai/catalogs/catalog_id_1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "name": "new_name_1",
        "description": "Revised catalog description"
    }
}
'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "catalog_id_1"
        "schema": "product",
        "name": "new_name_1",
        "description": "Revised catalog description",
        "size": 0,
        "access": "public",
        "created_at": "2019-03-11T20:40:36.726Z",
        "updated_at": "2019-03-11T20:40:36.753Z",
        "user": {
            "_type": "User",
            "_id": "user_id_1"
        },
    }
}

Update an existing catalog.

HTTP Request

PUT https://catalog.markable.ai/catalogs/:catalogId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

Body

Attribute Type Description
data Catalog A valid catalog object.

delete-catalog_icon Delete catalog

Example: Request

DELETE https://catalog.markable.ai/catalogs/catalog_id_1 HTTP/1.1
Authorization: Bearer 123abc
curl -X DELETE https://catalog.markable.ai/catalogs/catalog_id_1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "catalog_id_1",
        "schema": "product",
        "name": "new_name_1",
        "description": "Revised catalog description",
        "size": 0,
        "access": "public",
        "created_at": "2019-03-11T20:40:36.726Z",
        "updated_at": "2019-03-11T20:41:35.129Z",
        "user": {
            "_type": "User",
            "_id": "user_id_1"
        }
    }
}

Delete an existing catalog.

HTTP Request

DELETE https://catalog.markable.ai/catalogs/:catalogId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

get-catalog-objects_icon Get catalog

Example: Request

GET https://catalog.markable.ai/catalogs/catalog_id_1 HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog_id_1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_id": "catalog_id_1",
        "_type": "Catalog",
        "schema": "product",
        "name": "catalog_1",
        "description": "My new catalog",
        "size": 0,
        "access": "public",
        "created_at": "2019-03-12T00:19:33.448Z",
        "updated_at": "2019-03-12T00:19:33.478Z",
        "user": {
            "_type": "User",
            "_id": "user_id_1"
        }
    }
}

Get an existing catalog.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

list-catalog-objects_icon List catalogs

Example: Request

GET https://catalog.markable.ai/catalogs HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": [
        {
            "_id": "catalog_id_1",
            "_type": "Catalog",
            "schema": "product",
            "name": "product_catalog",
            "description": "catalog_2",
            "size": 0,
            "access": "public",
            "created_at": "2019-03-12T00:19:33.448Z",
            "updated_at": "2019-03-12T00:19:33.478Z",
            "user": {
                "_type": "User",
                "_id": "user_id_1"
            }
        },
        {
            "_id": "catalog_id_2",
            "_type": "Catalog",
            "schema": "style",
            "name": "style_catalog",
            "description": "style catalog",
            "size": 0,
            "access": "private",
            "created_at": "2019-03-12T00:22:02.002Z",
            "updated_at": "2019-03-12T00:22:02.030Z",
            "user": {
                "_type": "User",
                "_id": "user_id_1"
            }
        }
    ]
}

Get all existing catalogs.

HTTP Request

GET https://catalog.markable.ai/catalogs

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

None

Query Parameters

Parameter Description
limit The limit of items to return (defaults to 50).
skip The skip of items to return.

get-catalog-objects_icon Catalog Stats

Catalog statistics explaning

Example: Request

GET https://catalog.markable.ai/catalogs/catalog_id_1/stats HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog_id_1/stats \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "category": [
            {
                "_id": "skirts",
                "total": 1
            },
            {
                "_id": "glasses",
                "total": 1
            },
            {
                "_id": "jeans",
                "total": 1
            },
            {
                "_id": "overalls",
                "total": 1
            },
            {
                "_id": "tanks_camis",
                "total": 1
            }
        ],
        "status": [
            {
                "_id": "error",
                "total": 1
            },
            {
                "_id": "ok",
                "total": 1
            },
            {
                "_id": "pending",
                "total": 1
            }
        ],
        "gender": [
            {
                "_id": "men",
                "total": 1
            },
            {
                "_id": "women",
                "total": 1
            }
        ],
        "errors": [
            {
                "_id": null,
                "total": 1
            }
        ],
        "catalog": {
            "_type": "Catalog",
            "_id": "catalog_id_1",
            "schema": "product",
            "name": "product_catalog",
            "description": "My product catalog",
            "size": 10,
            "access": "private",
            "created_at": "2018-12-06T22:11:51.391Z",
            "updated_at": "2019-03-02T17:40:40.728Z",
            "user": {
                "_type": "User",
                "_id": "user_id_1"
            },
        }
    }
}

Stats for an existing catalog.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId/stats

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

list-catalog-objects_icon List public catalogs

Example: Request

GET https://catalog.markable.ai/catalogs/public HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/public \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": [
        {
            "_id": "catalog_id_1",
            "_type": "Catalog",
            "schema": "product",
            "size": 0,
            "updated_at": "2019-03-12T00:19:33.478Z",
            "name": "product_catalog",
            "description": "catalog_2",
            "created_at": "2019-03-12T00:19:33.448Z",
            "access": "public",
            "user": {
                "_type": "User",
                "_id": "user_id_1"
            }
        },
        {
            "_id": "catalog_id_4",
            "_type": "Catalog",
            "schema": "style",
            "size": 0,
            "updated_at": "2019-03-12T00:22:02.030Z",
            "name": "style_catalog_4",
            "description": "style catalog 4",
            "created_at": "2019-03-12T00:22:02.002Z",
            "access": "public",
            "user": {
                "_type": "User",
                "_id": "user_id_2"
            }
        }
    ]
}

Get all existing catalogs.

HTTP Request

GET https://catalog.markable.ai/catalogs/public

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

None

Catalog Items Catalog-items

catalog-items-objects_icon The Catalog Item Object

Example: Catalog Item Object

{
    "_id": "catalogitem-1",
    "images": [
        {
            "uri": "https://image_url_1.jpg",
            "_type": "Image",
            "status": "pending",
            "error": null
        },
        {
            "uri": "https://image_url_2.jpg",
            "_type": "Image",
            "status": "pending",
            "error": null
        },
    ],
    "data": {
        "stock": true,
        "name": "product name",
        "gender": "women",
        "price": 200,
        "brand": "new brand",
        "vendor": "new vendor",
        "country": "US",
        "sku": "2153608405:sweaters",
        "url": "https://productpage.com",
        "category": "sweaters",
    },
    "category": {
        "name": "sweaters",
        "id": "sweaters"
    },
    "_type": "CatalogItem",
    "created_at": "2019-03-11T20:41:35.105Z",
    "updated_at": "2019-03-11T20:41:35.106Z",
    "status": "cv_pending",
    "catalog": {
        "_type": "Catalog",
        "_id": "1",
        "name": "catalog-1"
    },
    "schema": "product",
    "fingerprint": "580498c0f46e206f13a8ed8ebfb3595a"
}

Schema: Catalog Item Object (Product)

{
    "title": "Catalog Item",
    "description": "A markable API product catalog item",
    "type": "object",
    "properties": {
        "meta": {
            "title": "Meta Information",
            "description": "Meta data for model",
            "type": "object"
        },
        "_type": {
            "type": "string",
            "default": "CatalogItem"
        },
        "_id": {
            "title": "ID",
            "description": "Primary key",
            "type": "string"
        },
        "fingerprint": {
            "title": "Fingerprint",
            "description": "Unique catalaog item hash",
            "type": "string"
        },
        "schema": {
            "title": "Schema",
            "description": "Determines type of catalog",
            "type": "string",
            "enum": [
                "product",
                "style"
            ],
            "default": "product"
        },
        "schema_version": {
            "title": "Schema Version",
            "description": "Version",
            "type": "string",
            "default": "null"
        },
        "catalog": {
            "title": "Catalog",
            "description": "Catalog to which item belogs to",
            "type": "object",
            "properties": {
                "_type": {
                    "type": "string",
                    "default": "Catalog"
                },
                "_id": {
                    "title": "ID",
                    "description": "Catalog ID"
                },
                "name": {
                    "title": "Name",
                    "description": "Catalog name",
                    "type": "string"
                }
            },
            "required": [
                "_id",
                "name"
            ]
        },
        "images": {
            "title": "Images",
            "description": "Images in catalog item",
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
                "$ref": "#/definitions/image"
            }
        },
        "category": {
            "title": "Category",
            "description": "Catalog Item Category",
            "type": [
                "string",
                "null"
            ],
            "default": "null"
        },
        "attributes": {
            "title": "Attributes",
            "description": "Catalog Item Attributes",
            "type": [
                "object",
                "null"
            ]
        },
        "data": {
            "title": "Data",
            "description": "Catalog item data properties",
            "type": "object",
            "properties": {
                "id": {
                    "title": "ID",
                    "description": "Catalog Item ID",
                    "type": "string"
                },
                "url": {
                    "title": "URL",
                    "description": "Catalog Item URL",
                    "type": "string",
                    "pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
                },
                "sku": {
                    "title": "SKU",
                    "description": "Catalog Item Stock Keeping Unit",
                    "type": "string"
                },
                "description": {
                    "title": "Description",
                    "description": "Catalog Item Description",
                    "type": "string"
                },
                "name": {
                    "title": "Name",
                    "description": "Catalog Item Name",
                    "type": "string"
                },
                "brand": {
                    "title": "Brand",
                    "description": "Catalog Item Brand",
                    "type": "string"
                },
                "vendor": {
                    "title": "Vendor",
                    "description": "Catalog Item Vendor",
                    "type": "string"
                },
                "category": {
                    "title": "Category",
                    "description": "Normalized Catalog Item Category",
                    "type": "string"
                },
                "gender": {
                    "title": "Gender",
                    "description": "Catalog Item Gender",
                    "enum": [
                        "men",
                        "women",
                        "unisex"
                    ]
                },
                "color": {
                    "title": "Color",
                    "description": "Catalog Item Color",
                    "type": "string"
                },
                "price": {
                    "title": "Price",
                    "description": "Catalog Item Price",
                    "type": "number"
                },
                "currency": {
                    "title": "Currency",
                    "description": "Catalog Item Currency",
                    "type": "string",
                    "default": "USD"
                }
            },
            "required": [
                "url"
            ],
            "additionalProperties": true
        },
        "status": {
            "title": "Status",
            "description": "Catalog Item Indexing Status",
            "type": "string",
            "enum": [
                "cv_pending",
                "nn_pending",
                "successful",
                "nodetections",
                "failed"
            ]
        },
        "error": {
            "title": "Error",
            "description": "Errors produced during indexing",
            "type": "object",
            "default": "null"
        },
        "failed_count": {
            "title": "Data",
            "description": "Catalog item data properties",
            "type": "object",
            "properties": {
                "cv": {
                    "type": "integer",
                    "default": 0
                },
                "nn": {
                    "type": "integer",
                    "default": 0
                }
            }
        },
        "created_at": {
            "title": "Created At",
            "description": "Catalog Item created at timestamp",
            "type": "string",
            "format": "date-time"
        },
        "updated_at": {
            "title": "Updated At",
            "description": "Catalog Item updated timestamp",
            "type": "string",
            "format": "date-time"
        },
        "indexed_started_at": {
            "title": "Indexed Start At",
            "description": "Catalog Item indexing start timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "type": "string",
                    "format": "date-time"
                },
                "nn": {
                    "type": "string",
                    "format": "date-time"
                }
            }
        },
        "indexed_ended_at": {
            "title": "Indexed End At",
            "description": "Catalog item indexing end timestamp",
            "type": "object",
            "properties": {
                "cv": {
                    "type": "string",
                    "format": "date-time"
                },
                "nn": {
                    "type": "string",
                    "format": "date-time"
                }
            }
        }
    },
    "additionalProperties": false,
    "if": {
        "properties": {
            "schema": {
                "enum": [
                    "product"
                ]
            }
        },
        "required": [
            "schema"
        ]
    },
    "then": {
        "required": [
            "category",
            "images",
            "data"
        ]
    },
    "else": {
        "required": [
            "images",
            "data"
        ]
    },
    "definitions": {
        "image": {
            "title": "Image",
            "description": "Image",
            "type": "object",
            "properties": {
                "_type": {
                    "type": "string",
                    "default": "Image"
                },
                "_id": {
                    "title": "Upload ID",
                    "type": "string"
                },
                "hash": {
                    "title": "Hash",
                    "description": "Unique image hash",
                    "type": "string"
                },
                "uri": {
                    "title": "URI",
                    "description": "Image URI",
                    "type": "string",
                    "pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
                },
                "width": {
                    "title": "Width",
                    "description": "Image width",
                    "type": [
                        "number",
                        "null"
                    ],
                    "default": null,
                    "minimum": 0
                },
                "height": {
                    "title": "Height",
                    "description": "Image height",
                    "type": [
                        "number",
                        "null"
                    ],
                    "default": null,
                    "minimum": 0
                },
                "thumbnail": {
                    "title": "Thumbnail",
                    "description": "Thumbnail Upload",
                    "type": "object",
                    "properties": {
                        "uri": {
                            "title": "Thumbnail URI",
                            "type": "string",
                            "pattern": "^(http://?|https://?)"
                        },
                        "width": {
                            "title": "Width",
                            "description": "Image width",
                            "type": [
                                "number",
                                "null"
                            ],
                            "default": null,
                            "minimum": 0
                        },
                        "height": {
                            "title": "Height",
                            "description": "Image height",
                            "type": [
                                "number",
                                "null"
                            ],
                            "default": null,
                            "minimum": 0
                        }
                    }
                },
                "snapshot": {
                    "title": "Snapshot",
                    "type": "object",
                    "properties": {
                        "uri": {
                            "title": "URI",
                            "type": "string",
                            "pattern": "^(http://?|https://?)"
                        },
                        "path": {
                            "title": "Path",
                            "type": "string",
                            "pattern": "^file://"
                        }
                    }
                },
                "status": {
                    "title": "Image Indexing Status",
                    "type": "string",
                    "enum": [
                        "pending",
                        "error",
                        "success"
                    ]
                },
                "error": {
                    "title": "Error",
                    "description": "Indexing errors",
                    "type": [
                        "object",
                        "null"
                    ]
                },
                "stats": {
                    "title": "Statistics",
                    "description": "Image processing statistics",
                    "type": "object"
                },
                "model": {
                    "title": "Model",
                    "description": "Image model used in detection",
                    "type": "string"
                },
                "detections": {
                    "title": "Detections",
                    "description": "Image cv detections",
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/detection"
                    }
                }
            },
            "required": [
                "uri"
            ],
            "additionalProperties": false
        },
        "detection": {
            "title": "Detection",
            "description": "Detected item",
            "type": "object",
            "properties": {
                "_id": {
                    "title": "ID",
                    "description": "Detection ID",
                    "type": "string"
                },
                "bounding_box": {
                    "title": "Bounding Box",
                    "description": "Detection bounding box specifications",
                    "type": "object",
                    "properties": {
                        "x": {
                            "title": "X-coordinate",
                            "description": "bounding box x coordinate",
                            "type": "integer"
                        },
                        "y": {
                            "title": "Y-coordinate",
                            "description": "bounding box y coordinate",
                            "type": "integer"
                        },
                        "width": {
                            "title": "Width",
                            "description": "bounding box width",
                            "type": "integer"
                        },
                        "height": {
                            "title": "Height",
                            "description": "bounding box height",
                            "type": "integer"
                        }
                    },
                    "required": [
                        "x",
                        "y",
                        "width",
                        "height"
                    ],
                    "additionalProperties": false
                },
                "category": {
                    "title": "Category",
                    "description": "Detected category",
                    "type": "string"
                },
                "score": {
                    "title": "Score",
                    "description": "Detection confidence",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                },
                "attributes": {
                    "title": "Attributes",
                    "description": "Detection attributes",
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/attribute"
                    }
                },
                "feature": {
                    "type": "object",
                    "title": "Feature Vector",
                    "description": "Detection Feature Vectors",
                    "properties": {
                        "hash": {
                            "title": "Hash",
                            "description": "MD5 Hash of Feature Vectors",
                            "type": "string",
                            "minLength": 32
                        },
                        "vector": {
                            "title": "Vector",
                            "description": "Detection Feature Vectors",
                            "type": "array",
                            "minLength": 128,
                            "maxItems": 128
                        }
                    },
                    "required": [
                        "hash",
                        "vector"
                    ]
                }
            },
            "required": [
                "bounding_box",
                "category",
                "score",
                "feature"
            ],
            "additionalProperties": false
        },
        "attribute": {
            "title": "Attribute",
            "description": "Detection Attribute Type",
            "type": "object",
            "properties": {
                "name": {
                    "title": "Name",
                    "description": "Attribute Name",
                    "type": "string",
                    "minLength": 1
                },
                "values": {
                    "title": "Values",
                    "description": "Attribute Values",
                    "type": "array",
                    "items": {
                        "title": "Value",
                        "description": "Label and Score",
                        "type": "object",
                        "properties": {
                            "value": {
                                "title": "Value",
                                "description": "Attribute Value Label",
                                "type": "string",
                                "minLength": 1
                            },
                            "score": {
                                "title": "Score",
                                "description": "Attribute Confidence Score",
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1
                            }
                        }
                    }
                }
            },
            "required": [
                "name",
                "value",
                "score"
            ],
            "additionalProperties": false
        }
    }
}

A Catalog Item (object) defines an visual item (e.g. product), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s). Catalog items can be defined as different either Product or Style. Catalog items are organized by catalogs.

Note

Attribute Type Description
_type string Object type
meta object Meta Information
_id string A unique identifier
fingerprint string Unique catalog item hash
schema string The schema used for catalog’s items:
product or style
schema_version string Schema Version Tag
catalog object Catalog reference
images array Visual representation of this item
category string Taxonomic classification of item
data object Custom - semantic representation of item
status string Indexing status of item
cv_pending, nn_pending, successful, nodetections, failed
error object Errors produced during indexing operations
failed_count object Count of failures during indexing operations
created_at string (date-time) Creation date/time
updated_at string (date-time) Updated date/time
indexing_started_at object Indexing operation start date/time
indexing_ended_at object Indexing oepration end date/time

Auto Categorize a CatalogItem

The following feature attempts to predict the Markable category based on textual information.

Example: Request

POST https://catalog.markable.ai/category HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category"
        }
    }
}
curl -X POST https://catalog.markable.ai/category \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category"
        }
    }
}
'

Example: Response

{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "hhttps://example.com/products/1/b.png"
            }
        ],
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category"
        },
        "category": {
            "name": "shoes",
            "id": "shoes"
        }
    }
}

Given an item without a category, we try and figure out what the the Supported Markable category is based on the textual information you provide. Its best to run this call with as much textual information as possible in the freeform data key. The response can be directly used to create a catalog item

HTTP Request

POST https://catalog.markable.ai/category

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

create-catalog-item_icon Create catalog item

Example: Request (with gender being optional)

POST https://catalog.markable.ai/catalogs/catalog-1/items HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "category": {
            "name": "glasses"
        },
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "name" : "A great awesome product",
            "brand" : "Brand",
            "color" : "green",
            "gender" : "women",
            "vendor" : "vendor",
            "stock" : true,
            "price" : 30,
            "currency" : "USD"
        }
    }
}
curl -X POST https://catalog.markable.ai/catalogs/catalog-1/items \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "category": {
            "name": "glasses"
        }
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "name" : "A great awesome product",
            "brand" : "Brand",
            "color" : "green",
            "gender" : "women",
            "vendor" : "vendor",
            "stock" : true,
            "price" : 30,
            "currency" : "USD"
        }
    }
}
'

Example: Response

{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png",
                "_type": "Image",
                "status": "pending",
                "error": null
            },
            {
                "uri": "https://example.com/products/1/b.png",
                "_type": "Image",
                "status": "pending",
                "error": null
            }
        ],
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "name" : "A great awesome product",
            "brand" : "Brand",
            "color" : "green",
            "gender" : "women",
            "vendor" : "vendor",
            "stock" : true,
            "price" : 30,
            "currency" : "USD"
        },
        "category": {
            "name": "glasses",
            "id": "glasses"
        },
        "_type": "CatalogItem",
        "created_at": "2019-03-12T21:22:04.345Z",
        "updated_at": "2019-03-12T21:22:04.345Z",
        "status": "cv_pending",
        "catalog": {
            "_type": "Catalog",
            "_id": "1",
            "name": "catalog1"
        },
        "schema": "product",
        "fingerprint": "uniqueID",
        "_id": "item-1"
    }
}

Example: Request (with thumbnail generation option)

POST https://catalog.markable.ai/catalogs/catalog-1/items HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "options": { "transform": true, "width": 100, "height": 100 },
        "images": [
            {
                "uri": "https://example.com/products/2/a.png"
            },
            {
                "uri": "https://example.com/products/2/b.png"
            }
        ],
        "category": {
            "name": "glasses"
        },
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "name" : "A great awesome product",
            "brand" : "Brand",
            "color" : "green",
            "gender" : "women",
            "vendor" : "vendor",
            "stock" : true,
            "price" : 30,
            "currency" : "USD"
        }
    }
}
curl -X POST https://catalog.markable.ai/catalogs/catalog-1/items \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "options": { "transform": true, "width": 100, "height": 100 },
        "images": [
            {
                "uri": "https://example.com/products/2/a.png"
            },
            {
                "uri": "https://example.com/products/2/b.png"
            }
        ],
        "category": {
            "name": "shoes"
        }
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category",
            "gender": "women"
        }
    }
}
'

Example: Response

{
    "data": {
        "images": [
            {
                "_type": "Image",
                "_id": "1",
                "uri": "https://example.com/products/2/a.png",
                "width": null,
                "height": null,
                "thumbnail": {
                    "uri": "hhttps://markable/images/2/a.jpeg",
                    "width": 66,
                    "height": 100
                },
                "status": "pending",
                "error": null
            },
            {
                "_type": "Image",
                "_id": "2",
                "uri": "https://example.com/products/2/b.png",
                "width": null,
                "height": null,
                "thumbnail": {
                    "uri": "https://markable/images/2/b.jpeg",
                    "width": 66,
                    "height": 100
                },
                "status": "pending",
                "error": null
            }
        ],
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category",
            "gender": "women"
        },
        "category": {
            "name": "shoes",
            "id": "shoes"
        },
        "_type": "CatalogItem",
        "created_at": "2019-03-12T21:58:43.099Z",
        "updated_at": "2019-03-12T21:58:43.100Z",
        "status": "cv_pending",
        "catalog": {
            "_type": "Catalog",
            "_id": "catalog_id_1",
            "name": "catalog1"
        },
        "schema": "product",
        "fingerprint": "uniqueID",
        "_id": "item-2"
    }
}

Create a new catalog item in your catalog that will eventually get indexed.

Indexing

HTTP Request

POST https://catalog.markable.ai/catalogs/:catalogId/items

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

Body

Attribute Type Description
data CatalogItem A valid catalog item object.

Options

Attribute Type Description
transform Boolean Generates a thumbnail for each image. The thumbnail will retain aspect ratio. Max width and height can be specified. This setting defaults to max 50, 50 if width and height are not specified.

delete-catalog-item_icon Delete catalog item

Example: Request

DELETE https://catalog.markable.ai/catalogs/catalog-1/items/item-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X DELETE https://catalog.markable.ai/catalogs/catalog-1/items/item-1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "images": [
            {
                "_type": "Image",
                "_id": "image1",
                "uri": "https://example.com/products/2/a.png",
                "width": null,
                "height": null,
                "thumbnail": {
                    "uri": "hhttps://markable/images/2/a.jpeg",
                    "width": 66,
                    "height": 100
                },
                "status": "pending",
                "error": null
            },
            {
                "_type": "Image",
                "_id": "image2",
                "uri": "https://example.com/products/2/b.png",
                "width": null,
                "height": null,
                "thumbnail": {
                    "uri": "https://markable/images/2/b.jpeg",
                    "width": 66,
                    "height": 100
                },
                "status": "pending",
                "error": null
            }
        ],
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category",
            "gender": "women"
        },
        "category": {
            "name": "shoes",
            "id": "shoes"
        },
        "_type": "CatalogItem",
        "created_at": "2019-03-12T21:58:43.099Z",
        "updated_at": "2019-03-12T21:58:43.100Z",
        "status": "cv_pending",
        "catalog": {
            "_type": "Catalog",
            "_id": "catalog_id_1",
            "name": "catalog1"
        },
        "schema": "product",
        "fingerprint": "uniqueID",
        "_id": "item-2"
    }
}

Delete an existing catalog item.

HTTP Request

DELETE https://catalog.markable.ai/catalogs/:catalogId/items/:itemId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required
itemId The ID of the catalog item. required

get-catalog-item_icon Get catalog item

Example: Request

GET https://catalog.markable.ai/catalogs/catalog-1/items/item-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1/items/item-1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_id": "item_id_3",
        "schema_version": "v1.0.0",
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category",
            "gender": "women"
        },
        "fingerprint": "uniqueID",
        "failed_count": {
            "cv": 0
        },
        "updated_at": "2019-03-13T00:20:44.589Z",
        "schema": "product",
        "images": [
            {
                "uri": "https://example.com/products/3/a.png",
                "status": "ok",
                "width": 853,
                "height": 853,
                "error": null,
                "thumbnail": {
                    "uri": "https://markable/images/s3-url-3.jpeg",
                    "width": 100,
                    "height": 100
                }
            }
        ],
        "status": "nn_pending",
        "error": null,
        "catalog": {
            "_id": "catalog_id_1"
        },
        "indexing_ended_at": {
            "cv": "2019-03-08T22:45:05.195159+00:00"
        },
        "created_at": "2018-09-04T20:40:26.225Z",
        "indexing_started_at": {
            "cv": "2019-03-08T21:15:47.358115+00:00"
        }
    }
}

Get an existing catalog item.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId/items/:itemId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required
itemId The ID of the catalog item. required

Query parameters

Parameter Type Description
attributes Boolean Return attributes for every catalogItem

list-catalog-item_icon List catalog items

Example: Request

GET https://catalog.markable.ai/catalogs/catalog-1/items HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1/items \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Request with filters

GET https://catalog.markable.ai/catalogs/catalog-1/items?success=true&limit=50&skip=0&category=dresses HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1/items?success=true&limit=50&skip=0&category=dresses \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": [
        {
            "_id": "item-1",
            "images": [
                {
                    "uri": "https://agreatproductimage/a.jpg",
                    "_type": "Image",
                    "_id": "uniqueID",
                    "thumbnail": {
                        "uri": "https://markable/thumbnail/product/a.jpeg",
                        "width": 75,
                        "height": 100
                    },
                    "status": "ok",
                    "error": null,
                    "width": 1000,
                    "height": 1334,
                },
                {
                    "uri": "https://agreatproductimage/b.jpg",
                    "_type": "Image",
                    "_id": "uniqueID",
                    "thumbnail": {
                        "uri": "https://markable/thumbnail/product/b.jpeg",
                        "width": 75,
                        "height": 100
                    },
                    "status": "ok",
                    "error": null,
                    "width": 1000,
                    "height": 1334,
                },
                {
                    "uri": "https://agreatproductimage/c.jpg",
                    "_type": "Image",
                    "_id": "uniqueID",
                    "thumbnail": {
                        "uri": "https://markable/thumbnail/product/c.jpeg",
                        "width": 75,
                        "height": 100
                    },
                    "status": "ok",
                    "error": null,
                    "width": 1000,
                    "height": 1334,
                }
            ],
            "data": {
                "id": "external-id",
                "sku": "external-sku",
                "name": "product name",
                "url": "https://example.com/product.html",
                "color": "blue",
                "gender": "women",
                "description": "Product description",
                "category": "Shoulder Bags",
                "stock": true,
                "price": 80,
                "currency": "US"
            },
            "category": {
                "name": "handbags",
                "id": "handbags"
            },
            "_type": "CatalogItem",
            "created_at": "2019-03-07T11:00:17.101Z",
            "updated_at": "2019-03-13T18:05:07.337Z",
            "status": "nn_pending",
            "catalog": {
                "_id": "catalog_id_1"
            },
            "schema": "product",
            "fingerprint": "uniqueID",
            "indexing_started_at": {
                "cv": "2019-03-09T21:07:29.548721+00:00"
            },
            "indexing_ended_at": {
                "cv": "2019-03-09T21:07:38.005306+00:00"
            },
            "error": null,
            "failed_count": {
                "cv": 0
            }
        },
        {
            "_id": "item-2",
            "images": [
                {
                    "uri": "https://anothergreatproductimage/a.jpg",
                    "_type": "Image",
                    "_id": "uniqueID",
                    "thumbnail": {
                        "uri": "https://markable/thumbnail/anotherproduct/a.jpeg",
                        "width": 75,
                        "height": 100
                    },
                    "status": "ok",
                    "error": null,
                    "width": 1000,
                    "height": 1334,
                },
                {
                    "uri": "https://anothergreatproductimage/b.jpg",
                    "_type": "Image",
                    "_id": "uniqueID",
                    "thumbnail": {
                        "uri": "https://markable/thumbnail/anotherproduct/b.jpeg",
                        "width": 75,
                        "height": 100
                    },
                    "status": "ok",
                    "error": null,
                    "width": 1000,
                    "height": 1334,
                },
                {
                    "uri": "https://anothergreatproductimage/c.jpg",
                    "_type": "Image",
                    "_id": "uniqueID",
                    "thumbnail": {
                        "uri": "https://markable/thumbnail/anotherproduct/c.jpeg",
                        "width": 75,
                        "height": 100
                    },
                    "status": "ok",
                    "error": null,
                    "width": 1000,
                    "height": 1334,
                }
            ],
            "data": {
                "id": "external-id",
                "sku": "external-sku",
                "name": "product name",
                "url": "https://example.com/anotherproduct.html",
                "color": "blue",
                "gender": "women",
                "description": "Product description",
                "category": "Shoes",
                "stock": true,
                "price": 80,
                "currency": "US"
            },
            "category": {
                "name": "shoes",
                "id": "shoes"
            },
            "_type": "CatalogItem",
            "created_at": "2019-03-07T11:00:18.421Z",
            "updated_at": "2019-03-13T18:05:07.382Z",
            "status": "nn_pending",
            "catalog": {
                "_id": "catalog_id_1"
            },
            "schema": "product",
            "fingerprint": "uniqueID",
            "indexing_started_at": {
                "cv": "2019-03-09T21:07:29.550073+00:00"
            },
            "indexing_ended_at": {
                "cv": "2019-03-09T21:07:39.090980+00:00"
            },
            "error": null,
            "failed_count": {
                "cv": 0
            }
        }
    ]
}

Get all existing catalog items.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId/items

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

Parameter Description
limit The limit of items to return (defaults to 20).
skip The skip of items to return.
success Set this value filter by success status
error Set this value filter by error status
pending Set this value filter by pending status
category The category of the items to filter by
attributes Boolean. Returns attributes for every catalogItem

Indexing

Indexing is how we make CatalogItems available for search and our way of representing images.

We have constraints on the image sizes we index.

  1. We support .jpg, .jpeg, .png

  2. Minimum image size = 100 px

  3. Maximum image size = 5000 px

  4. Maximum image memory size = 10485760 b

Taxonomy

Markable’s taxonomy includes our supported categories and attributes.

Supported Categories

Example: Request

GET https://catalog.markable.ai/category HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/category \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

This is our current exhaustive list of supported categories.

{
    "data": {
        "bags": [
            "handbags",
            "clutches",
            "backpacks",
            "messengerbags"
        ],
        "footwear": [
            "boots",
            "shoes",
            "sandals",
            "slippers"
        ],
        "fullbody": [
            "rompers",
            "overalls",
            "dresses",
            "jumpsuits"
        ],
        "glasses": [
            "glasses"
        ],
        "headwear": [
            "beanieknitcaps",
            "baseballcaps",
            "berets",
            "sunhats_cowboyhats"
        ],
        "humans": [
            "humans"
        ],
        "jewelry_watches": [
            "watches"
        ],
        "lowerbody": [
            "shorts",
            "jeans",
            "skirts",
            "leggings",
            "pants"
        ],
        "upperbody": [
            "vests",
            "buttondowns",
            "blouses",
            "tees",
            "suitcoats_blazers",
            "tanks_camis",
            "sweaters",
            "tunics",
            "longsleeveshirts",
            "coats_jackets",
            "hoodies",
            "henleys",
            "cardigans",
            "polos"
        ],
        "upperbody_accessories": [
            "scarves_wraps",
            "ties"
        ]
    }
}

Markable’s supported categories.

HTTP Request

GET https://catalog.markable.ai/category

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Supported Attributes

CatalogItems after indexing get assigend attributes, based on their category. Attributes can be of type color, pattern, sleeve length and more.

Example: Request

GET https://catalog.markable.ai/attributes HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/attributes \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

This is a snippet of our attributes.

{
    "data": {
        "backpacks": [
            "color",
            "pattern"
        ],
        "baseballcaps": [
            "color",
            "pattern"
        ],
        "beanieknitcaps": [
            "color",
            "pattern"
        ],
        "berets": [
            "color",
            "pattern"
        ],
        "blouses": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "boots": [
            "color",
            "heel_height",
            "heel_type",
            "pattern",
            "shaft_height",
            "toe_style"
        ],
        "buttondowns": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "cardigans": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "clutches": [
            "color",
            "pattern"
        ],
        "coats_jackets": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "dresses": [
            "closing_style",
            "collar_type",
            "color",
            "dress_types",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "glasses": [
            "color",
            "pattern"
        ],
        "handbags": [
            "color",
            "pattern"
        ],
        "henleys": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "hoodies": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "humans": [
            "gender"
        ],
        "jeans": [
            "color",
            "jeans_fit",
            "jeans_type",
            "lower_hemline",
            "pattern"
        ],
        "jumpsuits": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "leggings": [
            "color",
            "lower_hemline",
            "pattern"
        ],
        "longsleeveshirts": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "messengerbags": [
            "color",
            "pattern"
        ],
        "overalls": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "pants": [
            "color",
            "lower_hemline",
            "pattern"
        ],
        "polos": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "rompers": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "sandals": [
            "color",
            "heel_height",
            "heel_type",
            "pattern",
            "shaft_height",
            "toe_style"
        ],
        "scarves_wraps": [
            "color",
            "pattern"
        ],
        "shoes": [
            "color",
            "heel_height",
            "heel_type",
            "pattern",
            "shaft_height",
            "toe_style"
        ],
        "shorts": [
            "color",
            "lower_hemline",
            "pattern"
        ],
        "skirts": [
            "color",
            "lower_hemline",
            "pattern",
            "skirt_type"
        ],
        "slippers": [
            "color",
            "heel_height",
            "heel_type",
            "pattern",
            "shaft_height",
            "toe_style"
        ],
        "suitcoats_blazers": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "sunhats_cowboyhats": [
            "color",
            "pattern"
        ],
        "sweaters": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "tanks_camis": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "tees": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "ties": [
            "color",
            "pattern"
        ],
        "tunics": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "vests": [
            "closing_style",
            "collar_type",
            "color",
            "pattern",
            "sleeve_length",
            "upper_hemline"
        ],
        "watches": [
            "color",
            "pattern"
        ]
    }
}

Markable’s supported attributes per category.

HTTP Request

GET https://catalog.markable.ai/attributes

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Image Search

We have two different kinds of search, Product and How to Wear it for images.

Our Product Search returns the most visually relevant images in your product schema catalog.

image-search_icon The Product Search Query Object

Example: Product Search Query Object (defaults to auto detect gender)

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}

Example: Product Search Query Object With Gender Specific Results

{
    "data": {
        "gender": ["women"],
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}

Example: Product Search Query Object with Options

{
    "data": {
        "gender": ["men"],
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ],
        "options": {
            "limit": 30,
            "relevance": 50
        }
    }
}

Example: Product Search Query Object with Attributes

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ],
        "options": {
            "relevance": 90
            "attributes": true
        }
    }
}

A Product Search Query (object) defines a visual search query for an image.

Attribute Type Description
image_uri String A valid image URI. required
gender Array Either ['men'], ['women'], ['unisex'] or any combination can be provided in the request to limit all results to specified gender. If no gender field is provided, we will automatically detect gender and return detected gender based results. If gender is not detected, results will return closest matching items irrespective of gender.
catalogs Array<Catalog> List of product catalogs (public or private) included in the visual search scope. Accounts can be updated with Default catalogs to perform search without explicitly specifying the catalog name or ID.
options Object A list of options that we support. Currently we support the options below

These options give you the flexibility to control how our visual search is performed.

Attribute Type Description
limit Number Number of results to return. Default 30
relevance Number How relevant you want the results to be. Default 50. This takes precedence over limit
auto_detect_gender Boolean Automatically detect gender and return detected gender based results. Note that this option defaults to true if gender is not specified in the request, and false if gender is provided.
attributes Boolean Return attributes for every catalogItem, for both the searched input image and the images in the results. Note that this option will introduce a few 100ms in search. There is no guarantee that the attributes will be common between the input image and the result images; however, its highly likely that they will be.
human_detection Boolean Return bounding boxes for human detections. Default is false.

Example: Image Search with Catalogs Names (Preferred over IDS)

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
'

Example: Image Search with Catalogs IDS

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
'

Example: Simple Image Search with Catalogs and Gender

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
  "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men"],
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men"],
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
'

Example: Multipart Image Search with Catalogs (Alpha availability)

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
Content-Type: multipart/form-data; charset=utf-8;
... (See shell for a full example)
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: multipart/form-data;' \
-H 'Authorization: Bearer 123abc' \
-F 'image=@/local/folder/1.png' \
-F 'data={ "gender": ["women"] , "catalogs": [{  "name": "catalog-name-1" }] }'

Example: Response

{
    "meta": {
        "image": {
            "uri": "http://www.somefashion.com/image.jpg",
            "width": 1365,
            "height": 2048
        },
        "stats": {
            "cv_detection": 2065,
            "nn_search": 199,
            "db_queries": 292
        },
        "catalogs": {
            "requested": [
                "catalog_id_1"
            ],
            "searched": [
                "catalog_id_1"
            ]
        },
        "gender": [
            "men",
            "women"
        ],
        "options": {
            "limit": 30,
            "relevance": 50,
            "attributes": false,
            "auto_detect_gender": false, 
            "human_detection": false
        }
    },
    "data": [
        {
            "_type": "SearchResult",
            "_id": "uniqueID",
            "score": 0.9995391368865967,
            "category": {
                "_type": "Category",
                "_id": "humans",
                "name": "humans"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "x": 367.3973388671875,
                "y": 66.24256896972656,
                "width": 609.6744995117188,
                "height": 1876.552230834961
            },
            "gender": [
                "women"
            ],
            "matches": []
        },
        {
            "_type": "SearchResult",
            "_id": "uniqueID",
            "score": 0.9929601550102234,
            "category": {
                "_type": "Category",
                "_id": "handbags",
                "name": "handbags"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "x": 367.1494140625,
                "y": 1231.869140625,
                "width": 182.40740966796875,
                "height": 332.765380859375
            },
            "gender": [
                "women"
            ],
            "matches": [
                {
                    "_type": "product",
                    "_id": "uniqueID",
                    "score": "0.902",
                    "images": [
                        {
                            "uri": "https://handbag/image.jpg",
                            "_type": "Image",
                            "_id": "uniqueID",
                            "thumbnail": {
                                "uri": "https://thumbnail.jpeg",
                                "width": 75,
                                "height": 100
                            },
                            "status": "ok",
                            "error": null,
                            "width": 1000,
                            "height": 1334,
                        }
                    ],
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                        "url": "link_to_product_page",
                    },
                    "catalog": {
                        "_type": "Catalog",
                        "_id": "catalog_id_1",
                        "name": null
                    },
                    "created_at": "2019-03-14T13:50:04.134Z",
                    "updated_at": "2019-03-14T13:50:04.134Z"
                },
                {
                    "_type": "product",
                    "_id": "uniqueID",
                    "score": "0.899",
                    "images": [
                        {
                            "uri": "https://handbag/image2.jpg",
                            "_type": "Image",
                            "_id": "uniqueID",
                            "thumbnail": {
                                "uri": "https://thumbnail2.jpeg",
                                "width": 75,
                                "height": 100
                            },
                            "status": "ok",
                            "error": null,
                            "width": 1000,
                            "height": 1334,
                        }
                    ],
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name",
                        "url": "link_to_product_page",
                    },
                    "catalog": {
                        "_type": "Catalog",
                        "_id": "catalog_id_1",
                        "name": null
                    },
                    "created_at": "2019-03-14T13:50:04.134Z",
                    "updated_at": "2019-03-14T13:50:04.134Z"
                },
            ]
        },
        {
            "_type": "SearchResult",
            "_id": "uniqueID",
            "score": 0.9856816530227661,
            "category": {
                "_type": "Category",
                "_id": "coats_jackets",
                "name": "coats_jackets"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "x": 408.2473449707031,
                "y": 325.932373046875,
                "width": 560.6332702636719,
                "height": 736.38623046875
            },
            "gender": [
                "women"
            ],
            "matches": [
                {
                    "_type": "product",
                    "_id": "uniqueID",
                    "score": "0.924",
                    "images": [
                        {
                            "uri": "https://jacket/image.jpg",
                            "_type": "Image",
                            "_id": "uniqueID",
                            "thumbnail": {
                                "uri": "https://thumbnail.jpeg",
                                "width": 75,
                                "height": 100
                            },
                            "status": "ok",
                            "error": null,
                            "width": 1000,
                            "height": 1334,
                        },
                    ],
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "catalog": {
                        "_type": "Catalog",
                        "_id": "catalog_id_1",
                        "name": null
                    },
                    "created_at": "2019-03-14T13:50:04.138Z",
                    "updated_at": "2019-03-14T13:50:04.138Z"
                },
                {
                    "_type": "product",
                    "_id": "uniqueID",
                    "score": "0.924",
                    "images": [
                        {
                            "uri": "https://jacket/image2.jpg",
                            "_type": "Image",
                            "_id": "uniqueID",
                            "thumbnail": {
                                "uri": "https://thumbnail2.jpeg",
                                "width": 75,
                                "height": 100
                            },
                            "status": "ok",
                            "error": null,
                            "width": 1000,
                            "height": 1334,
                        },
                    ],
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name",
                        "url": "link_to_product_page",
                    },
                    "catalog": {
                        "_type": "Catalog",
                        "_id": "catalog_id_1",
                        "name": null
                    },
                    "created_at": "2019-03-14T13:50:04.138Z",
                    "updated_at": "2019-03-14T13:50:04.138Z"
                },
            ]
        },
    ]
}

Search an image - detect and retreive products based on visual features/similarity.

HTTP Request

POST https://catalog.markable.ai/image/search

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

None

Body

Attribute Type Description
data ImageSearchQuery A valid image search object.

Our How to Wear it search gives style results given a specific image. Its best if the searched image is a product image.

As an example, if you search with a shoe (a product image), results from your style catalog will be shown.

image-search_icon The How to Wear it Query Object

Example: How to Wear it Query Object

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "style-catalog-name-1"
            },
            {
                "name": "style-catalog-name-2"
            }
        ]
    }
}

A How to Wear it Query (object) defines a visual search query for an image.

Attribute Type Description
image_uri String A valid image URI. required
gender Array Either ['men'], ['women'], ['unisex'] or any combination can be provided in the request to limit all results to specified gender. If no gender field is provided, we will automatically detect gender and return detected gender based results. If gender is not detected, results will return closest matching items irrespective of gender.
catalogs Array<Catalog> List of style catalogs (public or private) included in the visual search scope. Accounts can be updated with Default catalogs to perform search without explicitly specifying the catalog name or ID.
options Object A list of options that we support. Currently we support the options below

These options give you the flexibility to control how our visual search is performed.

Attribute Type Description
limit Number Number of results to return. Default 30
relevance Number How relevant you want the results to be. Default 50. This takes precedence over limit
auto_detect_gender Boolean Automatically detect gender and return detected gender based results. Note that this option defaults to true if gender is not specified in the request, and false if gender is provided.
attributes Boolean Return attributes for every catalogItem, for both the searched input image and the images in the results. Note that this option will introduce a few 100ms in search. There is no guarantee that the attributes will be common between the input image and the result images; however, its highly likely that they will be.
human_detection Boolean Return bounding boxes for human detections. Default is false.

Example: How to Wear it with style Catalog Names

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "style-catalog-name-1"
            },
            {
                "name": "style-catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "style-catalog-name-1"
            },
            {
                "name": "style-catalog-name-2"
            }
        ]
    }
}
'

Example: How to Wear it with style Catalogs IDS

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
'

Example: Simple How to Wear it with style Catalogs and Gender

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
  "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men"],
        "catalogs": [
            {
                "name": "style-catalog-name-1"
            },
            {
                "name": "style-catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men", "women"],
        "catalogs": [
            {
                "name": "style-catalog-name-1"
            },
            {
                "name": "style-catalog-name-2"
            }
        ]
    }
}
'

Example: Multipart How to Wear it with style Catalogs (Alpha availability)

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
Content-Type: multipart/form-data; charset=utf-8;
... (See shell for a full example)
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: multipart/form-data;' \
-H 'Authorization: Bearer 123abc' \
-F 'image=@/local/folder/1.png' \
-F 'data={ "catalogs": [{ "name": "style-catalog-name-1" }] }'

Example: Response

{
    "meta": {
        "image": {
            "uri": "http://www.somefashion.com/image.jpg",
            "width": 1848,
            "height": 885
        },
        "stats": {
            "cv_detection": 3919,
            "nn_search": 240,
            "db_queries": 195
        },
        "catalogs": {
            "requested": [
                "style_catalog_id_1"
            ],
            "searched": [
                "style_catalog_id_1"
            ]
        },
        "gender": [
            "men",
            "women"
        ],
        "options": {
            "limit": 30,
            "relevance": 50,
            "attributes": false,
            "auto_detect_gender": false,
            "human_detection": false
        }
    },
    "data": [
        {
            "_type": "SearchResult",
            "_id": "uniqueID",
            "score": 0.8623029589653015,
            "category": {
                "_type": "Category",
                "_id": "shoes",
                "name": "shoes"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "x": 0,
                "y": 0,
                "width": 1846.52392578125,
                "height": 851.519287109375
            },
            "gender": [
                "women",
                "men",
                "unisex"
            ],
            "matches": [
                {
                    "_type": "style",
                    "_id": "uniqueID",
                    "score": "0.911",
                    "images": [
                        {
                            "height": 960,
                            "error": null,
                            "status": "ok",
                            "uri": "https://somestylephoto/image.jpg",
                            "width": 626,
                            "thumbnail": {
                                "uri": "https://thumbnail.jpeg",
                                "width": 65,
                                "height": 100
                            }
                        }
                    ],
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name",
                        "url": "link_to_style_image_page",
                    },
                    "catalog": {
                        "_type": "Catalog",
                        "_id": "style_catalog_id_1",
                        "name": null
                    },
                    "created_at": "2019-03-14T15:57:57.669Z",
                    "updated_at": "2019-03-14T15:57:57.669Z"
                },
                {
                    "_type": "style",
                    "_id": "uniqueID",
                    "score": "0.908",
                    "images": [
                        {
                            "error": null,
                            "height": 744,
                            "width": 935,
                            "status": "ok",
                            "uri": "https://somestylephoto2/image.jpg",
                            "thumbnail": {
                                "uri": "https://thumbnail.jpeg",
                                "width": 100,
                                "height": 80
                            }
                        }
                    ],
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name",
                        "url": "link_to_style_image_page",
                    },
                    "catalog": {
                        "_type": "Catalog",
                        "_id": "style_catalog_id_1",
                        "name": null
                    },
                    "created_at": "2019-03-14T15:57:57.669Z",
                    "updated_at": "2019-03-14T15:57:57.669Z"
                },
            ]
        }
    ]
}

Given a product image, find how it fits with different fashion styles. In specific, HTWI search returns results from a catalog of schema style.

HTTP Request

POST https://catalog.markable.ai/image/search/style

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

None

Body

Attribute Type Description
data ImageSearchQuery A valid Image Search object.

Search Constraints

We have constraints on the input image we search on.

  1. We support .jpg, .jpeg, .png

  2. Minimum image size = 100 px

  3. Maximum image size = 5000 px

  4. Maximum image memory size = 10485760 b