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.
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
Sort Options
Default sort is by ID, ascending. Prefixing a sort value with - will sort in descending order.
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
Sort Options
Default sort is by ID, ascending. Prefixing a sort value with - will sort in descending order.
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.
