This documentation is for our current platform, hosted at bluebite.com. If you are still using the mtag.io Object Manager or Studio to manage your Blue Bite account, please see our Legacy Documentation.

Blue Bite Object API

Overview

In the Blue Bite Experience Suite, Objects are digital records that represent physical items. Touchpoints are digital records that represent the interaction point for an Object (e.g. a QR code or NFC chip). Encoded URLs are maintained on the Touchpoint level, and Objects can contain one or more Touchpoints. 

The Blue Bite Object API can be used to create and update Objects and Touchpoints programmatically.

The Object API supports two primary use cases:

  • Single-object Management (e.g. I want to create or update one specific object via API calls)
  • Bulk Object Import (e.g. I want to create or update several objects via a single API call)

A common use case is association, where a user needs to programmatically upload one or many Objects to Blue Bite without interfacing with the UI. Object attributes, variables, and touchpoints and custom attributes can all be created and edited via this API.

Access & API Keys

The Object API is available to all Object Manager users, and uses API keys to authenticate requests. When making requests, you must specify your API key in the X-Api-Key header. Please contact your account manager or email support@bluebite.com to request an API key. 

Object API Keys are scoped to a specific Organization. If you wish to use the Object API to manage Objects across multiple Organizations, you will need a unique key for each Organization. When making requests, you will need to ensure you’re authenticating with the proper key. 

Whoever has access to your API key will be able to create, update, and delete Objects and Touchpoints in your account.  Be sure to keep your API keys stored as securely as you would store a password. Do not publish your API keys where they will be publicly accessible (e.g. Github). If you believe your API Key has been compromised, contact your Account Manager (or email support@bluebite.com) as soon as possible.

Expected Responses

Blue Bite uses standardized HTTP response codes to indicate the result of an API request.

Response Code & Description
Example Case
2XX - Success
Object successfully created. Successes can be full or partial. 
400 - Bad Request
Request invalid. Ensure your request is properly formatted.
401 - Unauthorized
Request failed due to authentication. Ensure API key is valid. 
404 - Not Found
Requested item not found. Ensure you’re attempting to manipulate an object that exists in your account.
429 - Too Many Requests
Rate limits violated. 
5XX - Something Went Wrong
An internal error occurred, or the request took too long to resolve. Contact support if this happens repeatedly. 

If your response results in a failure, there will be an informative message included in the response payload. 

Single-Object Operations

If you need to manage individual objects, our single-object API routes are the best way to do so. Below is a high-level overview of the functionality of each route. To view example requests and responses, please see our interactive documentation here

Create Object

POST /v3/objects
Rate Limit: 200 requests/minute

Use this route to create an object in your account. You may include the following object information on an Object create request:

  • Object Note
  • Custom Attributes
  • Object Variables
  • Active (1) or Inactive (0) status 
  • Touchpoints (must include slug and pertinent identifiers)

Retrieve Object

To retrieve information about an object in your account, you can use our single-object GET routes. The response payload will include all object data (object note, custom attributes, variables, project association, Touchpoints, etc).

In order to identify which object you’d like to retrieve, you can use one of three identifiers:

  • Integer identifier (id)
  • Object UUID 
  • Touchpoint URL 

Option 1: Get Object using Integer ID 

GET /v3/objects/{id}
ID: 123
Request Path: https://api.bluebite.com/v3/objects/123

Option 2: Get Object using UUID 

GET /v3/objects/uuid/{uuid}
UUID: 1b006eb3-7cd8-464b-b3f5-7e94e652eb5a
Request Path:
https://api.bluebite.com/v3/objects/uuid/?id=1b006eb3-7cd8-464b-b3f5-7e94e652eb5a

Option 3: Get Object using Touchpoint URL

GET /v3/objects/touchpoint/{escaped touchpoint URL}

To lookup objects via Touchpoint URL, you must escape the Touchpoint URL. Instructions on how to escape URLs can be found here.

Touchpoint URL: https://bb.io/q/?id=1b006eb3-7cd8-464b-b3f5-7e94e652eb5a
Request Path: https://api.bluebite.com/v3/objects/touchpoint/?id=https%3A%2F%2Fbb.io%2Fq%2F?id%3D1b006eb3-7cd8-464b-b3f5-7e94e652eb5a

Update Object

PUT /v3/objects/{id}
Rate Limit: 200 requests/minute

Use this route to update objects in your account. PUT requests must contain a complete set of object attributes, or else information will be lost. The response payload will include all updated object data (object note, custom attributes, variables, project association, Touchpoints, etc).

Like the single-object GET route, you can look up objects by integer ID, UUID, or touchpoint URL. The request format is the same as the above examples – only the operation differs.

Delete Object

DELETE /v3/objects/{id}
Rate Limit: 200 requests/minute

This endpoint allows API users to delete objects in their account. This is a permanent action that cannot be reversed. If an object is deleted, all associated touchpoint data will also be deleted. Attempting to visit a deleted touchpoint URL will lead to our whoops page

Unlike the single-object GET and PUT operations, you can only delete objects by integer ID. 

Object List & Bulk Delete

List Objects

GET /v3/objects
Rate Limit: 25 requests/minute

Requests to this endpoint will return a list of objects in your account. 

Pagination

Results can be paginated by using limit and offset values. To view the next or previous page of results, use the next or previous URLs from the response. By default, responses will include 100 items. At a maximum, responses can include 1,000 items. 

Filter Options

Filter Field
Notes
batch_operation_id
Pass in the ID of an import to see a list of all objects included in an import.
data.<key>
Filter by custom attributes.
variables.<key>
Filter by object variables.
note
Filter by note. This will return all objects with notes containing the query string.
status
Filter by active (1) or inactive (0) status.
technology
Filter by Touchpoint technology type (QR, NFC, GS1).

Sort Options

Default sort is by ID, ascending. Prefixing a sort value with - will sort in descending order.

Sort Field
id
created_at
updated_at
data.<key>
variables.<key>
project_name
status
note
technology

Delete Multiple Objects

DELETE /v3/objects/{id1, id2, id3…}
Rate Limit: 200 requests/minute

We allow API users to delete several objects in their account if necessary. To do this, pass in a comma-delimited list of object IDs. This is a permanent action that cannot be reversed. 

Bulk Object Imports

If you need to manage your objects in bulk, our object import routes are the best way to do so. Below is a high-level of the functionality of each route. To view example requests and responses, please see our interactive documentation here. 

How does it work?

To process a bulk import, you will need to submit a CSV or JSON file with object data.

Creating Objects via Import

To create new objects, all columns are optional. However, the objects will not be usable in the real world if they do not define at least one Touchpoint.

Updating Objects via Import

To update Objects, you must include either a uuid or Touchpoint data. A Touchpoint’s identifier, id or sample URL are all acceptable object identifiers. All other columns are optional. 

Unlike the single-object routes, these updates are PATCH operations – any columns not explicitly included in the import file will not be changed. 

Creating and Updating Objects in the same file

Imports are “update or create” operations. In other words, you can submit an import file that includes data for both new objects and objects that already exist in your account. To do this, include the UUID column in the import file, but leave that value blank for any rows that are supposed to create new objects. This can also be done by using TouchPoints. 

Example file

First two rows will update existing objects (if found), third row will create a new object. 

Download the example file here.

Submit an Object Import

POST /v3/import/
Rate Limit: 15 requests / minute

Use this route to submit an import file. We accept import data in CSV and JSON form. Import files cannot exceed 5MB.

Get a List of Previous Imports

GET /v3/import/
Rate Limit: 25 requests / minute

Use this route to retrieve a list of import files. 

Results can be paginated by using limit and offset values. To view the next or previous page of results, use the next or previous URLs from the response. By default, responses will include 100 items. At a maximum, responses can include 1,000 items. 

Filter Options

Filter Field
Notes
uploaded_by
Filter by the user that uploaded the file. Accepts an integer ID. 
file_type
JSON or CSV
status
Options are QUEUED, PROCESSING, COMPLETED, CANCELED, FAILED via their enumerated counterparts (0-4).

Sort Options

Default sort is by ID, ascending. Prefixing a sort value with - will sort in descending order.

Sort Field
id
created_at
uploaded_by
file_type
file_name
status

Retrieve Import Details

GET /v3/import/{id}
Rate Limit: 200 requests / minute

Use this route to check the status of an import (either in-progress or already-completed). 

Retrieve Import Results

GET /v3/import/{id}/results
Rate Limit: 75 requests / minute

Use this route to check the results of a completed import file. This route will return information about each individual row of a specified import.

Download an Import File

GET /v3/import/{id}/download
Rate Limit: 25 requests / minute

Use this route to retrieve a link to download an import file.