Skip to content
Foliosodev
Sign in Get started
Menu
On this page

REST API

Spaces, groups and tags

Read the spaces you can reach, and the groups and tags inside them, so you know where to file pages and how to filter them. These endpoints are read-only and need the read ability.

All three return every result at once, without pagination, wrapped in data. Spaces and groups are created and changed in the app. Tags are too, and the API also creates a tag when you name one a space doesn't have yet on a page. See Tags.

List spaces

http
GET /spaces

Returns the spaces you can open in the organisation, sorted by name. That includes open spaces, closed and private spaces you've been given a role in, and your own personal space. Spaces you can't open aren't listed.

bash
curl https://acme.folioso.dev/api/v1/spaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
json
{
  "data": [
    {
      "slug": "engineering",
      "name": "Engineering",
      "accessType": "closed",
      "isPersonal": false,
      "isDefault": false
    },
    {
      "slug": "general",
      "name": "General",
      "accessType": "open",
      "isPersonal": false,
      "isDefault": true
    },
    {
      "slug": "personal-42",
      "name": "My space",
      "accessType": "private",
      "isPersonal": true,
      "isDefault": false
    }
  ]
}
Field Type Description
slug string The space's identifier. Use it as space when creating pages and filtering lists.
name string The space's name.
accessType string open, closed or private. See Spaces.
isPersonal boolean true for your personal space ("My space").
isDefault boolean true for the organisation's default space.

List groups

http
GET /groups

Returns the groups in the spaces you can open, in the order they appear in the sidebar.

Parameter Description
space Only groups in the space with this slug. An unknown slug gives an empty list.
bash
curl "https://acme.folioso.dev/api/v1/groups?space=engineering" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
json
{
  "data": [
    {
      "id": 12,
      "name": "Runbooks",
      "description": "How we operate production.",
      "colour": "#3b82f6",
      "space": "engineering"
    },
    {
      "id": 14,
      "name": "Architecture",
      "description": null,
      "colour": null,
      "space": "engineering"
    }
  ]
}
Field Type Description
id integer The group's identifier. Use it as group_id when creating a page and as group when filtering pages.
name string The group's name.
description string or null The group's description.
colour string or null The group's colour.
space string The slug of the space the group belongs to.

See Groups.

List tags

http
GET /tags

Returns the tags in the spaces you can open, sorted by name. Tags belong to a space, so two spaces can each have a tag with the same name; they're different tags with different ids.

Parameter Description
space Only tags in the space with this slug. An unknown slug gives an empty list.
bash
curl "https://acme.folioso.dev/api/v1/tags?space=engineering" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
json
{
  "data": [
    {
      "id": 31,
      "name": "php",
      "colour": "#777bb3",
      "isDefault": true
    },
    {
      "id": 40,
      "name": "release",
      "colour": "#22c55e",
      "isDefault": false
    }
  ]
}
Field Type Description
id integer The tag's identifier. Use it as tag when filtering pages.
name string The tag's name.
colour string or null The tag's colour.
isDefault boolean true for the language tags every space starts with.

To set a page's tags, send their names as tags when you create or update it. Names a space doesn't have yet are created there. See Tags. Renaming, recolouring and deleting tags is done in the app. See Tags.

Putting it together

To file a new page in a group with tags, look up the space and group first, then create the page:

bash
curl "https://acme.folioso.dev/api/v1/groups?space=engineering" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

curl https://acme.folioso.dev/api/v1/pages \
  -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Restart the queue workers", "space": "engineering", "group_id": 12, "tags": ["runbook"] }'

To list every page with a tag, use its id:

bash
curl "https://acme.folioso.dev/api/v1/pages?tag=40" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

See Pages.