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 currently in private beta - subject for 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.

This API and documentation is currently in private beta - subject for modifications.

Versioning

The platform behind Markable Lens API is continuesly being improved for stability, accuracy, and new features. We may introduce changes with bugs, so to minimize the impact for our integrated users/partners the API will be versioned.

Currently the API is in private beta and the versioning process is not being implemented, but as soon as we move into public beta the versioning will be in place.

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, 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 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.
406 Not Acceptable - The request format that isn’t valid JSON.
429 Too Many Requests - You have reached the default request limit. (This can be adjusted depending on needs.)
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 Object

{
    "_type": "Error",
    "id": "abc",
    "code": 400,
    "detail": "Something went wrong."
}

Example: Error Response

{
    "errors": [
        {
            "_type": "Error",
            "id": "abc",
            "code": 400,
            "detail": "Something went wrong."
        }
    ]
}

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

An error object MAY have the following members:

Attribute Description
id A unique identifier for this particular occurrence of the problem.
links A links object containing the following members.
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.
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.
detail A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source An object containing references to the source of the error.
meta A meta object containing non-standard meta-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": "1",
    "size": 5,
    "name": "catalog-1",
    "description": "My first catalog",
    "schema": "product",
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Catalog",
    "required": [
        "name",
        "schema"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Catalog"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "size": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true
        },
        "user": {
            "type": "object",
            "description": "User",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "User"
                },
                "_id": {
                    "type": "string",
                    "readOnly": true
                }
            }
        },
        "name": {
            "type": "string"
        },
        "description": {
            "type": "string"
        },
        "schema": {
            "type": "string",
            "enum": [
                "product"
            ],
            "default": "product"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}

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 your customly defined catalogs.

Attribute Type Description
_type String Type. read-only
_id String A unique identifier. read-only
size Integer Number or items in this catalog. read-only
name String A custom unique name.
description String A custom description.
schema String The schema to be used for this catalog’s items.
Can be: product.
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

catalog-item_icon Catalog Item

Example: Catalog Item Object

{
    "_type": "CatalogItem",
    "_id": "item-1",
    "schema": "product",
    "catalog": {
        "_type": "Catalog",
        "_id": "1",
        "name": "catalog-1"
    },
    "images": [
        {
            "_type": "Image",
            "_id": "1",
            "uri": "https://markable.ai/data/products/dress/1.png",
            "width": 100,
            "height": 100
        },
        {
            "_type": "Image",
            "_id": "2",
            "uri": "https://markable.ai/data/products/dress/2.png",
            "width": 100,
            "height": 100
        }
    ],
    "category": {
      "_type": "Category",
      "_id": "1",
      "name": "dress"
    }
    "data": {
        "id": "external-id-1",
        "url": "external-url-1",
        "foo": "bar"
    },
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Item Object (Product)

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "CatalogItem",
    "required": [
        "catalog",
        "images",
        "data"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "CatalogItem"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "schema": {
            "type": "string",
            "readOnly": true,
            "default": "product"
        },
        "catalog": {
            "type": "object",
            "description": "Catalog",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Catalog"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "images": {
            "type": "array",
            "items": {
                "type": "object",
                "description": "Image",
                "required": [
                    "uri"
                ],
                "properties": {
                    "_type": {
                        "type": "string",
                        "readOnly": true,
                        "default": "Image"
                    },
                    "_id": {
                        "type": "string",
                        "readOnly": true
                    },
                    "uri": {
                        "anyOf": [
                            {
                                "type": "string",
                                "format": "uri"
                            },
                            {
                                "type": "string",
                                "format": "byte"
                            }
                        ]
                    },
                    "width": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    },
                    "height": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    }
                },
                "additionalProperties": false
            },
            "minItems": 1,
            "uniqueItems": true
        },
        "category": {
            "type": "object",
            "description": "Category",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Category"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "data": {
            "type": "object",
            "additionalProperties": true
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "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). Catalog items can be defined as different types of objects, but currently only Product.

Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
catalog Catalog Reference to catalog containing this item.
images Array<Image> List of images - visual representation of this item (object).
category Category Category - taxonomic classification of item (object).
data Object Custom data - semantic representation of this item (object).
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

image_icon Image

An Image defines an image per definition.

Example: Image Object

{
    "_type": "Image",
    "_id": "image-1",
    "uri": "https://example.com/images/1.png",
    "width": 100,
    "height": 100
}

Schema: Image Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Image",
    "required": [
        "uri"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Image"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "uri": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uri"
                },
                {
                    "type": "string",
                    "format": "byte"
                }
            ]
        },
        "width": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true
        },
        "height": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true
        }
    },
    "additionalProperties": false
}
Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
uri String A valid image URI.
content_type String Image content type. read-only
width Integer Image width in pixels. read-only
height Integer Image height in pixels. read-only

category_icon Category

An Image defines a category per definition.

Example: Category Object

{
    "_type": "Category",
    "_id": "1",
    "name": "dress"
}

Schema: Category Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Category",
    "required": [
        "name"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Category"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "name": {
            "type": "string"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}
Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
name String A custom unique name.

bounding-box_icon Bounding Box

An Bounding Box defines an rectangular area (within an image) which contains a visually detected object.

Example: Bounding Box Object

{
    "_type": "BoundingBox",
    "_id": "1",
    "_score": 0.70,
    "_category": {
        "_type": "Category",
        "_id": "1",
        "name": "dress"
    },
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10
}

Schema: Bounding Box Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "BoundingBox",
    "required": [
        "x",
        "y",
        "width",
        "height"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "BoundingBox"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "multipleOf": 0.01,
            "readOnly": true
        },
        "x": {
            "type": "integer",
            "minimum": 0,
            "default": 0
        },
        "y": {
            "type": "integer",
            "minimum": 0,
            "default": 0
        },
        "width": {
            "type": "integer",
            "minimum": 10
        },
        "height": {
            "type": "integer",
            "minimum": 10
        }
    },
    "additionalProperties": false
}
Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
_score Float Confidence score of the classification.
_category Category Category - taxonomic classification of bounding box content (object).
x Integer Bounding box offset x coordinate in pixels. read-only
y Integer Bounding box offset y coordinate in pixels. read-only
width Integer Bounding box offset width in pixels. read-only
height Integer Bounding box offset height in pixels. read-only

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://api.markable.ai/auth/user/authorize HTTP/1.1
{
    "data": {
        "email": "developer@client.com",
        "password": "password"
    }
}
curl -X POST https://api.markable.ai/auth/user/authorize \
-d '
{
    "data": {
        "email": "developer@client.com",
        "password": "password"
    }
}
'

Example: Response with User Access Token

{
    "data": {
        "access_token": "usertoken123abc"
    }
}

Create authorization (authentication token) for a user.

HTTP Request

POST https://api.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.

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

Example: Response

{
    "data": {
        "type": "User",
        "name": "Developer at Client",
        "email": "developer@client.com",
        "user_id": "user_id_1",
        "clients": [
            {
                "type": "Client",
                "client_id": "client_id_1"
                "client_secret": "client_secret_1",
                "user_id": "user_id_1",
                "scope": "default"
            }
        ]
    }
}

HTTP Request

GET https://api.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"
}

The Client Credentials (object) refers to a object holding holding 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

Example: Request

POST https://api.markable.ai/auth/client/authorize HTTP/1.1
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1"
  }
}
curl -X POST https://api.markable.ai/auth/client/authorize \
-d '
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1"
  }
}
'

Example: Response Client Access Token

{
    "data": {
      "access_token": "clienttoken123"
    }
}

Create authorization (authentication token) for a client.

HTTP Request

POST https://api.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

Example: Catalog Object

{
    "_type": "Catalog",
    "_id": "1",
    "size": 5,
    "name": "catalog-1",
    "description": "My first catalog",
    "schema": "product",
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Catalog",
    "required": [
        "name",
        "schema"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Catalog"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "size": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true,
            "description": "The number of items in this catalog"
        },
        "user": {
            "type": "object",
            "description": "User",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "User"
                },
                "_id": {
                    "type": "string",
                    "readOnly": true
                }
            }
        },
        "name": {
            "type": "string"
        },
        "description": {
            "type": "string"
        },
        "schema": {
            "type": "string",
            "enum": [
                "product"
            ],
            "default": "product"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}

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/vides the items (exact or similar) must be known to Markable‘s visual search engine, either using existing catalogs or your customly defined catalogs.

Attribute Type Description
_type String Type. read-only
_id String A unique identifier. read-only
size Integer Number or items in this catalog. read-only
name String A custom unique name.
description String A custom description.
schema String The schema to be used for this catalog’s items.
Can be: product.
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

create-catalog_icon Create catalog

Example: Request

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

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "1",
        "size": 0,
        "user": {
            "_type": "User",
            "_id": "1"
        },
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Create a new catalog.

HTTP Request

POST https://api.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

Query Parameters

None

Body

Attribute Type Description
data Catalog A valid catalog object.

update-catalog_icon Update catalog

Example: Request

PUT https://api.markable.ai/catalogs/catalog-1 HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog"
    }
}
curl -X PUT https://api.markable.ai/catalogs/catalog-1 \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog"
    }
}
'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "1",
        "user": {
            "_type": "User",
            "_id": "1"
        },
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Update an existing catalog.

HTTP Request

PUT https://api.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

Query Parameters

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://api.markable.ai/catalogs/catalog-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X DELETE https://api.markable.ai/catalogs/catalog-1 \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {}
}

Delete an existing catalog.

HTTP Request

DELETE https://api.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

Query Parameters

Parameter Description
catalogId The ID of the catalog. required

get-catalog-objects_icon Get catalog

Example: Request

GET https://api.markable.ai/catalogs/catalog-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://api.markable.ai/catalogs/catalog-1 \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "1",
        "size": 0,
        "user": {
            "_type": "User",
            "_id": "1"
        },
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Get an existing catalog.

HTTP Request

GET https://api.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

Query Parameters

Parameter Description
catalogId The ID of the catalog. required

list-catalog-objects_icon List catalogs

Example: Request

GET https://api.markable.ai/catalogs HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://api.markable.ai/catalogs \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": [
        {
            "_type": "Catalog",
            "_id": "1",
            "size": 0,
            "user": {
                "_type": "User",
                "_id": "1"
            },
            "name": "catalog-1",
            "description": "My first catalog",
            "schema": "product",
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        },
        {
            "_type": "Catalog",
            "_id": "2",
            "size": 0,
            "user": {
                "_type": "User",
                "_id": "1"
            },
            "name": "catalog-2",
            "description": "My second catalog",
            "schema": "product",
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        }
    ]
}

Get all existing catalogs.

HTTP Request

GET https://api.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

Query Parameters

None

Catalog Items Catalog-items

catalog-items-objects_icon The Catalog Item Object

Example: Catalog Item Object

{
    "_type": "CatalogItem",
    "_id": "item-1",
    "schema": "product",
    "catalog": {
        "_type": "Catalog",
        "_id": "1",
        "name": "catalog-1"
    },
    "images": [
        {
            "_type": "CatalogItem",
            "_id": "1",
            "schema": "product",
            "uri": "https://markable.ai/data/products/dress/1.png",
            "width": 100,
            "height": 100
        },
        {
            "_type": "Image",
            "_id": "2",
            "uri": "https://markable.ai/data/products/dress/2.png",
            "width": 100,
            "height": 100
        }
    ],
    "category": {
        "_type": "Category",
        "_id": "1",
        "name": "dress"
    },
    "data": {
        "id": "external-id-1",
        "url": "external-url-1",
        "foo": "bar"
    },
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Item Object (Product)

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "CatalogItem",
    "required": [
        "catalog",
        "images",
        "data"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "CatalogItem"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "schema": {
            "type": "string",
            "readOnly": true,
            "default": "product"
        },
        "catalog": {
            "type": "object",
            "description": "Catalog",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Catalog"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "images": {
            "type": "array",
            "items": {
                "type": "object",
                "description": "Image",
                "required": [
                    "uri"
                ],
                "properties": {
                    "_type": {
                        "type": "string",
                        "readOnly": true,
                        "default": "Image"
                    },
                    "_id": {
                        "type": "string",
                        "readOnly": true
                    },
                    "uri": {
                        "anyOf": [
                            {
                                "type": "string",
                                "format": "uri"
                            },
                            {
                                "type": "string",
                                "format": "byte"
                            }
                        ]
                    },
                    "width": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    },
                    "height": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    }
                },
                "additionalProperties": false
            },
            "minItems": 1,
            "uniqueItems": true
        },
        "category": {
            "type": "object",
            "description": "Category",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Category"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "data": {
            "type": "object",
            "additionalProperties": true
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "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 types of objects, but currently only Product. Catalog items are organized by catalogs.

Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
catalog Catalog Reference to catalog containing this item.
images Array<Image> List of images - visual representation of this item (object).
category Category Category - taxonomic classification of item (object).
data Object Custom data - semantic representation of this item (object).
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

create-catalog-item_icon Create catalog item

Example: Request

POST https://api.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": "sunglasses"
        },
        "data": {
            "id": "external-id-1",
            "foo": "bar"
        }
    }
}
curl -X POST https://api.markable.ai/catalogs/catalog-1/items \
-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": "sunglasses"
        }
        "data": {
            "id": "external-id-1",
            "foo": "bar"
        }
    }
}
'

Example: Response

{
    "data": {
        "_type": "CatalogItem",
        "_id": "item-1",
        "schema": "product",
        "catalog": {
            "_type": "Catalog",
            "_id": "1",
            "name": "catalog-1"
        },
        "images": [
            {
                "_type": "Image",
                "_id": "1",
                "uri": "https://example.com/products/1/a.png",
                "width": 200,
                "height": 300
            },
            {
                "_type": "Image",
                "_id": "2",
                "uri": "https://example.com/products/1/b.png",
                "width": 200,
                "height": 300
            }
        ],
        "category": {
          "_type": "Category",
          "_id": "1",
          "name": "sunglasses"
      },
        "data": {
            "id": "external-id-1",
            "foo": "bar"
        },
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Create a new catalog item.

HTTP Request

POST https://api.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
catalogId The ID of the catalog. required

Body

Attribute Type Description
data CatalogItem A valid catalog item object.

delete-catalog-item_icon Delete catalog item

Example: Request

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

Example: Response

{
    "data": {
        "_type": "CatalogItem",
        "_id": "item-1",
        "schema": "product",
        "catalog": {
            "_type": "Catalog",
            "_id": "1",
            "name": "catalog-1"
        },
        "images": [
            {
                "_type": "Image",
                "_id": "1",
                "uri": "https://example.com/products/1/a.png",
                "width": 200,
                "height": 300
            },
            {
                "_type": "Image",
                "_id": "2",
                "uri": "https://example.com/products/1/b.png",
                "width": 200,
                "height": 300
            }
        ],
        "category": {
          "_type": "Category",
          "_id": "1",
          "name": "sunglasses"
      },
        "data": {
            "id": "external-id-1",
            "foo": "bar"
        },
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Delete an existing catalog item.

HTTP Request

DELETE https://api.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

Query Parameters

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://api.markable.ai/catalogs/catalog-1/items/item-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://api.markable.ai/catalogs/catalog-1/items/item-1 \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_type": "CatalogItem",
        "_id": "item-1",
        "schema": "product",
        "catalog": {
            "_type": "Catalog",
            "_id": "1",
            "name": "catalog-1"
        },
        "images": [
            {
                "_type": "Image",
                "_id": "1",
                "uri": "https://example.com/products/1/a.png",
                "width": 200,
                "height": 300
            },
            {
                "_type": "Image",
                "_id": "2",
                "uri": "https://example.com/products/1/b.png",
                "width": 200,
                "height": 300
            }
        ],
        "category": {
          "_type": "Category",
          "_id": "1",
          "name": "sunglasses"
      },
        "data": {
            "id": "external-id-1",
            "foo": "bar"
        },
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Get an existing catalog item.

HTTP Request

GET https://api.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

Query Parameters

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

list-catalog-item_icon List catalog items

Example: Request

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

Example: Response

{
    "data": [
        {
            "_type": "CatalogItem",
            "_id": "item-1",
            "schema": "product",
            "catalog": {
                "_type": "Catalog",
                "_id": "1",
                "name": "catalog-1"
            },
            "images": [
                {
                    "_type": "Image",
                    "_id": "1",
                    "uri": "https://example.com/products/1/a.png",
                    "width": 200,
                    "height": 300
                },
                {
                    "_type": "Image",
                    "_id": "2",
                    "uri": "https://example.com/products/1/b.png",
                    "width": 200,
                    "height": 300
                }
            ],
            "category": {
              "_type": "Category",
              "_id": "1",
              "name": "sunglasses"
          },
            "data": {
                "id": "external-id-1",
                "url": "https://company.xyz/external-product-id-1",
                "foo": "bar"
            },
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        },
        {
            "_type": "CatalogItem",
            "_id": "item-2",
            "schema": "product",
            "catalog": {
                "_type": "Catalog",
                "_id": "1",
                "name": "catalog-1"
            },
            "images": [
                {
                    "_type": "Image",
                    "_id": "1",
                    "uri": "https://example.com/products/1/a.png",
                    "width": 200,
                    "height": 300
                },
                {
                    "_type": "Image",
                    "_id": "2",
                    "uri": "https://example.com/products/1/b.png",
                    "width": 200,
                    "height": 300
                }
            ],
            "category": {
              "_type": "Category",
              "_id": "1",
              "name": "sunglasses"
          },
            "data": {
                "id": "external-id-2",
                "url": "https://company.xyz/external-product-id-2",
                "foo": "bar"
            },
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        }
    ]
}

Get all existing catalog items.

HTTP Request

GET https://api.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
catalogId The ID of the catalog. required

Image Search

image-search_icon The Image Search Query Object

Example: Image Search Query Object

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

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

Attribute Type Description
image_uri String A valid image URI. required
catalogs Array<Catalog> List of catalogs (public or private) - which will be included the visual search scope.

Example: Simple Image Search without Catalogs

POST https://api.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png"
    }
}

Example: Image Search with Catalogs

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

Example: Response

{
    "meta": {
        "image": {
            "width": 100,
            "height": 100
            "uri": "http://i.com/1.png"
        },
        "stats": {
            "detection": 313,
            "extraction": 141,
            "search": 8,
            "image_download": 57
        },
    },
    "data": [
        {
            "type": "SearchResult"
            "category": {
                "_type": "Category",
                "_id": "shorts",
                "name": "shorts"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "y": 266,
                "x": 54,
                "height": 145,
                "width": 204
            },
            "score": 0.963,
            "matches": [
                {
                    "_type": "CatalogItem",
                    "_id": "5938629ec77b4a05f48f782a",
                    "score": 0.701,
                    "images": [
                        {
                            "uri": "http://i.com/result1.png",
                            "_type": "Image"
                        },
                        {
                            "uri": "http://i.com/result2.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog"
                        "name": "catalog-1",
                        "_id": "catalog-1"
                    }
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                },
                {
                    "_type": "CatalogItem",
                    "_id": "59386368c77b4a05fa8f7b06",
                    "score": 0.7,
                    "images": [
                        {
                            "uri": "http://i.com/result2.png"
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog"
                        "name": "catalog-1",
                        "_id": "catalog-1"
                    },
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                }
            ]
        },
        {
            "type": "SearchResult",
            "category": {
                "_type": "Category",
                "_id": "sandals",
                "name": "sandals"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "y": 266,
                "x": 54,
                "height": 145,
                "width": 204
            },
            "score": 0.831,
            "matches": [
                {
                    "_type": "CatalogItem",
                    "_id": "5938629ec77b4a05f48f7821",
                    "score": 0.62,
                    "images": [
                        {
                            "uri": "http://i.com/result5.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog"
                        "name": "catalog-2",
                        "_id": "catalog-2"
                    },
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                },
                {
                    "_type": "CatalogItem",
                    "_id": "59386368c77b4a05fa8f7b02",
                    "score": 0.4,
                    "images": [
                        {
                            "uri": "http://i.com/result4.png"
                            "_type": "Image"
                        },
                        {
                            "uri": "http://i.com/result5.png"
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog"
                        "name": "catalog-2",
                        "_id": "catalog-2"
                    },
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                }
            ]
        }
    ]

Search an image - detect and retreive objects (products/logos/faces) based on visual features/similarity.

HTTP Request

POST https://api.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.