Side Space

API 参考

orgs

Organizations: people, teams with roles in spaces, folder rules that limit or widen who may change what (never who sees it), single sign-on through OpenID Connect for proven email domains, and an audit export.

30 个接口 · 概览

POST/v1/auth/sso/start

Start signing in through the organization that owns the address's domain (OpenID Connect)
无需认证

Open url in a browser, then poll /v1/auth/sso/poll with handle. 404 when no organization signs this domain in.

请求体 application/json

  • emailstring必填
  • device_namestring
  • platformstring

响应

请求示例
curl -X POST "https://side.example.com/v1/auth/sso/start" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
响应示例 · 200
{
  "url": "https://hooks.example.com/side",
  "handle": "handle",
  "expires_at": "2026-11-14T09:30:00Z"
}

GET/v1/auth/sso/callback

Where the identity provider sends the browser back (an HTML page)
无需认证

响应

  • 200
    Signed in
    any
  • 400
    Unknown
    any
  • 403
    The provider refused
    any
请求示例
curl "https://side.example.com/v1/auth/sso/callback"

POST/v1/auth/sso/poll

Collect the tokens once the browser came back (once)
无需认证

请求体 application/json

  • handlestring必填

响应

  • 200
    Signed in
    TokenPair
  • 202
    Still waiting for the browser
  • 410
    Expired
  • 4xx/5xx
    Error
    Error
请求示例
curl -X POST "https://side.example.com/v1/auth/sso/poll" \
  -H "Content-Type: application/json" \
  -d '{"handle":"handle"}'
响应示例 · 200
{
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "expires_in": 1,
  "user": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
}

GET/v1/orgs

Your organizations
Bearer 令牌

响应

  • 200
    Organizations
    object
    › 展开字段
    • itemsOrg[]必填
      › 7 个字段
      • idstring必填
      • namestring必填
      • roleOrgRole必填
        owneradminmember
      • membersinteger必填
      • teamsinteger必填
      • spacesinteger必填
      • created_atTimestamp必填
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/orgs" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "id": "id",
      "name": "A001_C003.mov",
      "role": "owner",
      "members": 1,
      "teams": 1,
      "spaces": 1,
      "created_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/orgs

Make an organization with you as its owner (people only; tokens need admin)
Bearer 令牌

请求体 application/json

  • namestring必填

响应

请求示例
curl -X POST "https://side.example.com/v1/orgs" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov"}'
响应示例 · 201
{
  "id": "id",
  "name": "A001_C003.mov",
  "role": "owner",
  "members": 1,
  "teams": 1,
  "spaces": 1,
  "created_at": "2026-11-14T09:30:00Z"
}

GET/v1/orgs/{oid}

Bearer 令牌

参数 · 路径

  • oidstring必填

响应

请求示例
curl "https://side.example.com/v1/orgs/oid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "id": "id",
  "name": "A001_C003.mov",
  "role": "owner",
  "members": 1,
  "teams": 1,
  "spaces": 1,
  "created_at": "2026-11-14T09:30:00Z"
}

PATCH/v1/orgs/{oid}

Rename (an admin)
Bearer 令牌

参数 · 路径

  • oidstring必填

请求体 application/json

  • namestring必填

响应

请求示例
curl -X PATCH "https://side.example.com/v1/orgs/oid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov"}'
响应示例 · 200
{
  "id": "id",
  "name": "A001_C003.mov",
  "role": "owner",
  "members": 1,
  "teams": 1,
  "spaces": 1,
  "created_at": "2026-11-14T09:30:00Z"
}

GET/v1/orgs/{oid}/members

Bearer 令牌

参数 · 路径

  • oidstring必填

响应

  • 200
    People
    object
    › 展开字段
    • itemsOrgMember[]必填
      › 4 个字段
      • userUser必填
        › 4 个字段
        • idstring必填
        • emailstring必填
          Agents have an address at agents.invalid: it finds them for invites, no mail goes there
        • display_namestring必填
        • kindstring必填
          humanagent
      • roleOrgRole必填
        owneradminmember
      • teamsstring[]必填
      • sinceTimestamp必填
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/orgs/oid/members" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "user": {},
      "role": "owner",
      "teams": [],
      "since": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/orgs/{oid}/members

Add someone by email (an admin; only an owner adds owners)
Bearer 令牌

参数 · 路径

  • oidstring必填

请求体 application/json

  • emailstring必填
  • roleOrgRole
    owneradminmember

响应

请求示例
curl -X POST "https://side.example.com/v1/orgs/oid/members" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
响应示例 · 201
{
  "user": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "role": "owner",
  "teams": [
    "team"
  ],
  "since": "2026-11-14T09:30:00Z"
}

PATCH/v1/orgs/{oid}/members/{uid}

Change a role (an admin; owners by an owner). The last owner stays.
Bearer 令牌

参数 · 路径

  • oidstring必填
  • uidstring必填

请求体 application/json

响应

请求示例
curl -X PATCH "https://side.example.com/v1/orgs/oid/members/usr_01JD7Q1Z3X5V7T9R1P3N5L7J9H" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"owner"}'

DELETE/v1/orgs/{oid}/members/{uid}

Remove someone (an admin, or themself). They leave its teams, and the spaces they were in only through them.
Bearer 令牌

参数 · 路径

  • oidstring必填
  • uidstring必填

响应

请求示例
curl -X DELETE "https://side.example.com/v1/orgs/oid/members/usr_01JD7Q1Z3X5V7T9R1P3N5L7J9H" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/orgs/{oid}/teams

Bearer 令牌

参数 · 路径

  • oidstring必填

响应

  • 200
    Teams
    object
    › 展开字段
    • itemsTeam[]必填
      › 5 个字段
      • idstring必填
      • org_idstring必填
      • namestring必填
      • membersUser[]必填
        › 4 个字段
        • idstring必填
        • emailstring必填
          Agents have an address at agents.invalid: it finds them for invites, no mail goes there
        • display_namestring必填
        • kindstring必填
          humanagent
      • created_atTimestamp必填
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/orgs/oid/teams" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "id": "id",
      "org_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "name": "A001_C003.mov",
      "members": [],
      "created_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/orgs/{oid}/teams

Make a team (an admin). Names are unique in the organization, ignoring case.
Bearer 令牌

参数 · 路径

  • oidstring必填

请求体 application/json

  • namestring必填

响应

请求示例
curl -X POST "https://side.example.com/v1/orgs/oid/teams" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov"}'
响应示例 · 201
{
  "id": "id",
  "org_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "members": [
    {}
  ],
  "created_at": "2026-11-14T09:30:00Z"
}

PATCH/v1/orgs/{oid}/teams/{tid}

Bearer 令牌

参数 · 路径

  • oidstring必填
  • tidstring必填

请求体 application/json

  • namestring必填

响应

请求示例
curl -X PATCH "https://side.example.com/v1/orgs/oid/teams/tid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov"}'
响应示例 · 200
{
  "id": "id",
  "org_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "members": [
    {}
  ],
  "created_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/orgs/{oid}/teams/{tid}

Delete a team (an admin); its roles in spaces and folder grants go with it
Bearer 令牌

参数 · 路径

  • oidstring必填
  • tidstring必填

响应

请求示例
curl -X DELETE "https://side.example.com/v1/orgs/oid/teams/tid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

POST/v1/orgs/{oid}/teams/{tid}/members

Add someone to a team (an admin); they join the organization as a member if needed
Bearer 令牌

参数 · 路径

  • oidstring必填
  • tidstring必填

请求体 application/json

  • emailstring必填

响应

请求示例
curl -X POST "https://side.example.com/v1/orgs/oid/teams/tid/members" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
响应示例 · 201
{
  "id": "id",
  "email": "[email protected]",
  "display_name": "display_name",
  "kind": "human"
}

DELETE/v1/orgs/{oid}/teams/{tid}/members/{uid}

Bearer 令牌

参数 · 路径

  • oidstring必填
  • tidstring必填
  • uidstring必填

响应

请求示例
curl -X DELETE "https://side.example.com/v1/orgs/oid/teams/tid/members/usr_01JD7Q1Z3X5V7T9R1P3N5L7J9H" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/orgs/{oid}/spaces

The organization's spaces (admins see all, members the ones they are in)
Bearer 令牌

参数 · 路径

  • oidstring必填

响应

  • 200
    Spaces
    object
    › 展开字段
    • itemsOrgSpace[]必填
      › 4 个字段
      • idstring必填
      • namestring必填
      • owner_idstring必填
      • teamsMemberTeam[]必填
        › 3 个字段
        • idstring必填
        • namestring必填
        • roleRole必填
          viewercommentereditormanager
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/orgs/oid/spaces" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "id": "id",
      "name": "A001_C003.mov",
      "owner_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "teams": []
    }
  ]
}

GET/v1/orgs/{oid}/sso

Single sign-on settings (an admin). A 404 still names the redirect URI and the DNS proof.
Bearer 令牌

参数 · 路径

  • oidstring必填

响应

请求示例
curl "https://side.example.com/v1/orgs/oid/sso" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "issuer": "issuer",
  "client_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "client_secret": "client_secret",
  "domains": [
    "domain"
  ],
  "required": false,
  "redirect_uri": "redirect_uri",
  "domain_proof": "domain_proof",
  "updated_at": "2026-11-14T09:30:00Z"
}

PUT/v1/orgs/{oid}/sso

Connect an OpenID Connect provider for email domains (an owner)
Bearer 令牌

The issuer must answer OpenID discovery over https. Each new domain must carry the DNS TXT record _sidespace. = domain_proof (422 domain_unproven otherwise), unless the server trusts it. With required, email codes stop working for those domains (403 sso_required). client_secret may be left out to keep the stored one.

参数 · 路径

  • oidstring必填

请求体SSOConfig application/json

  • issuerstring必填
  • client_idstring必填
  • client_secretstring
  • domainsstring[]必填
  • requiredboolean
    Email codes stop working for these domains
  • redirect_uristring
    Register it with the provider
  • domain_proofstring
    Value of the DNS TXT record _sidespace.
  • updated_atTimestamp

响应

请求示例
curl -X PUT "https://side.example.com/v1/orgs/oid/sso" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"issuer":"issuer","client_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S","domains":["domain"]}'
响应示例 · 200
{
  "issuer": "issuer",
  "client_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "client_secret": "client_secret",
  "domains": [
    "domain"
  ],
  "required": false,
  "redirect_uri": "redirect_uri",
  "domain_proof": "domain_proof",
  "updated_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/orgs/{oid}/sso

Turn single sign-on off (an owner); email codes work again
Bearer 令牌

参数 · 路径

  • oidstring必填

响应

请求示例
curl -X DELETE "https://side.example.com/v1/orgs/oid/sso" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/orgs/{oid}/audit

Audit export (an admin; tokens need admin), oldest first, at most 200 000 records
Bearer 令牌

参数 · 路径

  • oidstring必填

参数 · 查询

  • sincestring
    RFC 3339 or YYYY-MM-DD; default 30 days before until
  • untilstring
    Default now
  • formatstring
    jsonlcsv
    default "jsonl"

响应

  • 200
    One AuditRecord per line (jsonl), or CSV with a header row
    AuditRecord
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/orgs/oid/audit" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

PUT/v1/spaces/{sid}/org

Put the space in an organization, or take it out with an empty org_id (a space manager who is an admin there)
Bearer 令牌

Taking it out drops its teams' roles.

参数 · 路径

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

请求体 application/json

  • org_idstring必填

响应

请求示例
curl -X PUT "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/org" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"}'
响应示例 · 200
{
  "id": "id",
  "name": "A001_C003.mov",
  "role": "viewer",
  "owner_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "root_node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "journal_seq": 1,
  "created_at": "2026-11-14T09:30:00Z",
  "storage_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "fork": {
    "from_space_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "path": "Ep01/Shots/A001_C003.mov",
    "at_seq": 1
  },
  "org_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
}

GET/v1/spaces/{sid}/teams

Teams with a role in the space
Bearer 令牌

参数 · 路径

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

响应

  • 200
    Teams
    object
    › 展开字段
    • itemsMemberTeam[]必填
      › 3 个字段
      • idstring必填
      • namestring必填
      • roleRole必填
        viewercommentereditormanager
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/teams" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "id": "id",
      "name": "A001_C003.mov",
      "role": "viewer"
    }
  ]
}

PUT/v1/spaces/{sid}/teams/{tid}

Give a team of the space's organization a role (a manager); tokens need members:manage
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • tidstring必填

请求体 application/json

  • roleRole必填
    viewercommentereditormanager

响应

请求示例
curl -X PUT "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/teams/tid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"viewer"}'
响应示例 · 200
{
  "id": "id",
  "name": "A001_C003.mov",
  "role": "viewer"
}

DELETE/v1/spaces/{sid}/teams/{tid}

Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • tidstring必填

响应

请求示例
curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/teams/tid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/spaces/{sid}/folder-access

Folders with access rules
Bearer 令牌

参数 · 路径

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

响应

  • 200
    Folders
    object
    › 展开字段
    • itemsFolderAccess[]必填
      › 6 个字段
      • node_idstring必填
      • pathstring必填
      • default_roleRole | any必填
        The most anyone not granted may do inside; null keeps their space role
      • grantsFolderGrant[]必填
        › 4 个字段
        • kindstring必填
          userteam
        • idstring
        • roleRole必填
          viewercommentereditormanager
        • namestring
          An email or team name; on a request a user may be named by email instead of id
      • updated_bystring
      • updated_atTimestamp
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/folder-access" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "path": "Ep01/Shots/A001_C003.mov",
      "default_role": "viewer",
      "grants": [],
      "updated_by": "updated_by",
      "updated_at": "2026-11-14T09:30:00Z"
    }
  ]
}

GET/v1/spaces/{sid}/nodes/{nid}/access

Your role at a file or folder, and the folder whose rules decide it
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填

响应

请求示例
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/access" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "role": "viewer",
  "space_role": "viewer",
  "governed_by": {
    "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "path": "Ep01/Shots/A001_C003.mov",
    "default_role": "viewer",
    "grants": [],
    "updated_by": "updated_by",
    "updated_at": "2026-11-14T09:30:00Z"
  }
}

PUT/v1/spaces/{sid}/nodes/{nid}/access

Set a folder's rules (a manager; tokens need members:manage). Replaces them.
Bearer 令牌

The nearest folder with rules decides for everything under it. A grant may exceed the person's space role; default_role caps everyone else. Managers are never limited. Rules decide what may be changed, not what is seen.

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填

请求体SetFolderAccessRequest application/json

  • default_roleRole | any
  • grantsFolderGrant[]必填
    › 4 个字段
    • kindstring必填
      userteam
    • idstring
    • roleRole必填
      viewercommentereditormanager
    • namestring
      An email or team name; on a request a user may be named by email instead of id

响应

请求示例
curl -X PUT "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/access" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grants":[{}]}'
响应示例 · 200
{
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "path": "Ep01/Shots/A001_C003.mov",
  "default_role": "viewer",
  "grants": [
    {}
  ],
  "updated_by": "updated_by",
  "updated_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/nodes/{nid}/access

Remove a folder's rules (a manager)
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填

响应

请求示例
curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/access" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"