Smyle Engine API

Smyle Engine API for computer vision as a service.

Base URI

https://{Application-ID}.engine.smyle.io/0
Headers
X-Smyle-Application-Id
string required
Applied to all methods

Your application ID.

X-Smyle-API-Key
string required
Applied to all methods

Your API key.

Responses
Documentation
Request format

For POST and PUT requests, the request body must be JSON, with the Content-Type header set to application/json.

Authentication is done via HTTP headers. The X-Smyle-Application-Id header identifies which application you are accessing, and the X-Smyle-API-Key header authenticates the endpoint.

API Methods
Indexes and types

We describe in this section the ressources related to adding and retrieving objects to indexes.

GET /indexes
DELETE /indexes/{indexName}/_clear
DELETE /indexes/{indexName}
GET /indexes/{indexName}
DELETE /indexes/{indexName}/{typeName}/_clear
DELETE /indexes/{indexName}/{typeName}
List indexes
GET /indexes

This command lists all your existing indexes.

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

Clear an index (disabled)
DELETE /indexes/{indexName}/_clear

This method deletes the index content. Settings and index specific API keys are kept untouched.

Path variables

indexName
string required

The name of the index.

Example:
shoes

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

404 NOT_FOUND

The object ID does not exist.

Delete an index (disabled)
DELETE /indexes/{indexName}

This method deletes an existing index and associated types.

Path variables

indexName
string required

The name of the index.

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

404 NOT_FOUND

The object ID does not exist.

List types
GET /indexes/{indexName}

This command lists the existing types for the given index.

Path variables

indexName
string required

The name of the index.

Example:
shoes

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

Clear a type (disabled)
DELETE /indexes/{indexName}/{typeName}/_clear

This method deletes the type content. Type's settings are kept untouched.

Path variables

indexName
string required

The name of the index.

Example:
shoes
typeName
string required

The name of the type.

Example:
heels

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

404 NOT_FOUND

The object ID does not exist.

Delete a type (disabled)
DELETE /indexes/{indexName}/{typeName}

This method deletes an existing index.

Path variables

indexName
string required

The name of the index.

Example:
shoes
typeName
string required

The name of the type.

Example:
heels

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

404 NOT_FOUND

The object ID does not exist.

Objects indexing
POST /indexes/{indexName}/{typeName}
PUT /indexes/{indexName}/{typeName}/{objectID}
GET /indexes/{indexName}/{typeName}/{objectID}
GET /indexes/_all/_all
POST /indexes/{indexName}/{typeName}/{objectID}/partial
DELETE /indexes/{indexName}/{typeName}/{objectID}
Add an object without ID
POST /indexes/{indexName}/{typeName}

This method adds one object in the index with automatic assignation of id.

Path variables

indexName
string required

The name of the index.

Example:
shoes
typeName
string required

The name of the type.

Example:
heels

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Request body

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

400 BAD_OBJECT

The uploaded JSON does not correspond to the object model.

Add or update an object by ID (partially disabled)
PUT /indexes/{indexName}/{typeName}/{objectID}

This method adds or replaces an object (if the object does not exist, it will be created). Be careful: the object ID is shared across all indexes and types. If it already exists in another index or type it will be deleted first. The object will also be completely overriden: existing attributes that are not replaced are deleted.

Path variables

indexName
string required

The name of the index.

Example:
shoes
typeName
string required

The name of the type.

Example:
heels
objectID
string required

The object ID.

Example:
prod-342

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Request body

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

400 BAD_OBJECT

The uploaded JSON does not correspond to the object model.

Retreive an object by ID
GET /indexes/{indexName}/{typeName}/{objectID}

Retrieves an indexed object.

Path variables

indexName
string required

The name of the index.

Example:
shoes
typeName
string required

The name of the type.

Example:
heels
objectID
string required

The object ID.

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

404 NOT_FOUND

The object ID does not exist.

Retrieve multiple objects
GET /indexes/_all/_all

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Request body

Object
requests
Object
indexName
string
Example:
index1
typeName
string
Example:
type1
objectID
string
Example:
id1

Responses

200 OK
Body
Object
results
Object
indexName
string
Example:
index1
typeName
string
Example:
type1
objectID
string
Example:
obj1
403 INVALID_KEY

The application ID or API key is invalid.

400 BAD_OBJECT

The uploaded JSON does not correspond to the object model.

Partially update an object by ID (partially disabled)
POST /indexes/{indexName}/{typeName}/{objectID}/partial

This method updates part of an object (if the object does not exist, it will be created. You can avoid an automatic creation of the object by passing createIfNotExists=false as query argument).

Path variables

indexName
string required

The name of the index.

Example:
shoes
typeName
string required

The name of the type.

Example:
heels
objectID
string required

The object ID.

Example:
prod-345

Request parameters

createIfNotExists
boolean optional

Create the object if it doesn't exist. Default: true.

Example:
true

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Request body

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

400 BAD_OBJECT

The uploaded JSON does not correspond to the object model.

404 NOT_FOUND

The object ID does not exist.

Delete an object by ID (disabled)
DELETE /indexes/{indexName}/{typeName}/{objectID}

This method deletes an existing object from the index.

Path variables

indexName
string required

The name of the index.

Example:
shoes
typeName
string required

The name of the type.

Example:
heels
objectID
string required

The object ID

Example:
prod-345

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
403 INVALID_KEY

The application ID or API key is invalid.

404 NOT_FOUND

The object ID does not exist.

Objects ranking

Ranking query.

GET /rank/{indexNames}/{typeNames}/{objectID}
GET /indexes/{indexNames}/{typeNames}
Find most similar by object ID
GET /rank/{indexNames}/{typeNames}/{objectID}

Return objects ranked by similarity with the query.

Path variables

indexNames
string required

The name of the index, or a list of indexes separated by commas, or _all for all indexes.

Example:
shoes
typeNames
string required

The name of the type, or a list of types separated by commas, or _all for all types.

Example:
heels
objectID
string required

The object ID.

Example:
prod-345

Request parameters

page
number optional

Pagination parameter used to select the page to retrieve. Page is zero-based and defaults to 0. Thus, to retrieve the 10th page you need to set page=9.

Example:
0
hitsPerPage
number optional

Pagination parameter used to select the number of hits per page. Defaults to 40.

Example:
40

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
Body
403 INVALID_KEY

The application ID or API key is invalid.

400 BAD_OBJECT

The uploaded JSON does not correspond to the object model.

404 NOT_FOUND

The object ID does not exist.

Find most similar to new image
GET /indexes/{indexNames}/{typeNames}

Return objects ranked by similarity with the query.

Path variables

indexNames
string required

The name of the index, or a list of indexes separated by commas, or _all for all indexes.

Example:
shoes
typeNames
string required

The name of the type, or a list of types separated by commas, or _all for all types.

Example:
heels

Request parameters

query
string required

The image URL query.

Example:
http://www.test.com/image.jpg
page
number optional

Pagination parameter used to select the page to retrieve. Page is zero-based and defaults to 0. Thus, to retrieve the 10th page you need to set page=9.

Example:
0
hitsPerPage
number optional

Pagination parameter used to select the number of hits per page. Defaults to 40.

Example:
1

Request headers

X-Smyle-Application-Id
string required

Your application ID.

X-Smyle-API-Key
string required

Your API key.

Responses

200 OK
Body
403 INVALID_KEY

The application ID or API key is invalid.

400 BAD_OBJECT

The uploaded JSON does not correspond to the object model.

404 NOT_FOUND

The object ID does not exist.

Data Reference
Posted object model object

The model for an object which is posted or put in an index.

Properties

_imgs
Array

The list of images.

Object
img
string

The image URL.

Example:
http://url1.jpg
cropping
string

The cropping type. Possible values:

  • manual: image is cropped only if bounding_box or polygon is provided by user. If cropped, it fires on_crop event.
  • uniform: image is cropped only if uniform background is detected. If cropped, it fires on_crop event.
  • detect: image is cropped only if the object type is detected. If cropped, it fires on_detect and on_crop event.
  • segment: same as detect but the background is removed. If cropped, it fires on_detect and on_crop event.

Default is uniform. Values are ordered: e.g. a detect cropping type implies uniform and user.

Example:
uniform
indexing
string

The indexing type. Possible values:

  • off: no indexing
  • on_crop: indexed only if cropped.
  • on_detect: indexed only if object is detected.
  • on: indexed in any case.

Default value is on.

Example:
on
training
string

The indexing type. Possible values:

  • off: no indexing
  • on_crop: indexed only if cropped.
  • on_detect: indexed only if object is detected.
  • on: indexed in any case.

Default value is on_detect.

Example:
on_detect
bounding_box
Object
xmin
number
Example:
0
xmax
number
Example:
1
ymin
number
Example:
0
ymax
number
Example:
1
polygon
Array of Point
any
string
Example:
text field
or
number
Example:
2.3
or_maybe
Array of string
Example:
list
or_finally
Array of number
Example:
1
Index or type list object

A list of indexes or types.

Properties

items
Array
Object
name
string

The index or type name.

Example:
heels
createdAt
string

The UTC creation time.

Example:
2013-08-15T19:52:13.225Z
updatedAt
string

The last UTC update time.

Example:
2013-08-17T07:59:28.313Z
entries
number

The number of items.

Example:
364
pendingTask
number

Indicates the number of pending tasks for the index or type.

Example:
10
Object update status object

The status ID of an created or updated object.

Properties

created
boolean

Indicate if the object has been created or updated.

Example:
false
updatedAt
string

The last update UTC time.

Example:
2013-01-18T15:33:13.556Z
taskID
number

The task ID.

Example:
680
objectID
string

The object ID.

Example:
myID
Object delete status object

The status ID of a deleted object.

Properties

deletedAt
string

The deletion UTC time.

Example:
2013-01-18T15:33:13.556Z
taskID
number
Example:
681
Query object

A query.

Properties

imgs
Array
Object
img
string
Example:
http://url1.jpg
cropping
string
Example:
uniform
bounding_box
Object
xmin
number
Example:
0
xmax
number
Example:
1
ymin
number
Example:
0
ymax
number
Example:
1
polygon
Array
Object
x
number
Example:
0.2
y
number
Example:
0.2
BoundingBox object

A bounding box model.

Properties

xmin
number
Example:
0
xmax
number
Example:
1
ymin
number
Example:
0
ymax
number
Example:
1
Point object

A point model

Properties

x
number
Example:
0.2
y
number
Example:
0.2
Retriveved object model object

The model for an object which retrieved by a GET method.

Properties

_imgs
Array

The list of images.

Object
img
string

The image URL.

Example:
http://url1.jpg
cropping
string
Example:
uniform
indexing
string
Example:
on
training
string
Example:
on_crop
bounding_box
Object
xmin
number
Example:
0
xmax
number
Example:
1
ymin
number
Example:
0
ymax
number
Example:
1
polygon
Array
Object
x
number
Example:
0.2
y
number
Example:
0.2
cropped
boolean
Example:
true
indexed
boolean
Example:
true
trained
boolean
Example:
true
bounding_box_cropped
Object
xmin
number
Example:
0
xmax
number
Example:
1
ymin
number
Example:
0
ymax
number
Example:
1
any
string
Example:
text field
or
number
Example:
2.3
or_maybe
Array of string
Example:
list
or_finally
Array of number
Example:
1
Response object

The response model.

Properties

results
Array
Object
indexName
string
Example:
shoes
typeName
string
Example:
heels
page
number
Example:
0
nbHits
number
Example:
38
nbPages
number
Example:
19
processingTimeMS
number
Example:
6
hits
Array
Object
_objectID
string
Example:
2051967
_rankingInfo
Object
score
number
Example:
0.094552
scores
Object
pattern
number
Example:
0.223
color
number
Example:
0.424
query
Object