API reference

Developer

43 endpoints · Overview

GET/v1/openapi.yaml

This API description (no auth)

No auth

Responses

200
OpenAPI document
string

Example request

curl "https://side.example.com/v1/openapi.yaml"

GET/v1/operations.json

Every operation with the scope it needs and example calls (curl, and TypeScript, Python, CLI and MCP where they exist), generated from this description (no auth)

No auth

Responses

200
Operations
object

Example request

curl "https://side.example.com/v1/operations.json"

Example response · 200

{}

GET/v1/llms-full.txt

The agent guide (/llms.txt), rules to paste into AGENTS.md or CLAUDE.md, and every operation in plain text (no auth)

No auth

Responses

200
Text
string

Example request

curl "https://side.example.com/v1/llms-full.txt"

GET/v1/tokens

Personal access tokens the caller made (for themselves and their agents), revoked ones included

Bearer token

Responses

200
Tokens
object
› Show fields
- itemsTokenInfo[]required
  › 13 fields
  - idstringrequired
  - namestringrequired
  - prefixstringrequired
    The first characters of the secret, to tell tokens apart
  - userUserrequired
    › 4 fields
    idstringrequired
    emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestringrequired
    kindstringrequired
    humanagent
  - scopesstring[]required
  - space_idsstring[] | nullrequired
    null means every space
    required
  - expires_atTimestamp | anyrequired
  - last_used_atTimestamp | anyrequired
  - created_atTimestamprequired
  - revoked_atTimestamp | anyrequired
  - s3_access_key_idstring
    Set when the token is also an S3 key
  - app_idstring
    Set when an app got the token through OAuth: it lasts an hour and the app refreshes it
  - parent_idstring
    Set when the token was derived from another token; it works only while that one (and every token above it) does
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/tokens" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "name": "A001_C003.mov",
      "prefix": "prefix",
      "user": {},
      "scopes": [],
      "space_ids": [],
      "expires_at": "2026-11-14T09:30:00Z",
      "last_used_at": "2026-11-14T09:30:00Z",
      "created_at": "2026-11-14T09:30:00Z",
      "revoked_at": "2026-11-14T09:30:00Z",
      "s3_access_key_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "app_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
    }
  ]
}

POST/v1/tokens

Make a personal access token; the secret is returned once

Bearer token

Request body application/json

namestringrequired
≤ 100 chars
scopesstring[]required
space_idsstring[]
Limit to these spaces (the caller must be a member); omitted means every space
expires_in_daysinteger
0 means never
default 90 · ≥ 0 · ≤ 3650
agent_idstring
Act as this agent (one the caller made) instead of the caller
s3boolean
Also make it an S3 key for the S3-compatible gateway: s3_access_key_id is returned and the token is the secret access key
default false

Responses

201
The token (shown once) and its details
object
› Show fields
- tokenstringrequired
- infoTokenInforequired
  › 13 fields
  - idstringrequired
  - namestringrequired
  - prefixstringrequired
    The first characters of the secret, to tell tokens apart
  - userUserrequired
    › 4 fields
    idstringrequired
    emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestringrequired
    kindstringrequired
    humanagent
  - scopesstring[]required
  - space_idsstring[] | nullrequired
    null means every space
    required
  - expires_atTimestamp | anyrequired
  - last_used_atTimestamp | anyrequired
  - created_atTimestamprequired
  - revoked_atTimestamp | anyrequired
  - s3_access_key_idstring
    Set when the token is also an S3 key
  - app_idstring
    Set when an app got the token through OAuth: it lasts an hour and the app refreshes it
  - parent_idstring
    Set when the token was derived from another token; it works only while that one (and every token above it) does
- s3_access_key_idstring
  With s3: the access key id (the token is the secret)
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/tokens" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov","scopes":["scope"]}'

Example response · 201

{
  "token": "token",
  "info": {
    "id": "id",
    "name": "A001_C003.mov",
    "prefix": "prefix",
    "user": {},
    "scopes": [
      "scope"
    ],
    "space_ids": [
      "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C"
    ],
    "expires_at": "2026-11-14T09:30:00Z",
    "last_used_at": "2026-11-14T09:30:00Z",
    "created_at": "2026-11-14T09:30:00Z",
    "revoked_at": "2026-11-14T09:30:00Z",
    "s3_access_key_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "app_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
  },
  "s3_access_key_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
}

DELETE/v1/tokens/{id}

Revoke a token at once

Bearer token

Parameters · path

idstringrequired

Responses

204
Revoked
4xx/5xx
Error
Error

Example request

curl -X DELETE "https://side.example.com/v1/tokens/id" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/token

The calling access token itself (who it acts as, scopes, spaces, expiry). Any token may call it.

Bearer token

Responses

200
The token
TokenInfo
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/token" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "id": "id",
  "name": "A001_C003.mov",
  "prefix": "prefix",
  "user": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "scopes": [
    "scope"
  ],
  "space_ids": [
    "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C"
  ],
  "expires_at": "2026-11-14T09:30:00Z",
  "last_used_at": "2026-11-14T09:30:00Z",
  "created_at": "2026-11-14T09:30:00Z",
  "revoked_at": "2026-11-14T09:30:00Z",
  "s3_access_key_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "app_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
}

Make a narrower token from the calling one, e.g. for a subagent: scopes and spaces only shrink, it expires no later, and it is switched off when the calling token (or any token above it) is revoked or expires. At most 8 levels.

Bearer token

Request body application/json

namestringrequired
≤ 100 chars
scopesstring[]
Each must be granted by the calling token; omitted means the same scopes
space_idsstring[]
Each must be reachable by the calling token; omitted means the same spaces
expires_in_secondsinteger
Omitted means when the calling token expires; never later than that
≥ 60
s3boolean
default false

Responses

201
The token (shown once) and its details
object
› Show fields
- tokenstringrequired
- infoTokenInforequired
  › 13 fields
  - idstringrequired
  - namestringrequired
  - prefixstringrequired
    The first characters of the secret, to tell tokens apart
  - userUserrequired
    › 4 fields
    idstringrequired
    emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestringrequired
    kindstringrequired
    humanagent
  - scopesstring[]required
  - space_idsstring[] | nullrequired
    null means every space
    required
  - expires_atTimestamp | anyrequired
  - last_used_atTimestamp | anyrequired
  - created_atTimestamprequired
  - revoked_atTimestamp | anyrequired
  - s3_access_key_idstring
    Set when the token is also an S3 key
  - app_idstring
    Set when an app got the token through OAuth: it lasts an hour and the app refreshes it
  - parent_idstring
    Set when the token was derived from another token; it works only while that one (and every token above it) does
- s3_access_key_idstring
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/token/derive" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov"}'

Example response · 201

{
  "token": "token",
  "info": {
    "id": "id",
    "name": "A001_C003.mov",
    "prefix": "prefix",
    "user": {},
    "scopes": [
      "scope"
    ],
    "space_ids": [
      "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C"
    ],
    "expires_at": "2026-11-14T09:30:00Z",
    "last_used_at": "2026-11-14T09:30:00Z",
    "created_at": "2026-11-14T09:30:00Z",
    "revoked_at": "2026-11-14T09:30:00Z",
    "s3_access_key_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "app_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
  },
  "s3_access_key_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
}

GET/v1/token/derived

Tokens derived from the calling one, at any depth, newest first

Bearer token

Responses

200
Tokens
object
› Show fields
- itemsTokenInfo[]required
  › 13 fields
  - idstringrequired
  - namestringrequired
  - prefixstringrequired
    The first characters of the secret, to tell tokens apart
  - userUserrequired
    › 4 fields
    idstringrequired
    emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestringrequired
    kindstringrequired
    humanagent
  - scopesstring[]required
  - space_idsstring[] | nullrequired
    null means every space
    required
  - expires_atTimestamp | anyrequired
  - last_used_atTimestamp | anyrequired
  - created_atTimestamprequired
  - revoked_atTimestamp | anyrequired
  - s3_access_key_idstring
    Set when the token is also an S3 key
  - app_idstring
    Set when an app got the token through OAuth: it lasts an hour and the app refreshes it
  - parent_idstring
    Set when the token was derived from another token; it works only while that one (and every token above it) does
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/token/derived" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "name": "A001_C003.mov",
      "prefix": "prefix",
      "user": {},
      "scopes": [],
      "space_ids": [],
      "expires_at": "2026-11-14T09:30:00Z",
      "last_used_at": "2026-11-14T09:30:00Z",
      "created_at": "2026-11-14T09:30:00Z",
      "revoked_at": "2026-11-14T09:30:00Z",
      "s3_access_key_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "app_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
    }
  ]
}

DELETE/v1/token/derived/{id}

Revoke a token derived from the calling one, and every token below it. The id "self" revokes the calling token.

Bearer token

Parameters · path

idstringrequired

Responses

204
Revoked
4xx/5xx
Error
Error

Example request

curl -X DELETE "https://side.example.com/v1/token/derived/id" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/apps

OAuth apps the caller registered (signed-in apps only)

Bearer token

Responses

200
Apps
object
› Show fields
- itemsOAuthApp[]required
  › 8 fields
  - idstringrequired
    The OAuth client_id
  - namestringrequired
  - redirect_urisstring[]required
  - client_uristring
  - logo_uristring
  - confidentialbooleanrequired
  - registeredbooleanrequired
    The app registered itself (RFC 7591)
  - created_atTimestamprequired
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/apps" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "name": "A001_C003.mov",
      "redirect_uris": [],
      "client_uri": "client_uri",
      "logo_uri": "logo_uri",
      "confidential": false,
      "registered": false,
      "created_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/apps

Register an OAuth app. People connect it at /oauth/authorize; it gets tokens at /oauth/token (see /.well-known/oauth-authorization-server). Apps can also register themselves at /oauth/register (RFC 7591, public clients only).

Bearer token

Request body application/json

namestringrequired
≤ 100 chars
redirect_urisstring[]required
https, http on localhost (any port), or the app's own scheme
≤ 10 items
client_uristring
https home page shown on the consent page
logo_uristring
confidentialboolean
Server-side app: gets a client_secret (shown once); PKCE becomes optional
default false

Responses

201
The app (and its secret, once)
any
› Show fields
- idstringrequired
  The OAuth client_id
- namestringrequired
- redirect_urisstring[]required
- client_uristring
- logo_uristring
- confidentialbooleanrequired
- registeredbooleanrequired
  The app registered itself (RFC 7591)
- created_atTimestamprequired
- client_secretstring
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/apps" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov","redirect_uris":["redirect_uri"]}'

Example response · 201

{
  "id": "id",
  "name": "A001_C003.mov",
  "redirect_uris": [
    "redirect_uri"
  ],
  "client_uri": "client_uri",
  "logo_uri": "logo_uri",
  "confidential": false,
  "registered": false,
  "created_at": "2026-11-14T09:30:00Z",
  "client_secret": "client_secret"
}

DELETE/v1/apps/{id}

Delete an app; every grant made to it stops working

Bearer token

Parameters · path

idstringrequired

Responses

204
Deleted
4xx/5xx
Error
Error

Example request

curl -X DELETE "https://side.example.com/v1/apps/id" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/agents

Agents the caller made

Bearer token

Responses

200
Agents
object
› Show fields
- itemsUser[]required
  › 4 fields
  - idstringrequired
  - emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  - display_namestringrequired
  - kindstringrequired
    humanagent
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/agents" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "email": "[email protected]",
      "display_name": "display_name",
      "kind": "human"
    }
  ]
}

POST/v1/agents

Make an agent (AI agent or service account). Add it to spaces by its email address, then make it a token with agent_id.

Bearer token

Request body application/json

namestringrequired
≤ 100 chars

Responses

201
The agent
User
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/agents" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov"}'

Example response · 201

{
  "id": "id",
  "email": "[email protected]",
  "display_name": "display_name",
  "kind": "human"
}

DELETE/v1/agents/{id}

Retire an agent - revokes its tokens and takes it out of every space (its past changes stay attributed to it)

Bearer token

Parameters · path

idstringrequired

Responses

204
Retired
4xx/5xx
Error
Error

Example request

curl -X DELETE "https://side.example.com/v1/agents/id" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

GET/v1/spaces/{sid}/webhooks

The space's webhook subscriptions (manager; tokens need webhooks:manage)

Bearer token

Parameters · path

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

Responses

200
Subscriptions
object
› Show fields
- itemsWebhook[]required
  › 15 fields
  - idstringrequired
  - space_idstringrequired
  - created_bystringrequired
    The manager it speaks for; it stops if they stop being a manager
  - urlstringrequired
    https (plain http and private addresses only on dev servers)
  - eventsstring[]required
    Journal ops to send (node.created, version.created, sidecar.updated, …); empty = all
  - path_globstringrequired
    Only paths matching, e.g. /dailies/** or **/*.mov; empty = all
  - mime_prefixstringrequired
    Only files whose type starts with this, e.g. video/; empty = all
  - descriptionstringrequired
  - activebooleanrequired
  - disabled_reasonstring | null
    required
  - cursor_seqintegerrequired
    Last journal seq handled
  - attemptsintegerrequired
    Failed tries of the next event
  - failing_sinceTimestamp | any
  - last_errorstring | null
    required
  - created_atTimestamprequired
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/webhooks" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
      "created_by": "created_by",
      "url": "https://hooks.example.com/side",
      "events": [],
      "path_glob": "path_glob",
      "mime_prefix": "mime_prefix",
      "description": "description",
      "active": false,
      "disabled_reason": "disabled_reason",
      "cursor_seq": 1,
      "attempts": 1,
      "failing_since": "2026-11-14T09:30:00Z",
      "last_error": "last_error",
      "created_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/spaces/{sid}/webhooks

Subscribe a URL to the space's events (manager). The secret is shown once.

Bearer token

Parameters · path

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

Request bodyWebhookRequest application/json

urlstring
eventsstring[]
path_globstring
mime_prefixstring
descriptionstring
activeboolean
from_seqinteger
Create only: start after this seq instead of with new events
≥ 0

Responses

201
Created
any
› Show fields
- idstringrequired
- space_idstringrequired
- created_bystringrequired
  The manager it speaks for; it stops if they stop being a manager
- urlstringrequired
  https (plain http and private addresses only on dev servers)
- eventsstring[]required
  Journal ops to send (node.created, version.created, sidecar.updated, …); empty = all
- path_globstringrequired
  Only paths matching, e.g. /dailies/** or **/*.mov; empty = all
- mime_prefixstringrequired
  Only files whose type starts with this, e.g. video/; empty = all
- descriptionstringrequired
- activebooleanrequired
- disabled_reasonstring | null
  required
- cursor_seqintegerrequired
  Last journal seq handled
- attemptsintegerrequired
  Failed tries of the next event
- failing_sinceTimestamp | any
- last_errorstring | null
  required
- created_atTimestamprequired
- secretstringrequired
  whsec_…, the HMAC key
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/webhooks" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/side","events":["event"],"path_glob":"path_glob"}'

Example response · 201

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "created_by": "created_by",
  "url": "https://hooks.example.com/side",
  "events": [
    "event"
  ],
  "path_glob": "path_glob",
  "mime_prefix": "mime_prefix",
  "description": "description",
  "active": false,
  "disabled_reason": "disabled_reason",
  "cursor_seq": 1,
  "attempts": 1,
  "failing_since": "2026-11-14T09:30:00Z",
  "last_error": "last_error",
  "created_at": "2026-11-14T09:30:00Z",
  "secret": "secret"
}

PATCH/v1/spaces/{sid}/webhooks/{wid}

Change filters or URL, or turn it off or back on (on clears its failures)

Bearer token

Parameters · path

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

Request bodyWebhookRequest application/json

urlstring
eventsstring[]
path_globstring
mime_prefixstring
descriptionstring
activeboolean
from_seqinteger
Create only: start after this seq instead of with new events
≥ 0

Responses

200
Updated
Webhook
4xx/5xx
Error
Error

Example request

curl -X PATCH "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/webhooks/wid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/side","events":["event"],"path_glob":"path_glob"}'

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "created_by": "created_by",
  "url": "https://hooks.example.com/side",
  "events": [
    "event"
  ],
  "path_glob": "path_glob",
  "mime_prefix": "mime_prefix",
  "description": "description",
  "active": false,
  "disabled_reason": "disabled_reason",
  "cursor_seq": 1,
  "attempts": 1,
  "failing_since": "2026-11-14T09:30:00Z",
  "last_error": "last_error",
  "created_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/webhooks/{wid}

Remove the subscription and its delivery log

Bearer token

Parameters · path

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

Responses

204
Removed
4xx/5xx
Error
Error

Example request

curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/webhooks/wid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

POST/v1/spaces/{sid}/webhooks/{wid}/ping

Send a test event of type ping now; the answer is the delivery (status, error, time)

Bearer token

Parameters · path

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

Responses

200
Delivery
WebhookDelivery
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/webhooks/wid/ping" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "id": 1,
  "event_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "event_type": "event_type",
  "seq": 3,
  "attempt": 1,
  "status": 1,
  "error": "error",
  "duration_ms": 83500,
  "created_at": "2026-11-14T09:30:00Z"
}

POST/v1/spaces/{sid}/webhooks/{wid}/replay

Send every event after from_seq again (and turn the subscription on)

Bearer token

Parameters · path

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

Request body application/json

from_seqintegerrequired
≥ 0

Responses

200
Rewound
Webhook
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/webhooks/wid/replay" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from_seq":1}'

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "created_by": "created_by",
  "url": "https://hooks.example.com/side",
  "events": [
    "event"
  ],
  "path_glob": "path_glob",
  "mime_prefix": "mime_prefix",
  "description": "description",
  "active": false,
  "disabled_reason": "disabled_reason",
  "cursor_seq": 1,
  "attempts": 1,
  "failing_since": "2026-11-14T09:30:00Z",
  "last_error": "last_error",
  "created_at": "2026-11-14T09:30:00Z"
}

GET/v1/spaces/{sid}/webhooks/{wid}/deliveries

Latest delivery attempts, newest first (kept 7 days)

Bearer token

Parameters · path

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

Parameters · query

limitinteger
default 500 · ≥ 1 · ≤ 1000

Responses

200
Deliveries
object
› Show fields
- itemsWebhookDelivery[]required
  › 9 fields
  - idintegerrequired
  - event_idstringrequired
  - event_typestringrequired
  - seqinteger | null
    required
  - attemptintegerrequired
  - statusinteger | null
    HTTP status; null when nothing answered
    required
  - errorstring | null
    required
  - duration_msintegerrequired
  - created_atTimestamprequired
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/webhooks/wid/deliveries" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": 1,
      "event_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "event_type": "event_type",
      "seq": 3,
      "attempt": 1,
      "status": 1,
      "error": "error",
      "duration_ms": 83500,
      "created_at": "2026-11-14T09:30:00Z"
    }
  ]
}

GET/v1/spaces/{sid}/actions

What can be done to files here, with a JSON Schema of each action's params and whether this server can run it

Bearer token

Parameters · path

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

Responses

200
Actions
object
› Show fields
- itemsAction[]required
  › 9 fields
  - namestringrequired
  - versionstringrequired
    Changes when its output would; part of the cache key
  - titlestringrequired
  - descriptionstringrequired
  - acceptsstring[]required
    MIME prefixes it takes, e.g. video/; empty = any file
  - writesstring[]required
    Sidecar namespaces it writes, and "files" when it makes new files
  - params_schemaobjectrequired
    JSON Schema of its params
  - availablebooleanrequired
  - needsstring
    When not available: the setting the server lacks
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/actions" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "name": "A001_C003.mov",
      "version": "version",
      "title": "title",
      "description": "description",
      "accepts": [],
      "writes": [],
      "params_schema": {},
      "available": false,
      "needs": "needs"
    }
  ]
}

GET/v1/spaces/{sid}/runs

Recent runs, newest first (any member)

Bearer token

Parameters · path

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

Parameters · query

version_idstring
node_idstring
stateRunState
queuedrunningdonefailedcanceled
actionstring
pipeline_idstring
limitinteger
default 50 · ≥ 1 · ≤ 500

Responses

200
Runs
object
› Show fields
- itemsRun[]required
  › 18 fields
  - idstringrequired
  - space_idstringrequired
  - node_idstringrequired
  - version_idstringrequired
    The version it works on; a newer save is a new run
  - actionstringrequired
  - action_versionstringrequired
  - paramsobjectrequired
    The params with defaults filled in
  - pipeline_idstring | null
    required
  - requested_bystringrequired
  - stateRunStaterequired
    queuedrunningdonefailedcanceled
  - attemptsintegerrequired
    Tries so far; failures that may pass later retry up to 3 times
  - progressnumber | null
    ≥ 0 · ≤ 1
    required
  - errorstring | null
    required
  - resultobject | null
    required
    › 2 fields
    sidecarsmap<string, any>
    namespace → document written on the version
    filesobject[]
    › 4 fields
    pathstringrequired
    mimestringrequired
    node_idstring
    version_idstring
  - cachedbooleanrequired
    The result was reused from the same bytes done before
  - created_atTimestamprequired
  - started_atTimestamp | any
  - finished_atTimestamp | any
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/runs" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
      "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
      "action": "action",
      "action_version": "action_version",
      "params": {},
      "pipeline_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "requested_by": "requested_by",
      "state": "queued",
      "attempts": 1,
      "progress": 0.5,
      "error": "error",
      "result": {},
      "cached": false,
      "created_at": "2026-11-14T09:30:00Z",
      "started_at": "2026-11-14T09:30:00Z",
      "finished_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/spaces/{sid}/runs

Run an action on a file (editor; tokens need runs:write). Answers the queued or running run, or 200 with a done run when the same bytes were done before.

Bearer token

Parameters · path

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

Request bodyRunRequest application/json

actionstringrequired
version_idstring
node_idstring
pathstring
paramsobject
Checked against the action's params_schema
freshboolean
Run again even if these bytes were done before

Responses

200
Already done (cached)
Run
202
Queued
Run
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/runs" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"action"}'

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "action": "action",
  "action_version": "action_version",
  "params": {},
  "pipeline_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "requested_by": "requested_by",
  "state": "queued",
  "attempts": 1,
  "progress": 0.5,
  "error": "error",
  "result": {
    "sidecars": {
      "key": "string"
    },
    "files": [
      {}
    ]
  },
  "cached": false,
  "created_at": "2026-11-14T09:30:00Z",
  "started_at": "2026-11-14T09:30:00Z",
  "finished_at": "2026-11-14T09:30:00Z"
}

GET/v1/spaces/{sid}/runs/{rid}

One run, with progress while running and the result when done

Bearer token

Parameters · path

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

Responses

200
Run
Run
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/runs/rid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "action": "action",
  "action_version": "action_version",
  "params": {},
  "pipeline_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "requested_by": "requested_by",
  "state": "queued",
  "attempts": 1,
  "progress": 0.5,
  "error": "error",
  "result": {
    "sidecars": {
      "key": "string"
    },
    "files": [
      {}
    ]
  },
  "cached": false,
  "created_at": "2026-11-14T09:30:00Z",
  "started_at": "2026-11-14T09:30:00Z",
  "finished_at": "2026-11-14T09:30:00Z"
}

POST/v1/spaces/{sid}/runs/{rid}/cancel

Stop a queued or running run (editor)

Bearer token

Parameters · path

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

Responses

200
Canceled
Run
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/runs/rid/cancel" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "action": "action",
  "action_version": "action_version",
  "params": {},
  "pipeline_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "requested_by": "requested_by",
  "state": "queued",
  "attempts": 1,
  "progress": 0.5,
  "error": "error",
  "result": {
    "sidecars": {
      "key": "string"
    },
    "files": [
      {}
    ]
  },
  "cached": false,
  "created_at": "2026-11-14T09:30:00Z",
  "started_at": "2026-11-14T09:30:00Z",
  "finished_at": "2026-11-14T09:30:00Z"
}

GET/v1/spaces/{sid}/pipelines

The space's pipelines (any member)

Bearer token

Parameters · path

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

Responses

200
Pipelines
object
› Show fields
- itemsPipeline[]required
  › 14 fields
  - idstringrequired
  - space_idstringrequired
  - created_bystringrequired
    The manager it runs for; it stops if they stop being a manager
  - namestringrequired
  - actionstringrequired
  - paramsobjectrequired
  - path_globstringrequired
    e.g. /dailies/** or **/*.mov; empty = all
  - mime_prefixstringrequired
    e.g. video/; empty = what the action accepts
  - conditionsPipelineConditions
    › 7 fields
    min_sizeinteger
    Bytes
    ≥ 0
    max_sizeinteger
    ≥ 0
    min_duration_snumber
    ≥ 0
    max_duration_snumber
    ≥ 0
    min_widthinteger
    ≥ 0
    min_heightinteger
    ≥ 0
    has_audioboolean
  - afterstring | null
    The action it follows: it starts when a run of that action finishes on a matching file, instead of on save
    required
  - activebooleanrequired
  - disabled_reasonstring | null
    required
  - cursor_seqintegerrequired
    Last journal seq looked at
  - created_atTimestamprequired
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/pipelines" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
      "created_by": "created_by",
      "name": "A001_C003.mov",
      "action": "action",
      "params": {},
      "path_glob": "path_glob",
      "mime_prefix": "mime_prefix",
      "conditions": {},
      "after": "after",
      "active": false,
      "disabled_reason": "disabled_reason",
      "cursor_seq": 1,
      "created_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/spaces/{sid}/pipelines

Run an action on every new file that matches (manager; tokens need pipelines:manage). Starts with files saved from now on; backfill for the ones already there.

Bearer token

Parameters · path

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

Request bodyPipelineRequest application/json

namestring
actionstring
paramsobject
path_globstring
mime_prefixstring
conditionsPipelineConditions
› 7 fields
- min_sizeinteger
  Bytes
  ≥ 0
- max_sizeinteger
  ≥ 0
- min_duration_snumber
  ≥ 0
- max_duration_snumber
  ≥ 0
- min_widthinteger
  ≥ 0
- min_heightinteger
  ≥ 0
- has_audioboolean
afterstring
An action name; "" clears it
activeboolean

Responses

201
Created
Pipeline
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/pipelines" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov","action":"action","params":{}}'

Example response · 201

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "created_by": "created_by",
  "name": "A001_C003.mov",
  "action": "action",
  "params": {},
  "path_glob": "path_glob",
  "mime_prefix": "mime_prefix",
  "conditions": {
    "min_size": 1,
    "max_size": 1,
    "min_duration_s": 0.5,
    "max_duration_s": 0.5,
    "min_width": 1,
    "min_height": 1,
    "has_audio": false
  },
  "after": "after",
  "active": false,
  "disabled_reason": "disabled_reason",
  "cursor_seq": 1,
  "created_at": "2026-11-14T09:30:00Z"
}

PATCH/v1/spaces/{sid}/pipelines/{pid}

Change it, or turn it off or back on (manager)

Bearer token

Parameters · path

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

Request bodyPipelineRequest application/json

namestring
actionstring
paramsobject
path_globstring
mime_prefixstring
conditionsPipelineConditions
› 7 fields
- min_sizeinteger
  Bytes
  ≥ 0
- max_sizeinteger
  ≥ 0
- min_duration_snumber
  ≥ 0
- max_duration_snumber
  ≥ 0
- min_widthinteger
  ≥ 0
- min_heightinteger
  ≥ 0
- has_audioboolean
afterstring
An action name; "" clears it
activeboolean

Responses

200
Updated
Pipeline
4xx/5xx
Error
Error

Example request

curl -X PATCH "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/pipelines/pid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov","action":"action","params":{}}'

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "created_by": "created_by",
  "name": "A001_C003.mov",
  "action": "action",
  "params": {},
  "path_glob": "path_glob",
  "mime_prefix": "mime_prefix",
  "conditions": {
    "min_size": 1,
    "max_size": 1,
    "min_duration_s": 0.5,
    "max_duration_s": 0.5,
    "min_width": 1,
    "min_height": 1,
    "has_audio": false
  },
  "after": "after",
  "active": false,
  "disabled_reason": "disabled_reason",
  "cursor_seq": 1,
  "created_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/pipelines/{pid}

Remove it (its runs stay)

Bearer token

Parameters · path

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

Responses

204
Removed
4xx/5xx
Error
Error

Example request

curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/pipelines/pid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

POST/v1/spaces/{sid}/pipelines/{pid}/backfill

Queue the action on the matching files already in the space (manager)

Bearer token

Parameters · path

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

Responses

200
How many runs started
object
› Show fields
- runsintegerrequired
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/pipelines/pid/backfill" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "runs": 1
}

GET/v1/spaces/{sid}/pipeline-templates

Ready-made rule sets (any member)

Bearer token

Parameters · path

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

Responses

200
Templates
object
› Show fields
- itemsPipelineTemplate[]required
  › 4 fields
  - idstringrequired
  - titlestringrequired
  - descriptionstringrequired
  - pipelinesPipelineRequest[]required
    › 8 fields
    namestring
    actionstring
    paramsobject
    path_globstring
    mime_prefixstring
    conditionsPipelineConditions
    › 7 fields
    min_sizeinteger
    Bytes
    ≥ 0
    max_sizeinteger
    ≥ 0
    min_duration_snumber
    ≥ 0
    max_duration_snumber
    ≥ 0
    min_widthinteger
    ≥ 0
    min_heightinteger
    ≥ 0
    has_audioboolean
    afterstring
    An action name; "" clears it
    activeboolean
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/pipeline-templates" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "title": "title",
      "description": "description",
      "pipelines": []
    }
  ]
}

POST/v1/spaces/{sid}/pipeline-templates/{tid}

Create a template's pipelines in the space (manager; tokens need pipelines:manage)

Bearer token

Parameters · path

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

Request body application/json

path_globstring
Limit them to these paths
backfillboolean
Also run them on the matching files already there

Responses

201
Created
object
› Show fields
- itemsPipeline[]required
  › 14 fields
  - idstringrequired
  - space_idstringrequired
  - created_bystringrequired
    The manager it runs for; it stops if they stop being a manager
  - namestringrequired
  - actionstringrequired
  - paramsobjectrequired
  - path_globstringrequired
    e.g. /dailies/** or **/*.mov; empty = all
  - mime_prefixstringrequired
    e.g. video/; empty = what the action accepts
  - conditionsPipelineConditions
    › 7 fields
    min_sizeinteger
    Bytes
    ≥ 0
    max_sizeinteger
    ≥ 0
    min_duration_snumber
    ≥ 0
    max_duration_snumber
    ≥ 0
    min_widthinteger
    ≥ 0
    min_heightinteger
    ≥ 0
    has_audioboolean
  - afterstring | null
    The action it follows: it starts when a run of that action finishes on a matching file, instead of on save
    required
  - activebooleanrequired
  - disabled_reasonstring | null
    required
  - cursor_seqintegerrequired
    Last journal seq looked at
  - created_atTimestamprequired
- runsintegerrequired
  Runs started by the backfill
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/pipeline-templates/tid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path_glob":"path_glob","backfill":false}'

Example response · 201

{
  "items": [
    {
      "id": "id",
      "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
      "created_by": "created_by",
      "name": "A001_C003.mov",
      "action": "action",
      "params": {},
      "path_glob": "path_glob",
      "mime_prefix": "mime_prefix",
      "conditions": {},
      "after": "after",
      "active": false,
      "disabled_reason": "disabled_reason",
      "cursor_seq": 1,
      "created_at": "2026-11-14T09:30:00Z"
    }
  ],
  "runs": 1
}

GET/v1/spaces/{sid}/plugins

The space's plugins (any member)

Bearer token

Parameters · path

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

Responses

200
Plugins
object
› Show fields
- itemsPlugin[]required
  › 10 fields
  - idstringrequired
  - space_idstringrequired
  - namestringrequired
  - manifestPluginManifestrequired
    › 9 fields
    namestringrequired
    Its actions are .
    ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
    titlestring
    descriptionstring
    versionstringrequired
    Part of the result cache key: a new version runs files again
    homepagestring
    runtimestring
    https: jobs are POSTed to endpoint. runner: no endpoint; sidespace runner (or any program) claims jobs at POST /v1/plugin-runs/claim
    httpsrunner
    default "https"
    endpointstring
    Receives the signed jobs (POST); https. Not set for runner plugins
    timeout_secondsinteger
    How long a run answered with 202 may take before it is sent again
    default 3600 · ≥ 10 · ≤ 86400
    actionsobject[]required
    ≤ 50 items
    › 6 fields
    namestringrequired
    ^[a-z][a-z0-9_-]{0,40}$
    titlestring
    descriptionstring
    acceptsstring[]
    MIME prefixes; empty = any file
    writesstring[]required
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
    params_schemaobject
    JSON Schema the params are checked against
  - endpointstringrequired
  - created_bystringrequired
  - activebooleanrequired
  - disabled_reasonstring | null
    required
  - created_atTimestamprequired
  - updated_atTimestamprequired
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/plugins" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
      "name": "A001_C003.mov",
      "manifest": {},
      "endpoint": "endpoint",
      "created_by": "created_by",
      "active": false,
      "disabled_reason": "disabled_reason",
      "created_at": "2026-11-14T09:30:00Z",
      "updated_at": "2026-11-14T09:30:00Z"
    }
  ]
}

POST/v1/spaces/{sid}/plugins

Install a plugin from its manifest (manager; tokens need plugins:manage). The signing secret is shown once.

Bearer token

Parameters · path

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

Request bodyPluginRequest application/json

manifest_urlstring
manifestPluginManifest
› 9 fields
- namestringrequired
  Its actions are .
  ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
- titlestring
- descriptionstring
- versionstringrequired
  Part of the result cache key: a new version runs files again
- homepagestring
- runtimestring
  https: jobs are POSTed to endpoint. runner: no endpoint; sidespace runner (or any program) claims jobs at POST /v1/plugin-runs/claim
  httpsrunner
  default "https"
- endpointstring
  Receives the signed jobs (POST); https. Not set for runner plugins
- timeout_secondsinteger
  How long a run answered with 202 may take before it is sent again
  default 3600 · ≥ 10 · ≤ 86400
- actionsobject[]required
  ≤ 50 items
  › 6 fields
  - namestringrequired
    ^[a-z][a-z0-9_-]{0,40}$
  - titlestring
  - descriptionstring
  - acceptsstring[]
    MIME prefixes; empty = any file
  - writesstring[]required
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
  - params_schemaobject
    JSON Schema the params are checked against
activeboolean

Responses

201
Installed
any
› Show fields
- idstringrequired
- space_idstringrequired
- namestringrequired
- manifestPluginManifestrequired
  › 9 fields
  - namestringrequired
    Its actions are .
    ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
  - titlestring
  - descriptionstring
  - versionstringrequired
    Part of the result cache key: a new version runs files again
  - homepagestring
  - runtimestring
    https: jobs are POSTed to endpoint. runner: no endpoint; sidespace runner (or any program) claims jobs at POST /v1/plugin-runs/claim
    httpsrunner
    default "https"
  - endpointstring
    Receives the signed jobs (POST); https. Not set for runner plugins
  - timeout_secondsinteger
    How long a run answered with 202 may take before it is sent again
    default 3600 · ≥ 10 · ≤ 86400
  - actionsobject[]required
    ≤ 50 items
    › 6 fields
    namestringrequired
    ^[a-z][a-z0-9_-]{0,40}$
    titlestring
    descriptionstring
    acceptsstring[]
    MIME prefixes; empty = any file
    writesstring[]required
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
    params_schemaobject
    JSON Schema the params are checked against
- endpointstringrequired
- created_bystringrequired
- activebooleanrequired
- disabled_reasonstring | null
  required
- created_atTimestamprequired
- updated_atTimestamprequired
- secretstringrequired
  whsec_…, the HMAC key jobs are signed with
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/plugins" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"manifest_url":"manifest_url","manifest":{"name":"A001_C003.mov","version":"version","actions":[]},"active":false}'

Example response · 201

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "name": "A001_C003.mov",
  "manifest": {
    "name": "A001_C003.mov",
    "title": "title",
    "description": "description",
    "version": "version",
    "homepage": "homepage",
    "runtime": "https",
    "endpoint": "endpoint",
    "timeout_seconds": 3600,
    "actions": []
  },
  "endpoint": "endpoint",
  "created_by": "created_by",
  "active": false,
  "disabled_reason": "disabled_reason",
  "created_at": "2026-11-14T09:30:00Z",
  "updated_at": "2026-11-14T09:30:00Z",
  "secret": "secret"
}

PATCH/v1/spaces/{sid}/plugins/{pid}

Take a new manifest (same name), or turn it off or on (manager)

Bearer token

Parameters · path

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

Request bodyPluginRequest application/json

manifest_urlstring
manifestPluginManifest
› 9 fields
- namestringrequired
  Its actions are .
  ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
- titlestring
- descriptionstring
- versionstringrequired
  Part of the result cache key: a new version runs files again
- homepagestring
- runtimestring
  https: jobs are POSTed to endpoint. runner: no endpoint; sidespace runner (or any program) claims jobs at POST /v1/plugin-runs/claim
  httpsrunner
  default "https"
- endpointstring
  Receives the signed jobs (POST); https. Not set for runner plugins
- timeout_secondsinteger
  How long a run answered with 202 may take before it is sent again
  default 3600 · ≥ 10 · ≤ 86400
- actionsobject[]required
  ≤ 50 items
  › 6 fields
  - namestringrequired
    ^[a-z][a-z0-9_-]{0,40}$
  - titlestring
  - descriptionstring
  - acceptsstring[]
    MIME prefixes; empty = any file
  - writesstring[]required
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
  - params_schemaobject
    JSON Schema the params are checked against
activeboolean

Responses

200
Updated
Plugin
4xx/5xx
Error
Error

Example request

curl -X PATCH "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/plugins/pid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"manifest_url":"manifest_url","manifest":{"name":"A001_C003.mov","version":"version","actions":[]},"active":false}'

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "name": "A001_C003.mov",
  "manifest": {
    "name": "A001_C003.mov",
    "title": "title",
    "description": "description",
    "version": "version",
    "homepage": "homepage",
    "runtime": "https",
    "endpoint": "endpoint",
    "timeout_seconds": 3600,
    "actions": []
  },
  "endpoint": "endpoint",
  "created_by": "created_by",
  "active": false,
  "disabled_reason": "disabled_reason",
  "created_at": "2026-11-14T09:30:00Z",
  "updated_at": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/plugins/{pid}

Uninstall (manager). Runs still waiting on it fail; what it wrote stays.

Bearer token

Parameters · path

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

Responses

204
Removed
4xx/5xx
Error
Error

Example request

curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/plugins/pid" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

POST/v1/plugin-runs/claim

A runner claims the oldest waiting job of a runner plugin (ADR 0022). Authorization: Bearer :. The job is a PluginJob with a fresh callback token and input URL; complete it with the /v1/plugin-runs/{rid}/… calls.

No auth

Parameters · query

waitinteger
Seconds to wait for a job (long poll)
default 0 · ≥ 0 · ≤ 30

Responses

200
A job
object
204
No job came in time
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/plugin-runs/claim"

Example response · 200

{}

POST/v1/plugin-runs/{rid}/progress

A plugin reports how far a run it answered with 202 has got

Run token

Parameters · path

ridstringrequired

Request body application/json

progressnumberrequired
≥ 0 · ≤ 1

Responses

204
Recorded
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/plugin-runs/rid/progress" \
  -H "Authorization: Bearer $RUN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"progress":0.5}'

POST/v1/plugin-runs/{rid}/upload

A ticket to upload a new file's bytes into the run's space (POST them to the gateway's /stream-upload, which answers with the manifest)

Run token

Parameters · path

ridstringrequired

Responses

200
Upload ticket
UploadSession
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/plugin-runs/rid/upload" \
  -H "Authorization: Bearer $RUN_TOKEN"

Example response · 200

{
  "missing": [
    "missing"
  ],
  "ticket": "ticket",
  "blockgw_url": "blockgw_url",
  "expires_at": "2026-11-14T09:30:00Z"
}

POST/v1/plugin-runs/{rid}/complete

Finish a run the plugin answered with 202, with its result or an error

Run token

Parameters · path

ridstringrequired

Request bodyPluginResult application/json

sidecarsmap<string, any>
namespace → document, only namespaces the action declares
filesobject[]
› 3 fields
- pathstringrequired
- mimestring
- manifestManifestrequired
  › 3 fields
  - algostringrequired
    fastcdc-v1
  - sizeintegerrequired
  - chunksChunkRef[]required
    › 3 fields
    hashHashrequired
    ^[0-9a-f]{64}$
    offsetintegerrequired
    lenintegerrequired
errorstring
On complete: the run failed
retryboolean
With error: try another attempt

Responses

200
The run as recorded
Run
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/plugin-runs/rid/complete" \
  -H "Authorization: Bearer $RUN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sidecars":{"key":"string"},"files":[{"path":"Ep01/Shots/A001_C003.mov","manifest":{}}],"error":"error"}'

Example response · 200

{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "action": "action",
  "action_version": "action_version",
  "params": {},
  "pipeline_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "requested_by": "requested_by",
  "state": "queued",
  "attempts": 1,
  "progress": 0.5,
  "error": "error",
  "result": {
    "sidecars": {
      "key": "string"
    },
    "files": [
      {}
    ]
  },
  "cached": false,
  "created_at": "2026-11-14T09:30:00Z",
  "started_at": "2026-11-14T09:30:00Z",
  "finished_at": "2026-11-14T09:30:00Z"
}