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.

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


Retrieve a single collection by ID

  • uuid: collection's unique identifier

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 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 an existing item

  • uuid: item's unique identifier

Retrieve a single item by UUID

  • uuid: item's unique identifier

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 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 a new image

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

Delete an existing image

  • uuid: image's unique identifier

Retrieve a single image by UUID

  • uuid: image's unique identifier

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 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 an existing tag

  • uuid: tag's unique identifier

Retrieve a single Tag by UUID

  • uuid: tag's unique identifier

Retrieve a list of tags

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

CollectionBundle


Resource
Description
Parameters optional

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/

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 a new Application ID

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

Retrieve a single Application ID by ID

  • uuid: application's unique identifier

SDK Version


Resource
Description
Parameters optional

Retrieve a single SDK version by ID

  • uuid: SDK version unique identifier

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 a new token.

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

Delete an existing token

  • uuid: token's unique identifier

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.

  • 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 a new media

  • file: file with the new media object

Delete an existing media

  • uuid: media's unique identifier

Retrieve a single media object by UUID

  • uuid: media's unique identifier

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.