API 参考

Developer

43 个接口 · 概览

GET/v1/openapi.yaml

This API description (no auth)

无需认证

响应

200
OpenAPI document
string

请求示例

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)

无需认证

响应

200
Operations
object

请求示例

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

响应示例 · 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)

无需认证

响应

200
Text
string

请求示例

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 令牌

响应

200
Tokens
object
› 展开字段
- itemsTokenInfo[]必填
  › 13 个字段
  - idstring必填
  - namestring必填
  - prefixstring必填
    The first characters of the secret, to tell tokens apart
  - userUser必填
    › 4 个字段
    idstring必填
    emailstring必填
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestring必填
    kindstring必填
    humanagent
  - scopesstring[]必填
  - space_idsstring[] | null必填
    null means every space
    必填
  - expires_atTimestamp | any必填
  - last_used_atTimestamp | any必填
  - created_atTimestamp必填
  - revoked_atTimestamp | any必填
  - 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

请求示例

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

响应示例 · 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 令牌

请求体 application/json

namestring必填
≤ 100 chars
scopesstring[]必填
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

响应

201
The token (shown once) and its details
object
› 展开字段
- tokenstring必填
- infoTokenInfo必填
  › 13 个字段
  - idstring必填
  - namestring必填
  - prefixstring必填
    The first characters of the secret, to tell tokens apart
  - userUser必填
    › 4 个字段
    idstring必填
    emailstring必填
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestring必填
    kindstring必填
    humanagent
  - scopesstring[]必填
  - space_idsstring[] | null必填
    null means every space
    必填
  - expires_atTimestamp | any必填
  - last_used_atTimestamp | any必填
  - created_atTimestamp必填
  - revoked_atTimestamp | any必填
  - 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

请求示例

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"]}'

响应示例 · 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 令牌

参数 · 路径

idstring必填

响应

204
Revoked
4xx/5xx
Error
Error

请求示例

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 令牌

响应

200
The token
TokenInfo
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

请求体 application/json

namestring必填
≤ 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

响应

201
The token (shown once) and its details
object
› 展开字段
- tokenstring必填
- infoTokenInfo必填
  › 13 个字段
  - idstring必填
  - namestring必填
  - prefixstring必填
    The first characters of the secret, to tell tokens apart
  - userUser必填
    › 4 个字段
    idstring必填
    emailstring必填
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestring必填
    kindstring必填
    humanagent
  - scopesstring[]必填
  - space_idsstring[] | null必填
    null means every space
    必填
  - expires_atTimestamp | any必填
  - last_used_atTimestamp | any必填
  - created_atTimestamp必填
  - revoked_atTimestamp | any必填
  - 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

请求示例

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"}'

响应示例 · 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 令牌

响应

200
Tokens
object
› 展开字段
- itemsTokenInfo[]必填
  › 13 个字段
  - idstring必填
  - namestring必填
  - prefixstring必填
    The first characters of the secret, to tell tokens apart
  - userUser必填
    › 4 个字段
    idstring必填
    emailstring必填
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestring必填
    kindstring必填
    humanagent
  - scopesstring[]必填
  - space_idsstring[] | null必填
    null means every space
    必填
  - expires_atTimestamp | any必填
  - last_used_atTimestamp | any必填
  - created_atTimestamp必填
  - revoked_atTimestamp | any必填
  - 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

请求示例

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

响应示例 · 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 令牌

参数 · 路径

idstring必填

响应

204
Revoked
4xx/5xx
Error
Error

请求示例

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 令牌

响应

200
Apps
object
› 展开字段
- itemsOAuthApp[]必填
  › 8 个字段
  - idstring必填
    The OAuth client_id
  - namestring必填
  - redirect_urisstring[]必填
  - client_uristring
  - logo_uristring
  - confidentialboolean必填
  - registeredboolean必填
    The app registered itself (RFC 7591)
  - created_atTimestamp必填
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

请求体 application/json

namestring必填
≤ 100 chars
redirect_urisstring[]必填
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

响应

201
The app (and its secret, once)
any
› 展开字段
- idstring必填
  The OAuth client_id
- namestring必填
- redirect_urisstring[]必填
- client_uristring
- logo_uristring
- confidentialboolean必填
- registeredboolean必填
  The app registered itself (RFC 7591)
- created_atTimestamp必填
- client_secretstring
4xx/5xx
Error
Error

请求示例

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"]}'

响应示例 · 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 令牌

参数 · 路径

idstring必填

响应

204
Deleted
4xx/5xx
Error
Error

请求示例

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

GET/v1/agents

Agents the caller made

Bearer 令牌

响应

200
Agents
object
› 展开字段
- itemsUser[]必填
  › 4 个字段
  - idstring必填
  - emailstring必填
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  - display_namestring必填
  - kindstring必填
    humanagent
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

请求体 application/json

namestring必填
≤ 100 chars

响应

201
The agent
User
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

idstring必填

响应

204
Retired
4xx/5xx
Error
Error

请求示例

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 令牌

参数 · 路径

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

响应

200
Subscriptions
object
› 展开字段
- itemsWebhook[]必填
  › 15 个字段
  - idstring必填
  - space_idstring必填
  - created_bystring必填
    The manager it speaks for; it stops if they stop being a manager
  - urlstring必填
    https (plain http and private addresses only on dev servers)
  - eventsstring[]必填
    Journal ops to send (node.created, version.created, sidecar.updated, …); empty = all
  - path_globstring必填
    Only paths matching, e.g. /dailies/** or **/*.mov; empty = all
  - mime_prefixstring必填
    Only files whose type starts with this, e.g. video/; empty = all
  - descriptionstring必填
  - activeboolean必填
  - disabled_reasonstring | null
    必填
  - cursor_seqinteger必填
    Last journal seq handled
  - attemptsinteger必填
    Failed tries of the next event
  - failing_sinceTimestamp | any
  - last_errorstring | null
    必填
  - created_atTimestamp必填
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

请求体WebhookRequest application/json

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

响应

201
Created
any
› 展开字段
- idstring必填
- space_idstring必填
- created_bystring必填
  The manager it speaks for; it stops if they stop being a manager
- urlstring必填
  https (plain http and private addresses only on dev servers)
- eventsstring[]必填
  Journal ops to send (node.created, version.created, sidecar.updated, …); empty = all
- path_globstring必填
  Only paths matching, e.g. /dailies/** or **/*.mov; empty = all
- mime_prefixstring必填
  Only files whose type starts with this, e.g. video/; empty = all
- descriptionstring必填
- activeboolean必填
- disabled_reasonstring | null
  必填
- cursor_seqinteger必填
  Last journal seq handled
- attemptsinteger必填
  Failed tries of the next event
- failing_sinceTimestamp | any
- last_errorstring | null
  必填
- created_atTimestamp必填
- secretstring必填
  whsec_…, the HMAC key
4xx/5xx
Error
Error

请求示例

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"}'

响应示例 · 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 令牌

参数 · 路径

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

请求体WebhookRequest application/json

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

响应

200
Updated
Webhook
4xx/5xx
Error
Error

请求示例

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"}'

响应示例 · 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 令牌

参数 · 路径

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

响应

204
Removed
4xx/5xx
Error
Error

请求示例

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 令牌

参数 · 路径

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

响应

200
Delivery
WebhookDelivery
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

请求体 application/json

from_seqinteger必填
≥ 0

响应

200
Rewound
Webhook
4xx/5xx
Error
Error

请求示例

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}'

响应示例 · 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 令牌

参数 · 路径

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

参数 · 查询

limitinteger
default 500 · ≥ 1 · ≤ 1000

响应

200
Deliveries
object
› 展开字段
- itemsWebhookDelivery[]必填
  › 9 个字段
  - idinteger必填
  - event_idstring必填
  - event_typestring必填
  - seqinteger | null
    必填
  - attemptinteger必填
  - statusinteger | null
    HTTP status; null when nothing answered
    必填
  - errorstring | null
    必填
  - duration_msinteger必填
  - created_atTimestamp必填
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

响应

200
Actions
object
› 展开字段
- itemsAction[]必填
  › 9 个字段
  - namestring必填
  - versionstring必填
    Changes when its output would; part of the cache key
  - titlestring必填
  - descriptionstring必填
  - acceptsstring[]必填
    MIME prefixes it takes, e.g. video/; empty = any file
  - writesstring[]必填
    Sidecar namespaces it writes, and "files" when it makes new files
  - params_schemaobject必填
    JSON Schema of its params
  - availableboolean必填
  - needsstring
    When not available: the setting the server lacks
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

参数 · 查询

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

响应

200
Runs
object
› 展开字段
- itemsRun[]必填
  › 18 个字段
  - idstring必填
  - space_idstring必填
  - node_idstring必填
  - version_idstring必填
    The version it works on; a newer save is a new run
  - actionstring必填
  - action_versionstring必填
  - paramsobject必填
    The params with defaults filled in
  - pipeline_idstring | null
    必填
  - requested_bystring必填
  - stateRunState必填
    queuedrunningdonefailedcanceled
  - attemptsinteger必填
    Tries so far; failures that may pass later retry up to 3 times
  - progressnumber | null
    ≥ 0 · ≤ 1
    必填
  - errorstring | null
    必填
  - resultobject | null
    必填
    › 2 个字段
    sidecarsmap<string, any>
    namespace → document written on the version
    filesobject[]
    › 4 个字段
    pathstring必填
    mimestring必填
    node_idstring
    version_idstring
  - cachedboolean必填
    The result was reused from the same bytes done before
  - created_atTimestamp必填
  - started_atTimestamp | any
  - finished_atTimestamp | any
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

请求体RunRequest application/json

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

响应

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

请求示例

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"}'

响应示例 · 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 令牌

参数 · 路径

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

响应

200
Run
Run
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

响应

200
Canceled
Run
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

响应

200
Pipelines
object
› 展开字段
- itemsPipeline[]必填
  › 14 个字段
  - idstring必填
  - space_idstring必填
  - created_bystring必填
    The manager it runs for; it stops if they stop being a manager
  - namestring必填
  - actionstring必填
  - paramsobject必填
  - path_globstring必填
    e.g. /dailies/** or **/*.mov; empty = all
  - mime_prefixstring必填
    e.g. video/; empty = what the action accepts
  - conditionsPipelineConditions
    › 7 个字段
    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
    必填
  - activeboolean必填
  - disabled_reasonstring | null
    必填
  - cursor_seqinteger必填
    Last journal seq looked at
  - created_atTimestamp必填
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

请求体PipelineRequest application/json

namestring
actionstring
paramsobject
path_globstring
mime_prefixstring
conditionsPipelineConditions
› 7 个字段
- 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

响应

201
Created
Pipeline
4xx/5xx
Error
Error

请求示例

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":{}}'

响应示例 · 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 令牌

参数 · 路径

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

请求体PipelineRequest application/json

namestring
actionstring
paramsobject
path_globstring
mime_prefixstring
conditionsPipelineConditions
› 7 个字段
- 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

响应

200
Updated
Pipeline
4xx/5xx
Error
Error

请求示例

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":{}}'

响应示例 · 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 令牌

参数 · 路径

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

响应

204
Removed
4xx/5xx
Error
Error

请求示例

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 令牌

参数 · 路径

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

响应

200
How many runs started
object
› 展开字段
- runsinteger必填
4xx/5xx
Error
Error

请求示例

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

响应示例 · 200

{
  "runs": 1
}

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

Ready-made rule sets (any member)

Bearer 令牌

参数 · 路径

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

响应

200
Templates
object
› 展开字段
- itemsPipelineTemplate[]必填
  › 4 个字段
  - idstring必填
  - titlestring必填
  - descriptionstring必填
  - pipelinesPipelineRequest[]必填
    › 8 个字段
    namestring
    actionstring
    paramsobject
    path_globstring
    mime_prefixstring
    conditionsPipelineConditions
    › 7 个字段
    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

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

请求体 application/json

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

响应

201
Created
object
› 展开字段
- itemsPipeline[]必填
  › 14 个字段
  - idstring必填
  - space_idstring必填
  - created_bystring必填
    The manager it runs for; it stops if they stop being a manager
  - namestring必填
  - actionstring必填
  - paramsobject必填
  - path_globstring必填
    e.g. /dailies/** or **/*.mov; empty = all
  - mime_prefixstring必填
    e.g. video/; empty = what the action accepts
  - conditionsPipelineConditions
    › 7 个字段
    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
    必填
  - activeboolean必填
  - disabled_reasonstring | null
    必填
  - cursor_seqinteger必填
    Last journal seq looked at
  - created_atTimestamp必填
- runsinteger必填
  Runs started by the backfill
4xx/5xx
Error
Error

请求示例

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}'

响应示例 · 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 令牌

参数 · 路径

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

响应

200
Plugins
object
› 展开字段
- itemsPlugin[]必填
  › 10 个字段
  - idstring必填
  - space_idstring必填
  - namestring必填
  - manifestPluginManifest必填
    › 9 个字段
    namestring必填
    Its actions are .
    ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
    titlestring
    descriptionstring
    versionstring必填
    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[]必填
    ≤ 50 items
    › 6 个字段
    namestring必填
    ^[a-z][a-z0-9_-]{0,40}$
    titlestring
    descriptionstring
    acceptsstring[]
    MIME prefixes; empty = any file
    writesstring[]必填
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
    params_schemaobject
    JSON Schema the params are checked against
  - endpointstring必填
  - created_bystring必填
  - activeboolean必填
  - disabled_reasonstring | null
    必填
  - created_atTimestamp必填
  - updated_atTimestamp必填
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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 令牌

参数 · 路径

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

请求体PluginRequest application/json

manifest_urlstring
manifestPluginManifest
› 9 个字段
- namestring必填
  Its actions are .
  ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
- titlestring
- descriptionstring
- versionstring必填
  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[]必填
  ≤ 50 items
  › 6 个字段
  - namestring必填
    ^[a-z][a-z0-9_-]{0,40}$
  - titlestring
  - descriptionstring
  - acceptsstring[]
    MIME prefixes; empty = any file
  - writesstring[]必填
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
  - params_schemaobject
    JSON Schema the params are checked against
activeboolean

响应

201
Installed
any
› 展开字段
- idstring必填
- space_idstring必填
- namestring必填
- manifestPluginManifest必填
  › 9 个字段
  - namestring必填
    Its actions are .
    ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
  - titlestring
  - descriptionstring
  - versionstring必填
    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[]必填
    ≤ 50 items
    › 6 个字段
    namestring必填
    ^[a-z][a-z0-9_-]{0,40}$
    titlestring
    descriptionstring
    acceptsstring[]
    MIME prefixes; empty = any file
    writesstring[]必填
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
    params_schemaobject
    JSON Schema the params are checked against
- endpointstring必填
- created_bystring必填
- activeboolean必填
- disabled_reasonstring | null
  必填
- created_atTimestamp必填
- updated_atTimestamp必填
- secretstring必填
  whsec_…, the HMAC key jobs are signed with
4xx/5xx
Error
Error

请求示例

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}'

响应示例 · 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 令牌

参数 · 路径

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

请求体PluginRequest application/json

manifest_urlstring
manifestPluginManifest
› 9 个字段
- namestring必填
  Its actions are .
  ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
- titlestring
- descriptionstring
- versionstring必填
  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[]必填
  ≤ 50 items
  › 6 个字段
  - namestring必填
    ^[a-z][a-z0-9_-]{0,40}$
  - titlestring
  - descriptionstring
  - acceptsstring[]
    MIME prefixes; empty = any file
  - writesstring[]必填
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
  - params_schemaobject
    JSON Schema the params are checked against
activeboolean

响应

200
Updated
Plugin
4xx/5xx
Error
Error

请求示例

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}'

响应示例 · 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 令牌

参数 · 路径

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

响应

204
Removed
4xx/5xx
Error
Error

请求示例

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.

无需认证

参数 · 查询

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

响应

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

请求示例

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

响应示例 · 200

{}

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

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

运行令牌

参数 · 路径

ridstring必填

请求体 application/json

progressnumber必填
≥ 0 · ≤ 1

响应

204
Recorded
4xx/5xx
Error
Error

请求示例

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)

运行令牌

参数 · 路径

ridstring必填

响应

200
Upload ticket
UploadSession
4xx/5xx
Error
Error

请求示例

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

响应示例 · 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

运行令牌

参数 · 路径

ridstring必填

请求体PluginResult application/json

sidecarsmap<string, any>
namespace → document, only namespaces the action declares
filesobject[]
› 3 个字段
- pathstring必填
- mimestring
- manifestManifest必填
  › 3 个字段
  - algostring必填
    fastcdc-v1
  - sizeinteger必填
  - chunksChunkRef[]必填
    › 3 个字段
    hashHash必填
    ^[0-9a-f]{64}$
    offsetinteger必填
    leninteger必填
errorstring
On complete: the run failed
retryboolean
With error: try another attempt

响应

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

请求示例

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"}'

响应示例 · 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"
}