Side Space

API reference

Sidecars

9 endpoints · Overview

GET/v1/spaces/{sid}/namespaces

Sidecar namespaces that one member alone writes in this space
Bearer token

Parameters · path

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

Responses

  • 200
    Owned namespaces
    object
    › Show fields
    • itemsNamespaceOwner[]required
      › 3 fields
      • namespacestringrequired
      • ownerUserrequired
        › 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
  • 4xx/5xx
    Error
    Error
Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/namespaces" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "items": [
    {
      "namespace": "x-acme.qc",
      "owner": {},
      "created_at": "2026-11-14T09:30:00Z"
    }
  ]
}

PUT/v1/spaces/{sid}/namespaces/{ns}

Let only this member write the namespace here (manager). ai.generation or a custom x-… namespace.
Bearer token

Parameters · path

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

Request body application/json

  • owner_idstringrequired

Responses

Example request
curl -X PUT "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/namespaces/x-acme.qc" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"}'
Example response · 200
{
  "namespace": "x-acme.qc",
  "owner": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "created_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/namespaces/{ns}

Let every editor write the namespace again (manager)
Bearer token

Parameters · path

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

Responses

  • 204
    Released
  • 4xx/5xx
    Error
    Error
Example request
curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/namespaces/x-acme.qc" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/spaces/{sid}/versions/{vid}/sidecars

Bearer token

Parameters · path

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

Responses

  • 200
    Sidecars
    object
    › Show fields
    • itemsSidecar[]
      › 5 fields
      • namespacestringrequired
      • docobjectrequired
      • schema_versionintegerrequired
      • producerobject | nullrequired
        Who wrote it, e.g. {"name":"cliptap","version":"1.2","inherited_from":"ver_..."}
        required
      • updated_atTimestamprequired
  • 4xx/5xx
    Error
    Error
Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/sidecars" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "items": [
    {
      "namespace": "x-acme.qc",
      "doc": {},
      "schema_version": 1,
      "producer": {},
      "updated_at": "2026-11-14T09:30:00Z"
    }
  ]
}

GET/v1/spaces/{sid}/versions/{vid}/sidecars/{ns}

Bearer token

Parameters · path

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

Responses

Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/sidecars/x-acme.qc" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "namespace": "x-acme.qc",
  "doc": {},
  "schema_version": 1,
  "producer": {},
  "updated_at": "2026-11-14T09:30:00Z"
}

PUT/v1/spaces/{sid}/versions/{vid}/sidecars/{ns}

Write a sidecar (editor). Built-in namespaces are validated against proto/sidecar/.json; custom ones must start with x-; core and media are server-written.
Bearer token

Parameters · path

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

Request bodyPutSidecarRequest application/json

  • docobjectrequired
  • schema_versioninteger
    default 1
  • producerobject

Responses

Example request
curl -X PUT "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/sidecars/x-acme.qc" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"doc":{}}'
Example response · 200
{
  "namespace": "x-acme.qc",
  "doc": {},
  "schema_version": 1,
  "producer": {},
  "updated_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/versions/{vid}/sidecars/{ns}

Bearer token

Parameters · path

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

Responses

  • 204
    Deleted
  • 4xx/5xx
    Error
    Error
Example request
curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/sidecars/x-acme.qc" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/spaces/{sid}/versions/{vid}/renditions/{kind}

Bearer token

Parameters · path

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

Responses

Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/renditions/kind" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "kind": "kind",
  "mime": "video/quicktime",
  "manifest_hash": "manifest_hash",
  "size": 734003200
}

PUT/v1/spaces/{sid}/versions/{vid}/renditions/{kind}

Attach a derived file (chunks uploaded through an upload session first)
Bearer token

Parameters · path

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

Request bodyPutRenditionRequest application/json

  • manifestManifestrequired
    › 3 fields
    • algostringrequired
      fastcdc-v1
    • sizeintegerrequired
    • chunksChunkRef[]required
      › 3 fields
      • hashHashrequired
        ^[0-9a-f]{64}$
      • offsetintegerrequired
      • lenintegerrequired
  • mimestringrequired

Responses

Example request
curl -X PUT "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/renditions/kind" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"manifest":{"algo":"fastcdc-v1","size":734003200,"chunks":[]},"mime":"video/quicktime"}'
Example response · 200
{
  "kind": "kind",
  "mime": "video/quicktime",
  "manifest_hash": "manifest_hash",
  "size": 734003200
}