Need Help?

Compass API Guide

Last Updated: Dec 18, 2015

This document provides an overview of how to use the API for Luminoso's compass product. For the full list of API endpoints, see the API documentation.

Input and output


NOTE: Ensure that all calls to the Compass API include a trailing slash in the endpoint URL.

For GET/DELETE requests, parameters should go in the URL as query parameters. For PUT/POST requests, parameters should almost always go in the request body (exceptions for particular endpoints are noted in their documentation); they can be formatted as HTML forms (in which case the Content-Type header should be set to "application/x-www-form-urlencoded") or as JSON (in which case the Content-Type header should be set to "application/json").


Response bodies are JSON-encoded (except for certain 50X server errors).

Successful responses use the following HTTP codes:

  • 200 (OK) - request was successful
  • 201 (Created) - request was successful and a new object was created
  • 204 (No Content) - request was successful and the object was deleted

Some API methods return a "paginated" list of objects (for example, getting the list of messages in a topic). A paginated list is a JSON object with four keys:

  • count (integer) - total number of items (in all pages combined)
  • next (string) - URL of next page of items (null if there is no next page)
  • previous (string) - URL of previous page of items (null if there is no previous page)
  • results (JSON list of objects) - the items in the current page (each page contains up to 20 items)


Error responses use the following HTTP codes:

  • 400 (Bad Request) - request was invalid (e.g., a required parameter was missing)
  • 401 (Unauthorized) - request was not authenticated (authorization token or session cookie was either not provided or not valid)
  • 403 (Forbidden) - request was authenticated but user does not have permission to perform the action
  • 404 (Not Found) - requested URL doesn't exist
  • 405 (Method Not Allowed) - HTTP method specified in the request is not allowed on specified URL
  • 500 (Internal Server Error) - other unexpected error

In cases where there is an error, in addition to the HTTP code the response will include some information about the error. This information will usually be a JSON object but could also be a JSON string.

Below are some typical examples of error responses.

For a 401 (Unauthorized), when the request is not authenticated:

   "detail": "Authentication credentials were not provided."

For a 400 (Bad Request), when trying to create a project while specifying no name and a nonexistent account:

   "name": [
       "This field is required."
   "account": [
       "Invalid pk 'xxx' - object does not exist."

Data types

The documentation refers to several data types for parameters:

  • number - a numerical value (integer or floating point)
  • integer - an integer value
  • string - a string (in responses, this will be JSON-encoded)
  • boolean - a boolean value (in responses and JSON request bodies, true or false; in query parameters, True or False; in HTML forms, f/F/false/False/FALSE/0 are false and anything else is true)
  • time - a representation of a time (in responses, this will be a string in ISO format, such as 2014-08-17T12:45:01.22+00:00; in requests, it can be in this ISO format or a number of seconds since the UNIX epoch)

Authentication and access


A permission allows a particular user to do certain things with respect to a particular account.

The permission levels are:

  • read: the user can view account information and can view projects owned by the account
  • readwrite: the user can view account information and can view, modify, and create projects owned by the account
  • manage: the user can view and modify account information, and can view, modify, and create projects owned by the account

In addition to permissions on accounts, there is a special status called "site admin". If a user is a site admin, s/he is allowed to do everything. Site admins are the only users who are allowed to create accounts and users.

Tokens and authentication

Each user can obtain a token that can be used to authenticate to the API. Currently, each user can have at most one token. All tokens currently expire two weeks after their creation, or they can be deleted manually. A user's token is also reset if his password is reset or changed.

For an API request to be authenticated, it should include an "Authorization" header, whose value should be the string "Token " followed by the user's token. For example, if the token is "74e6d14dbde4303fe9864cb77306cc36394de460", then the value of the Authorization header should be "Token 74e6d14dbde4303fe9864cb77306cc36394de460".

To obtain your token, log in with your username and password. If you already have a token, the login response will include your existing token, otherwise it will include a newly-generated token.

More Support
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found