Management

Collections

A Collection is a place for Mode users to gather reports related to a team, project, or common theme. A Workspace may have different types of Collections depending on their Mode plan. Learn more about Collections here.

Spaces have been rebranded as Collections in Mode, but the API will continue to refer to spaces. The spaces object and resources are the same as Collections in the Mode UI.

You can use the spaces resource to manage and retrieve information about one or all Collections in a given Workspace.

Collection object

Properties
token required	string
id required	integer
space_type required	string
name required	string
description required	string
state required	string
restricted required	boolean
free_default required	string
viewable? required	string
viewed?	string
default_access_level	string
_links required	object

Links

All resource responses contain a set of links that describe other related resources or actions that you can take on this resource. A link is comprised of two main pieces: its name (which describes its relationship to this resource) and its href (the URL of the related action or resource). All resources have at least a _self link which is the URL that will return a representation of this resource.

creator
detail
preview_space_memberships
reports
search_space_permissions
self
space_memberships
space_report_pins
user_space_membership
viewed
web

{
  "token": "f3gtgvfbghnm",
  "id": 45917678,
  "space_type": "custom",
  "name": "Cool custom space",
  "description": "dolore officia incididunt reprehenderit",
  "state": "active",
  "restricted": true,
  "free_default": true,
  "_links": {
    "self": {
      "href": "api/{workspace}/spaces/f3gtgvfbghnm",
      "templated": false
    },
    "detail": {
      "href": "api/{workspace}/spaces/f3gtgvfbghnm/detail",
      "templated": false
    },
    "reports": {
      "href": "api/{workspace}/spaces/f3gtgvfbghnm/reports",
      "templated": false
    },
    "creator": {
      "href": "api/{username}",
      "templated": false
    },
    "space_report_pins": {
      "href": "/api/{workspace}/spaces/f3gtgvfbghnm/report_pins",
      "templated": false
    },
    "web": {
      "href": "/{workspace}/spaces/f3gtgvfbghnm",
      "templated": false
    },
    "user_space_membership": {
      "href": "/api/{workspace}/spaces/f3gtgvfbghnm/memberships/{membership_token}",
      "templated": false
    },
    "space_memberships": {
      "href": "/api/{workspace}/spaces/f3gtgvfbghnm/memberships",
      "templated": false
    },
    "preview_space_memberships": {
      "href": "/api/{workspace}/spaces/f3gtgvfbghnm/memberships/preview",
      "templated": false
    }
  },
  "_embedded": {}
}

Get a Collection

To retrieve information about a given Collection, send a GET request to the spaces resource along with a space_token.

Please note that you must have permission to view reports in the Collection in question to receive a response. Learn more about levels of permission in Mode.

URL Params
workspace required	string	`Workspace` username
space required	string	`Space` token

Responses
200	Space response
401	Unauthorized
404	Space not found

GET /{workspace}/spaces/{space}

curl --include \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{workspace}/spaces/{space}'

require 'http'

username = 'your_api_key'
password = 'your_api_secret'

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .get('https://app.mode.com/api/{workspace}/spaces/{space}')
puts response

from urllib2 import Request, urlopen

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

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

var request = require('request');

request({
  method: 'GET',
  url: 'https://app.mode.com/api/{workspace}/spaces/{space}',
  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);
});

List Collections

To return a list representing all Collections in a Workspace, send a GET request to the spaces resource that includes the query param ?filter=all. To get all non-personal collections, user the query param ?filter=custom.

Admins can get a list of all personal collections by using the following query param: ?filter=all.

If the page or per_page parameters are provided in the request, the response will be paginated and will include include a "pagination" section detailing information like current page, total pages, etc.

Please note that this list will only include Collections that are visible to you as the authorizing user, according to your level of permission in Mode. Admin users will get all Collections, including restricted and personal Collections. Learn more about levels of permission in Mode.

URL Params
workspace required	string	`Workspace` username
page	integer	Page of results
per_page	integer	Results per page

Query Params
filter	string	Returns a filtered list of `Collection`s. Valid options include `all`. The default returns a list of `Collection`'s that do not include other user's personal collections. Example: `?filter=all` returns all `Collections` including personal collections.

Responses
200	Space collection response
401	Unauthorized
404	Workspace not found

GET /{workspace}/spaces

curl --include \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{workspace}/spaces'

require 'http'

username = 'your_api_key'
password = 'your_api_secret'

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .get('https://app.mode.com/api/{workspace}/spaces')
puts response

from urllib2 import Request, urlopen

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

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

var request = require('request');

request({
  method: 'GET',
  url: 'https://app.mode.com/api/{workspace}/spaces',
  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);
});

Create a Collection

To create a new Collection, send a POST request to the spaces resource.

URL Params
workspace required	string	`Workspace` username

POST Body Params Object: `space`
description	string	Description of the `space`
name required	string	Name of the `space`

Responses
200	Space response
400	Bad request
401	Unauthorized
403	Forbidden
404	Account not found

POST /{workspace}/spaces

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
     --data-binary "{
  \"space\": {
    \"space_type\": \"Excepteur dolor officia ex\",
    \"name\": \"irure eiusmod labore\",
    \"description\": \"est reprehenderit ad ullamco\"
  }
}" \
'https://app.mode.com/api/{workspace}/spaces'

require 'http'

values = {
  space: {
    space_type: 'Excepteur dolor officia ex',
    name: 'irure eiusmod labore',
    description: 'est reprehenderit ad ullamco'
  }
}

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .post('https://app.mode.com/api/{workspace}/spaces', json: values)
puts response

from urllib2 import Request, urlopen

values = """
  {
    "space": {
      "space_type": "Excepteur dolor officia ex",
      "name": "irure eiusmod labore",
      "description": "est reprehenderit ad ullamco"
    }
  }
"""

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

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

var request = require('request');

request({
  method: 'POST',
  url: 'https://app.mode.com/api/{workspace}/spaces',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/hal+json'
  },
  body: "{  \"space\": {    \"space_type\": \"Excepteur dolor officia ex\",    \"name\": \"irure eiusmod labore\",    \"description\": \"est reprehenderit ad ullamco\"  }}"
}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

Update a Collection

To update a Collection, send a POST request to the spaces resource, specifying the space token.

Please note that you must have permission to view and edit reports in the Collection in question to receive a successful response. Learn more about levels of permission in Mode.

URL Params
workspace required	string	`Workspace` username
space required	string	`Space` token

POST Body Params Object: `space`
description	string	Description of the `space`
name required	string	Name of the `space`

Responses
200	Space response
400	Bad request
401	Unauthorized
403	Forbidden
404	Space not found

POST /{workspace}/spaces/{space}

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
     --data-binary "{
  \"space\": {
    \"space_type\": \"deserunt do\",
    \"name\": \"laborum qu\",
    \"description\": \"laboris null\"
  }
}" \
'https://app.mode.com/api/{workspace}/spaces/{space}'

require 'http'

values = {
  space: {
    space_type: 'deserunt do',
    name: 'laborum qu',
    description: 'laboris null'
  }
}

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .post('https://app.mode.com/api/{workspace}/spaces/{space}', json: values)
puts response

from urllib2 import Request, urlopen

values = """
  {
    "space": {
      "space_type": "deserunt do",
      "name": "laborum qu",
      "description": "laboris null"
    }
  }
"""

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

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

var request = require('request');

request({
  method: 'POST',
  url: 'https://app.mode.com/api/{workspace}/spaces/{space}',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/hal+json'
  },
  body: "{  \"space\": {    \"space_type\": \"deserunt do\",    \"name\": \"laborum qu\",    \"description\": \"laboris null\"  }}"
}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

Delete a Collection

To remove a Collection from a Workspace, send a DELETE request to the spaces resource, specifying the space_token.

Please note that in order to remove a Collection from a Workspace, all the reports (including archived ones) in that Collection must be removed first.

URL Params
workspace required	string	`Workspace` username
space required	string	`Space` token

Responses
200	Space response
401	Unauthorized
404	Space not found

DELETE /{workspace}/spaces/{space}

curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{workspace}/spaces/{space}'

require 'http'

username = 'your_api_key'
password = 'your_api_secret'

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .delete('https://app.mode.com/api/{workspace}/spaces/{space}')
puts response

from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{workspace}/spaces/{space}', headers=headers)
request.get_method = lambda: 'DELETE'

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

var request = require('request');

request({
  method: 'DELETE',
  url: 'https://app.mode.com/api/{workspace}/spaces/{space}',
  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);
});