API Reference

Introduction

Mode is a collaborative analytics platform that lets teams work together to solve problems and make better decisions with data.

Mode’s Application Programming Interface (API) powers its analytics platform. You can use the Mode API to programmatically retrieve information from Mode and interact with its rich array of analytics functions. These include writing queries, building, sharing, or distributing reports, and managing members, workspaces, and data.

New to APIs? Start here

APIs are interfaces that allow other applications to interact with and access a system’s features, functionalities, and data in a systematic manner. Mode’s API is organized on REST (Representational State Transfer) principles. REST is an architectural style that describes how distributed software systems can expose consistent interfaces to their resources. Mode’s REST API endpoints are resource-centric and use HTTP protocol to access and act upon them.

Getting started with the Mode API

Note: To access to Mode’s API, you must be a member of a Mode Business Workspace. Only resources within a Mode Business Workspace are accessible via the API.

The Mode API supports common HTTP verbs:

GET: Retrieve the representation of a single resource or a list of resources
POST: Create an instance of a resource
PATCH: Update a resource with attributes provided in the request
DELETE: Delete an instance of a resource

You can access the Mode API at: app.mode.com/api. You must use basic authentication to access the Mode API. To get started, follow these steps:

1. Set up your Mode account

Create a Mode account
Create a Workspace
Connect a database or use public data

2. Get an access token

Obtain an API access token
Learn more about authentication

3. Test it out

Send a test request to an API endpoint
Learn more about Mode resources by browsing the API reference side navigation to the left
Browse our API Cookbook to learn how to automate Mode workflows

Example — simple request example

Here’s how you can make a very simple request from Mode’s API. It doesn’t require any authentication, so you can try it out before creating an API token.

Choose a language from the tabs above, then run the code snippet below. This will make a GET request to retrieve the Workspace object for a fictional company called Parch and Posey.

curl https://app.mode.com/api/parch_and_posey

# gem install http
require 'http'

puts HTTP.get('https://app.mode.com/api/parch_and_posey').to_s

from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/parch_and_posey', headers=headers)

response_body = urlopen(request).read()
print(response_body)

var request = require('request');

request({
  method: 'GET',
  url: 'https://app.mode.com/api/parch_and_posey',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/hal+json'
  }}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

The JSON response will look like this. You can make the same request with your username or Workspace name. The response will be structured the same, with different values. Organizations have been rebranded as Workspaces in Mode. All references to organizations in the API map to Workspaces in the Mode UI.

{
  "username": "parch_and_posey",
  "name": "parch and posey",
  "id": 245835,
  "token": "9aab7b244909",
  "avatar": {
    "initials": "PP",
    "seed": "9aab7b244909",
    "color_class": "mode-avatar-color-10",
    "type": "initials"
  },
  "user": false,
  "_links": {
    "self": { "href": "/api/parch_and_posey" },
    "web": { "href": "/parch_and_posey" },
    "web_public_datasource_home": { "href": "/home/parch_and_posey/data_sources/0a671f65888c" },
    "web_spaces": { "href": "/parch_and_posey/spaces" },
    "web_groups": { "href": "/organizations/parch_and_posey/groups" },
    "web_new_organization": { "href": "/organizations/new" },
    "data_sources": { "href": "/api/parch_and_posey/data_sources" },
    "data_source": { "templated": true, "href": "/api/parch_and_posey/data_sources{/id}" },
    "home_web": { "href": "/home/parch_and_posey" },
    "home_starred_web": { "href": "/home/parch_and_posey/starred" },
    "home_reports_web": { "href": "/home/parch_and_posey/reports" },
    "home_search_web": { "href": "/home/parch_and_posey/search" },
    "home_discover_web": { "href": "/home/parch_and_posey/discover" },
    "select_data_sources_web": { "href": "/parch_and_posey/data_sources/select" },
    "new_invite_web": { "href": "/parch_and_posey/invites/new" },
    "new_upload_web": { "href": "/parch_and_posey/uploads/new" },
    "public_data_sources": { "href": "/api/data_sources" },
    "table": { "templated": true, "href": "/api/parch_and_posey/tables{/id}" },
    "report": { "templated": true, "href": "/api/parch_and_posey/reports{/id}" },
    "reports": { "href": "/api/parch_and_posey/reports" },
    "archived_reports": { "href": "/api/parch_and_posey/reports?filter=archived" },
    "public_reports": { "href": "/api/parch_and_posey/reports?filter=public" },
    "drafts_reports": { "href": "/api/parch_and_posey/reports?filter=drafts" },
    "starred_reports": { "href": "/api/parch_and_posey/reports?filter=starred" },
    "by_ids_reports": { "templated": true, "href": "/api/parch_and_posey/reports?filter=by_ids\u0026ids={ids}" },
    "viewed_reports": { "href": "/api/parch_and_posey/reports?filter=viewed" },
    "by_tokens_definitions": { "templated": true, "href": "/api/parch_and_posey/definitions?filter=by_tokens\u0026tokens={tokens}" },
    "bridges": { "href": "/api/parch_and_posey/bridges" },
    "access_tokens": { "href": "/api/parch_and_posey/access_tokens" }
  }
}

Most of Mode’s API requires authentication, so you’ll need to follow steps above to get an API access token before doing most actions with your Workspace’s account and data.