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

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 space

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 spaces

To return a list representing all Collections in a Workspace, send a GET request to the spaces resource.

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. Learn more about levels of permission in Mode.

URL Params

workspace

required
string Workspace username
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 space

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

space_type

required
string The type of the space, the only option is custom

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 space

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

space_type

required
string The type of the space, the only option is custom

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 space

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);
});