Need Help?

Compass API Endpoints

Last Updated: Nov 11, 2016

Compass API Documentation

The following endpoints/methods are provided by the Compass API:

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

To make API requests, the endpoints listed here should be prefixed with "https://<compass-url.tld>/api". For general information on how to use the Compass API, refer to the API Guide.

Projects

A project is one set of data (messages and their associated information and analysis).

A project object in the API has the following fields:

  • url (string): project URL (containing randomly-generated unique ID for the project)
  • name (string): name for the project (not necessarily unique)
  • account (string): unique ID of the account that owns this project
  • description (string): a description of the project, or notes about it, etc.
  • language (string): language code for the project's messages
  • status (string): "active" or "inactive" (an inactive project can still be viewed but will not process any new messages)
  • creator (string): username of the user who created the project
  • created (time): time at which the project was created
  • twitter_cap (integer): maximum number of messages this project can get from Twitter per day

GET /projects/

Get the list of all the projects the user has access to.

Permission required: none

Required parameters: none

Optional query parameters:

  • account (string): ID of a single account whose projects to list
  • status (string): only list projects that have this status ("active" or "inactive")

Response: paginated list of project objects

POST /projects/

Create a project.

Permission required: write

Required body parameters:

  • name (string): name for the project
  • account (string): ID of the account that will own the project
  • language (string): language code for the project's messages

Optional body parameters:

  • description (string): description, notes, etc.
  • status (string): "active" (default) or "inactive"
  • twitter_cap (integer): maximum number of messages this project can get from Twitter per day

Response: new project object

GET /projects/<project_id>/

Get a project.

Permission required: read

Required parameters: none

Optional parameters: none

Response: project object

PUT /projects/<project_id>/

Update a project.

Permission required: write

Required parameters: none

Optional body parameters:

  • name (string): name for the project
  • description (string): description, notes, etc.
  • status (string): "active" or "inactive" (an inactive project can still be viewed but will not process any new messages)
  • twitter_cap (integer): maximum number of messages this project can get from Twitter per day

Response: updated project object

DELETE /projects/<project_id>/

Delete a project.

Permission required: write

Required parameters: none

Optional parameters: none

Response: (empty)

Project Topics

A topic is for messages to be categorized into. A topic is defined by zero or more clusters. Topics are created by users.

A topic object in the API has the following fields:

  • url (string): unique URL for the topic
  • title (string): title for the topic
  • status (string): one of:
    • "active" (activated by user),
    • "inactive" (deactivated by user), or
    • "pending" (typically used for topics generated by the system and not yet activated or deactivated; pending topics are removed when the next set of clusters is generated)
  • only active and pending topics get messages categorized into them
  • blocking (boolean): whether this is a blocking topic (a topic can be marked as blocking to indicate, for example, that it is spam; messages in blocking topics are not shown in any other topics that they would otherwise appear in)
  • created (time): time at which the topic was created
  • info (JSON object): arbitrary metadata (empty by default)
  • clusters (JSON list of objects): list of clusters in the topic
  • measurements (JSON object): information about rates of incoming messages (see the statistics section for details)
  • messages_url (string): URL for the messages in the topic

POST /projects/<project_id>/p/topics/

Create a new topic.

Permission required: write

Required body parameters:

  • title (string): title for the topic
  • info (JSON-formatted string): terms that define the topic, in the following form:
       "info": {
          "terms": {
             "first term" : 1.0,
             "second": 0.9,
          }
       }
    The key in each entry of the terms dictionary is a word or phrase that defines the topic; the value is a floating-point number between 0 and 1 (inclusive) that indicates the weight of the word or phrase in the definition.
  • status (string): "active", "inactive", or "pending" (default "active")

Optional body parameters:

  • blocking (boolean): whether this is a blocking topic (default false)

Response: new topic object

GET /projects/<project_id>/p/topics/

Get the list of topics.

Permission required: read

Required parameters: none

Optional query parameters:

  • status (string): "active", "inactive", or "pending" (default is to include all statuses)
  • blocking (boolean): include only blocking topics or only non-blocking topics (default is to include all topics)
  • stats (boolean): include volume and sentiment statistics for each topic. If this parameter is "true", you can further configure the time_buckets with these parameters:
    • interval (number): number of seconds in each bucket (default is 300 (5 minutes))
    • num_buckets (integer): number of buckets to report information for (default is 120)
    • at_time (time): end of period to report information for (default is the current time)

Response: paginated list of topic objects

GET /projects/<project_id>/p/topics/<id>/

Get a topic.

Permission required: read

Required parameters: none

Optional query parameters:

  • stats (boolean): include volume and sentiment statistics for each topic. If this parameter is "true", you can further configure the time_buckets with these parameters:
    • interval (number): number of seconds in each bucket (default is 300 (5 minutes))
    • num_buckets (integer): number of buckets to report information for (default is 120)
    • at_time (time): end of period to report information for (default is the current time)

Response: topic object

GET /projects/<project_id>/p/topics/<id>/messages/

Get the list of messages in a topic.

Permission required: read

Required parameters: none

Optional query parameters:

  • outliers (boolean): include non-central messages (messages that are closer to this topic than any other topic but that aren't especially central to this topic)
  • any of the parameters for GET /projects/<project_id>/p/messages/

Response: paginated list of message objects

  • centrality (number): a positive or negative floating-point number that indicates how "central" the message is of the topic; negative numbers indicate "outliers"

PUT /projects/<project_id>/p/topics/<id>/

Update a topic.

Permission required: write

Required parameters: none

Optional body parameters:

  • title (string): title for the topic
  • status (string): "active" or "inactive"
  • blocking (boolean): whether this should be a blocking topic
  • info (JSON object): whatever you want

Response: updated topic object

DELETE /projects/<project_id>/p/topics/<id>/

Delete a topic.

Permission required: write

Required parameters: none

Optional parameters: none

Response: (empty)

Historical Topics

A read-only list of topics from the project's history, regardless of their status. Objects returned have the same fields as a regular topic.

GET /projects/<project_id>/p/topics_history/

Get a list of topics from the project's history. Without query parameters, all topics are returned in reverse chronological order.

Permission required: read

Required parameters: none

Optional query parameters:

Four query parameters are available In addition to the query parameters for regular topics. They all take
a timestamp argument in ISO 8601 format -- YYYY-MM- DD(THH:mm:ss)*. All times are UTC.

  • earliest_created (time): topics that were created on or after this time
  • latest_created (time): topics that were created on or before this time
  • earliest_ended (time): topics that became inactive on or after this time
  • latest_ended (time): topics that became inactive on or before this time

Response: paginated list of topic objects

Project Messages

A message is a single unit of text, along with some associated data. Messages can be added by users, or automatically added by an integrated data source (currently, this means the Gnip Twitter listener).

A message object in the API has the following fields:

  • url (string): unique URL for the message
  • text (string): text of the message
  • language (string): code for language that the message is in (all messages within a project must be the same language)
  • platform (string): where the message came from (e.g. "twitter", "email", etc.)
  • source_id (string): ID of the message on the original platform
  • timestamp (time): time at which the message was written
  • blocked (boolean): whether this message belongs to any blocked topic
  • is_spam (boolean): whether the system classified the message as spam (spam messages are by default excluded from the message list)
  • weight (number):
  • info (JSON object): arbitrary metadata; for Twitter messages, this contains information from the original source
  • sentiment (number): a confidence measure (positive or negative) indicative of the sentiment expressed by the message

POST /projects/<project_id>/p/messages/

Add a message or multiple messages. To add multiple messages at a time, specify a list of JSON objects instead of a single JSON object (adding multiple messages at a time is probably not possible when using HTML forms instead of JSON).

Permission required: write

Required body parameters (on each message):

  • text (string): the text of the message
  • timestamp (time): time at which the message was written
  • platform (string): where the message came from (e.g. "twitter", "email", etc.)

Optional body parameters (on each message):

  • source_id (string): ID of the message on the original platform
  • language (string): code for language that the message is in
  • info (JSON object): other information to include with the message (this is for reference only, not searchable or analyzed)

Optional query parameters:

  • replace (boolean): the messages added in this request will replace all other messages that match the other query parameters
  • any of the query parameters allowed for GET /projects/<project_id>/p/messages/: specify which existing messages to replace

Response: message object or list of message objects

GET /projects/<project_id>/p/messages/

Get the list of messages. By default, this excludes messages that have been marked as spam and messages that have not yet been marked as spam or not.

Permission required: read

Required parameters: none

Optional query parameters:

  • platform (string): only include messages from this platform
  • earliest (time): only include messages whose timestamp is this time or later
  • latest (time): only include messages whose timestamp is this time or earlier
  • older_than_id (number): only include messages older than the specified ID (i.e., with a lower ID, added to the system longer ago)
  • newer_than_id (number): only include messages newer than the specified ID (i.e., with a higher ID, added to the system more recently)
  • spam (boolean): include spam messages and messages that have not yet been marked as spam or not

Response: paginated list of message objects

GET /projects/<project_id>/p/messages/<id>/

Get a message.

Permission required: read

Required parameters: none

Optional parameters: none

Response: message object

DELETE /projects/<project_id>/p/messages/<id>/

Delete a message.

Permission required: write

Required parameters: none

Optional parameters: none

Response: (empty)

Project Partitions

A partition divides the space of messages into a set of mutually exclusive clusters. This means that for each partition, any given message falls into exactly one cluster from that partition. Partitions are periodically generated automatically by the system, and users can also request that a new partition be generated.

A partition object in the API has the following fields:

  • url (string): unique URL for the partition
  • assoc_time (time or null): time at which the association space that the partition was built on was created
  • created (time): time at which the partition was created
  • definition (JSON list of strings): list of cluster center vectors, in pack64 format
  • clusters (JSON list of objects): list of clusters in the partition

GET /projects/<project_id>/p/partitions/

Get the list of partitions.

Permission required: read

Required parameters: none

Optional query parameters:

  • earliest (time): only include partitions created at this time or later
  • latest (time): only include partitions created at this time or earlier

Response: paginated list of partitions

POST /projects/<project_id>/p/partitions/

Request that a new partition be made. [This is not implemented yet.]

Permission required: write

Required parameters: none

Optional parameters: none

Response: new partition object

GET /projects/<project_id>/p/partitions/<id>/

Get a partition.

Permission required: read

Required parameters: none

Optional parameters: none

Response: partition object

Project Clusters

A cluster is a set of criteria that can be applied to a message, such that any message can be classified as either in or not in that cluster. Every cluster belongs to exactly one partition. A cluster can also belong to a topic (but not more than one topic).

A cluster object in the API has the following fields:

  • url (string): unique URL for the cluster
  • partition (string): URL for the partition that the cluster belongs to
  • index (integer): which vector this cluster corresponds to from its partition's definition
  • topic (string or null): URL for the topic that the partition belongs to, if any
  • time_buckets (JSON object): information about number of messages in this cluster per time interval (see the statistics section for details)

GET /projects/<project_id>/p/clusters/<id>/

Get a cluster.

Permission required: read

Required parameters: none

Optional parameters: none

Response: cluster object

PUT /projects/<project_id>/p/clusters/<id>/

Update a cluster.

Permission required: write

Required parameters: none

Optional body parameters:

  • topic (string): ID of the topic that this cluster should belong to

Response: updated cluster object

Project Keywords

Currently, a keyword is a word or phrase used for retrieving relevant messages from Twitter (in the future, keywords might be used in other ways or for other data sources). There are two types of keywords: seed keywords are added (and removed) by users, and generated keywords are automatically generated (and removed) by the system based on the seed keywords and the Twitter messages found. Keywords can also be either positive or negative: messages containing positive keywords are considered relevant and the system will try to find more messages like them, whereas messages containing negative keywords are considered irrelevant and the system will try to avoid finding messages like them.

A project cannot have negative seeds without positive seeds. A multi-word phrase for a seed must be specified within quotation marks.

A keyword object in the API has the following fields:

  • url (string): unique URL for the keyword
  • keyword (string): the text of the keyword
  • language (string): code for the language that the keyword is in
  • role (string): "positive" or "negative"
  • source (string): "seed" or "generated"
  • priority (number): how important this keyword is (this is automatically computed by the system based on the messages it has seen; priority of generated keywords is between 0 and 1 (inclusive), and priority of seed keywords is between 1 and 2 (inclusive), except for negative keywords, which always have priority 0)

POST /projects/<project_id>/p/listener/keywords/

Add a keyword or multiple keywords. To add multiple keywords at a time, specify a list of JSON objects instead of a single JSON object (adding multiple keywords at a time is probably not possible when using HTML forms instead of JSON).  Note that negative keywords cannot be posted if the project does not have at least one positive keyword.

Permission required: write

Required body parameters:

  • keyword (string): the text of the keyword

Optional body parameters:

  • role (string): "positive" or "negative"

Optional query parameters:

  • replace (boolean): the keywords added in this request will replace all other keywords that match the other query parameters; do not mix positive and negative keywords in the same request 
  • any of the query parameters allowed for GET /projects/<project_id>/p/listener/keywords/: specify which existing keywords to replace

Response: new keyword object

GET /projects/<project_id>/p/listener/keywords/

Get the list of keywords.

Permission required: read

Required parameters: none

Optional query parameters:

  • role (string): "positive" or "negative"
  • source (string): "seed" or "generated"

Response: paginated list of keyword objects

DELETE /projects/<project_id>/p/listener/keywords/<id>/

Delete a keyword. (Only seed keywords can be deleted.)

Permission required: write

Required parameters: none

Optional parameters: none

Response: (empty)

Project Statistics

GET /projects/<project_id>/p/stats/

Get statistics about the number of messages in the project.

Permission required: read

Required parameters: none

Optional query parameters:

  • interval (number): number of seconds in each bucket (default is 300 (5 minutes))
  • num_buckets (integer): number of buckets to report information for (default is 120)
  • at_time (time): end of period to report information for (default is the current time)

Response: JSON object with two keys:

  • measurements
    • count (integer): total number of messages
    • velocity (number): rate of incoming messages (messages per hour)
    • acceleration (number): rate of velocity change (messages per hour per hour)
  • time_buckets
    • start_time (time): beginning of period for which buckets are being reported (default is 10 hours ago)
    • end_time (time): end of period for which buckets are being reported
    • interval (integer): number of seconds that each bucket represents
    • counts (JSON list of numbers): number of messages in each bucket, from earliest to latest
    • sentiment_counts (JSON list of JSON dictionaries, each with three key/value pairs: the total weight of negative, neutral, and positive messages received in each bucket, from earliest to latest
If the number of buckets requested is greater than the number of buckets that exist, some of the buckets will be null.

Project Message Usage

Message usage objects keep track of the number of messages used by the project from a particular source (currently, the two possible sources are Gnip and this API). Note that this message count might be higher than the number of messages actually in the project, because some messages might be filtered out as uninteresting.

A message usage object in the API has the following fields:

  • url (string): URL for the message usage object
  • source (string): "gnip" or "api"
  • start_time (time): start time of the day that this object counts messages for (days start and end at noon, including the start point and not the end point)
  • count (integer): number of messages recorded

GET /projects/<project_id>/p/usage/

Get the list of message usage objects.

Permission required: read

Required parameters: none

Optional query parameters:

  • source (string): only show message usage for this source
  • earliest (time): only show information from this time or later
  • latest (time): only show information from this time or earlier

Response: list of JSON objects, one per month, each with four keys:

  • start_time (time) - start time of the month (noon on the first day of the month)
  • month_name (string) - English name of the month
  • total_counts (JSON object) - keys are source types and values are message counts
  • days (list of JSON objects) - list of message usage objects for the individual days and source types in the month

GET /projects/<project_id>/p/usage/<id>/

Get message usage information for a particular source and day.

Permission required: read

Required parameters: none

Optional parameters: none

Response: message usage object

Project Configuration

A configuration is a user-modifiable aspect of a project's settings - for example, the number of clusters to make in each partition. Usually the defaults are good and you will not need to change them.

A configuration object in the API has the following fields:

  • key (string): the name of the configuration
  • value (JSON object): the information stored for the configuration

The current configurable options are:

  • assoc_axes - number of dimensions in the vectors that are used to represent terms and messages
  • assoc_min_tokens - minimum number of tokens (word instances) required to build a new assoc space
  • assoc_max_tokens - maximum number of tokens (word instances) used to build a new assoc space
  • assoc_min_messages - minimum number of messages required to build a new assoc space
  • partition_min_messages - minimum number of messages required to build a new partition
  • partition_max_messages - minimum number of messages used to build a new partition
  • number_of_clusters - number of clusters to keep per partition
  • number_of_discardable_clusters - number of clusters (topics) from the current partition that will be replaced by new topics when the next partition is built
  • partition_min_lifetime - any partitions created more than this many seconds ago will be automatically periodically deleted unless they contain any active topics
  • assoc_do_not_build_within - do not build a new assoc space within this many seconds of having built one
  • assoc_force_build_after - if it has been more than this many seconds since the last assoc space was built, make a new one even if there aren't enough messages/tokens
  • partition_do_not_build_within - do not build a new partition within this many seconds of having built one
  • partition_force_build_after - if it has been more than this many seconds since the last partition was built, make a new one even if there aren't enough messages
  • sentiment_threshold  - a floating point number between 0 and 1; values greater than it are considered to express "positive" sentiment, values less than its negative to its counterpart are considered to express "negative" sentiment, values in between are considered "neutral"
  • max_generated_keywords - the maximum number of keywords that will be generated in addition to the seed keywords, based on their relevance to the current conversation (default value: 20); set this to 0 if you want to capture messages that contain user-defined keywords only
  • pause_keyword_generation - by default, Compass generates additional keywords from the messages it receives; set this parameter to "True" to stop generating new keywords; keywords that were generated prior to the change will still be used to match new tweets

GET /projects/<project_id>/p/config/

Get all of the configuration keys and values.

Permission required: read

Required parameters: none

Optional parameters: none

Response: JSON object with two keys:

  • default (JSON list of objects): list of configuration objects with their default values (including ones whose values in this project are overridden to something else)
  • overridden (JSON list of objects): list of configuration objects whose values have been set by a user

GET /projects/<project_id>/p/config/<key>/

Get a configuration value.

Permission required: read

Required parameters: none

Optional parameters: none

Response: configuration object

PUT /projects/<project_id>/p/config/<key>/

Update a configuration value.

Permission required: write

Required body parameters:

  • value (JSON object or list or number): value to store for this configuration key

Optional parameters: none

Response: updated configuration object

DELETE /projects/<project_id>/p/config/<key>/

Unset a key in the project configuration. This will restore its default value.

Permission required: write

Required parameters: none

Optional parameters: none

Response: (empty)

Accounts

An account is a billable entity and has certain account-wide settings (it doesn't actually have any yet).

An account object in the API has the following fields:

  • url (string): account URL (contains the unique ID)
  • id (string): unique randomly-generated ID for the account
  • name (string): name for the account (not necessarily unique)

GET /accounts/

Get the list of accounts. If you are a site admin, this will include all accounts; otherwise, it will only include accounts that you have permission on.

Permission required: none

Required parameters: none

Optional parameters: none

Response: paginated list of account objects

POST /accounts/

Create a new account.

Permission required: site admin

Required body parameters:

  • name (string): a name for the account

Optional parameters: none

Response: new account object

GET /accounts/<account_id>/

Get an account.

Permission required: read (in the future this might change to manage, if accounts store information other than name)

Required parameters: none

Optional parameters: none

Response: account object

PUT /accounts/<account_id>/

Update an account.

Permission required: manage

Required parameters: none

Optional body parameters:

  • name (string): name for the account

Response: updated account object

DELETE /accounts/<account_id>/

Delete an account.

Permission required: manage

Required parameters: none

Optional parameters: none

Response: (empty)

Users

A user represents one person using the system.

A user object in the API has the following fields:

  • url (string): URL for the user (contains the email address)
  • email (string): email address (this is the equivalent of a username)
  • name (string): full name
  • default_account (string or null): ID of the user's default account
  • must_reset_password (boolean): whether the user is currently required to change his password before doing anything else
  • admin (boolean): whether the user is a site admin
  • permissions (JSON list of objects): list of permissions the user has

GET /users/

Get the list of users. If you are a site admin, this will include all users, otherwise it will include yourself and any users who have permission on any account that you have manage permission on.

Permission required: none

Required parameters: none

Optional parameters: none

Response: paginated list of user objects

POST /users/

Create a user.

Permission required: site admin

Required body parameters:

  • name (string): full name of the person
  • email (string): email address

Optional body parameters:

  • default_account (string) (default null): ID of account that should be user's default
  • admin (boolean) (default false): whether the user should be a site admin

Response: new user object

GET /users/<email>/

Get a user.

Permission required: you must be this user OR you must have manage permission on some account that this user has permission on

Required parameters: none

Optional parameters: none

Response: user object

PUT /users/<email>/

Update a user.

Permission required: you must be this user

Required parameters: none

Optional body parameters:

  • name (string): full name of the person
  • email (string): email address
  • default_account (string): ID of account that should be user's default

Optional body parameters for site admin only:

  • admin (boolean): whether this user should be a site admin

Response: updated user object

DELETE /users/<email>/

Delete a user.

Permission required: site admin

Required parameters: none

Optional parameters: none

Response: (empty)

PUT /users/<email>/password/

Change a user's password. This also resets his API token.

Permission required: you must be this user

Required body parameters:

  • password (string): new password
  • old_password (string): old password

Optional parameters: none

Response: JSON object with three keys:

  • token (string): the user's new token string
  • user (JSON object): user object
  • expiration (time): the time at which the new token will expire

POST /users/<email>/password/reset/

Reset a user's password to a temporary password. This also deletes his API token. When the user next logs in, he will not be permitted to do (most) things until he changes his password to something else.

Permission required: site admin

Required parameters: none

Optional parameters: none

Response: JSON object with one key:

  • password (string): the user's temporary password

Permissions

Permissions allow users to do certain things to certain accounts. A user can have at most one permission on each account.

A permission object in the API has the following fields:

  • url (string): URL for the permission
  • user (string): email address of the user who has the permission
  • account (string): ID of the account that the user has permission on
  • level (string): the permission level that the user has on the account ("read", "readwrite", or "manage" - for descriptions of the levels, refer to the API Guide)

GET /permissions/

Get the list of permissions on accounts that you have manage permission on.

Permission required: manage

Required parameters: none

Optional query parameters:

  • user (string): user (email address) to list permissions for
  • level (string): only include permissions with this level ("read", "readwrite", or "manage")

Response: paginated list of permission objects

POST /permissions/

Give a user permission on an account.

Permission required: manage

Required body parameters:

  • user (string): user (email address) to give permission on the acount
  • account (string): ID of account to give the user permission on
  • level (string): what permission to give the user on the account

Response: new permission object

GET /permissions/<permission_id>/

Get a permission object.

Permission required: manage OR you must be this user

Required parameters: none

Optional parameters: none

Response: permission object

DELETE /permissions/<permission_id>/

Remove a permission.

Permission required: manage

Required parameters: none

Optional parameters: none

Response: (empty)

Tokens

A token authenticates a particular user to the API. Currently, each user has at most one token at a time.

A token object in the API has the following fields:

  • token (string): the token string itself, to be included in authorization header on HTTP requests
  • user (string): the username of the user whose token this is
  • expiration (time): the time at which the token will expire

POST /login/

Log in with a username and password to get a token.

Permission required: none

Required body parameters:
  • username (string)
  • password (string)

Optional parameters: none

Response: JSON object with three keys:

  • token (string): the user's token string
  • user (JSON object): user object
  • expiration (time): the time at which the token will expire

GET /tokens/

Get a list of tokens. This will only include your tokens, unless you are a site admin.

Permission required: none

Required parameters: none

Optional query parameters:

  • user (string): user (email address) to list tokens for

Response: paginated list of token objects

GET /tokens/<token>/

Get an existing token.

Permission required: you must be the user who owns the token

Required parameters: none

Optional parameters: none

Response: token object

DELETE /tokens/<token>/

Delete a token.

Permission required: you must be the user who owns the token

Required parameters: none

Optional parameters: none

Response: (empty)

More Support

6560c840000970c2e652c21ccafb3167@luminoso.desk-mail.com
http://assets2.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete