Management API Documentation

Management API

The Management API is a RESTful interface to any action you can do in your account of the CraftAR Service.

Use the Management API to integrate CraftAR functionalities in your applications and services. It allows you to programmatically access and manipulate all resources found in CraftAR.

The API follows a RESTful architecture, uses HTTPS exclusively and accepts and returns JSON. This document contains a detailed description of the API calls.

We provide PHP and Python libraries for the Management API. Thanks to our customers, we also have implementations of this API for .NET, and Ruby.

Table of contents

Common

URL All the endpoint urls use HTTPS and follow this format

All the endpoint urls use HTTPS and follow this format: In example, this would be the url to access get the list of all the collections: All resources contain a resource_uri that identifies it within the API.

Authentication API calls can be authenticated in two ways: by using the API Key, or by using the Session.

API Key The API Key is a string associated with your account. Get your API Key here. Don’t share your API Key. If you suspect your API Key has been compromised, you can revoke it and generate a new one. To authenticate, just add ‘api_key’ as a GET or POST parameter. In example: Note: all our examples below will use that api_key. Session Note that this is included as a convenient method for testing and debugging, but it should not be used in production. This authentication scheme checks if you are logged in and have an active session. In example, if you are already logged in:

Invalid API key

HTTP Status code: 403 Forbidden

Pagination When getting a list of resources, the Management API will return a paginated set of objects.

To manage the pagination, all responses have a ‘meta’ field. In example: The "meta" fields
  • total_count: total number of objects in the underlying object list
  • limit: how many objects are returned per page. By default it’s 20.
  • offset: how many initial objects are skipped in this response
  • previous: if available, provides a URI to the previous page
  • next: if available, provides a URI to the next page
Fetching a page To navigate through pages, use the ‘limit‘ and ‘offset‘ parameters. In example: Get the first page (first 5 collections): Get the second page: Get the next page:

Collection

A Collection is a group of Items. It has at least one Token.
Resource
Description
Parameters optional
Get collection

Retrieve a single collection by ID

  • uuid: collection's unique identifier
Get collection list

Retrieve a list of collections

  • name: filter by this exact match.
  • name__contains: filter by case-sensitive containment.

Item

The basic concept you want to recognize. An Item belongs to a Collection. It has at least one Image.
Resource
Description
Parameters optional
Create item

Create a new item

  • name: string that describes the item
  • collection: resource uri like /api/v0/collection/UUID/
  • tags: list of resource URIs like ["/api/v0/tag/UUID1/", "/api/v0/tag/UUID2/"]
  • url: URL related to the item's content
  • content: a valid JSON object
  • custom: any type of custom data attached to the item.
  • trackable: true for creating an AR item (default: false)
Delete item

Delete an existing item

  • uuid: item's unique identifier
Get item

Retrieve a single item by UUID

  • uuid: item's unique identifier
Get item list

Retrieve a list of items

  • name: filter by this exact match.
  • name__contains: filter by case-sensitive containment.
  • collection__uuid: filter by collection UUID.
  • collection__name: filter by collection name, using this exact match.
  • collection__name__contains: filter by collection name, using case-sensitive containment.
Update item

Update an existing item

  • uuid: item's unique identifier
  • tags: list of resource URIs like ["/api/v0/tag/UUID1/", "/api/v0/tag/UUID2/"]
  • url: URL related to the item's content
  • content: a valid JSON object
  • custom: any type of custom data attached to the item.
  • trackable: true for creating an AR item (default: false)

Image

Belongs to an Item. An Item can be recognized from several images, in example:
Resource
Description
Parameters optional
Create image

Create a new image

  • item: resource uri like /v0/item/UUID/
  • file: file with the new reference image
Delete image

Delete an existing image

  • uuid: image's unique identifier
Get image

Retrieve a single image by UUID

  • uuid: image's unique identifier
Get image list

Retrieve a list of images

  • name: filter by this exact match.
  • name__contains: filter by case-sensitive containment.
  • item__uuid: filter by item UUID.
  • item__name: filter by item by this exact match.
  • item__name__contains: filter by item by case-sensitive containment.
  • item__collection__uuid: filter by item’s collection UUID.
  • item__collection__name: filter by item’s collection name, using this exact match.
  • item__collection__name__contains: filter by item’s collection name, using case-sensitive containment.
  • status: filter by image status (ER or OK).

Tag

Resource
Description
Parameters optional
Create tag

Create a new Tag in a given Collection. You should contact support to enable this feature int your account.

  • collection: resource uri like /v0/collection/UUID/
  • name: unique name of your Tag
Delete tag

Delete an existing tag

  • uuid: tag's unique identifier
Get tag

Retrieve a single Tag by UUID

  • uuid: tag's unique identifier
Get tag list

Retrieve a list of tags

  • name: filter by this exact match.
  • name__contains: filter by case-sensitive containment.

CollectionBundle

Resource
Description
Parameters optional
Create Collection Bundle

Create a collection bundle for an offline SDK or, regenerate it if a bundle with the same parameters already exists.

  • collection: resource uri like /v0/collection/UUID/
  • app: resource uri like /v0/app/UUID/
  • version: resource uri like /v0/version/UUID/
  • tag: resource uri like /api/v0/tag/UUID/
Get Collection Bundle List

Retrieve a list of Collection Bundles

  • tag__name: filter by tag name, using this exact match.
  • app__name: filter by application name, using this exact match.

Application ID

Resource
Description
Parameters optional
Create application

Create a new Application ID

  • collection: resource uri like /v0/collection/UUID/
  • name: name of your application's identifier
Get application

Retrieve a single Application ID by ID

  • uuid: application's unique identifier

SDK Version

Resource
Description
Parameters optional
Get SDK version

Retrieve a single SDK version by ID

  • uuid: SDK version unique identifier
Get SDK Version List

Retrieve a list of available SDK versions

  • sdk_name: filter by SDK's name
  • sdk_version: filter by SDK's version

Token

A Token belongs to a Collection. It’s used to identify the Collection when doing queries against the Recognition API.
Resource
Description
Parameters optional
Create token

Create a new token.

  • collection: resource uri like /v0/collection/UUID/
Delete token

Delete an existing token

  • uuid: token's unique identifier
Get token list

Retrieve a list of tokens

  • collection__uuid: filter by collection UUID.
  • collection__name: filter by collection name, using this exact match.
  • collection__name__contains: filter by collection name, using case-sensitive containment.
Update token
  • uuid: item's unique identifier
  • tags: list of resource URIs like ["/api/v0/tag/UUID1/", "/api/v0/tag/UUID2/"]

Media

Media objects are an optional feature that we provide for convenience, in case you don’t have a CDN.
Resource
Description
Parameters optional
Create media

Create a new media

  • file: file with the new media object
Delete media

Delete an existing media

  • uuid: media's unique identifier
Get media

Retrieve a single media object by UUID

  • uuid: media's unique identifier
Get media list

Retrieve a list of media objects

  • name: filter by this exact match.
  • name__contains: filter by case-sensitive containment.
  • mimetype: filter by this exact match.
  • mimetype__contains: filter by case-sensitive containment.