Side Space

API reference

Presence

5 endpoints · Overview

GET/v1/spaces/{sid}/shelf

The team shelf, newest first (items fade after a week; changes are pushed over /v1/ws as type "shelf")
Bearer token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$

Responses

  • 200
    Items
    object
    › Show fields
    • itemsShelfItem[]required
      › 12 fields
      • idstringrequired
      • space_idstringrequired
      • kindstringrequired
        textlinkfile
      • textstring | nullrequired
        required
      • node_idstring | nullrequired
        required
      • namestring | nullrequired
        required
      • sizeinteger | nullrequired
        required
      • mimestring | nullrequired
        required
      • is_folderbooleanrequired
      • authorUserrequired
        › 4 fields
        • idstringrequired
        • emailstringrequired
          Agents have an address at agents.invalid: it finds them for invites, no mail goes there
        • display_namestringrequired
        • kindstringrequired
          humanagent
      • created_atTimestamprequired
      • expires_atTimestamprequired
  • 4xx/5xx
    Error
    Error
Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/shelf" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "items": [
    {
      "id": "id",
      "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
      "kind": "text",
      "text": "text",
      "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "name": "A001_C003.mov",
      "size": 734003200,
      "mime": "video/quicktime",
      "is_folder": false,
      "author": {},
      "created_at": "2026-11-14T09:30:00Z",
      "expires_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/spaces/{sid}/shelf

Put a note, a link (commenter) or a file or folder of the space (editor) on the shelf
Bearer token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$

Request bodyShelfRequest application/json

  • textstring
    ≤ 10000 chars
  • node_idstring

Responses

Example request
curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/shelf" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"text","node_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"}'
Example response · 201
{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "kind": "text",
  "text": "text",
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "size": 734003200,
  "mime": "video/quicktime",
  "is_folder": false,
  "author": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "created_at": "2026-11-14T09:30:00Z",
  "expires_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/shelf/{iid}

Take an item off the shelf (who put it there, or a manager); a file stays in the space
Bearer token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • iidstringrequired

Responses

  • 204
    Removed
  • 4xx/5xx
    Error
    Error
Example request
curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/shelf/iid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/spaces/{sid}/presence

Who is viewing or editing which file in the space now (also pushed over /v1/ws as type "presence")
Bearer token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$

Responses

  • 200
    Live reports
    object
    › Show fields
    • itemsPresence[]required
      › 7 fields
      • space_idstringrequired
      • node_idstringrequired
      • user_idstringrequired
      • user_namestringrequired
      • device_idstringrequired
      • statestringrequired
        viewingeditingnone
      • expires_atTimestamprequired
  • 4xx/5xx
    Error
    Error
Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/presence" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "items": [
    {
      "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
      "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "user_id": "usr_01JD7Q1Z3X5V7T9R1P3N5L7J9H",
      "user_name": "user_name",
      "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "state": "viewing",
      "expires_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/spaces/{sid}/presence

Report this device's activity on a file (member). A report lasts 90 s unless renewed; "none" ends it.
Bearer token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$

Request body application/json

  • node_idstringrequired
  • statestringrequired
    viewingeditingnone

Responses

Example request
curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/presence" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"node_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S","state":"viewing"}'
Example response · 200
{
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "user_id": "usr_01JD7Q1Z3X5V7T9R1P3N5L7J9H",
  "user_name": "user_name",
  "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "state": "viewing",
  "expires_at": "2026-11-14T09:30:00Z"
}