SynapSynapDocs
Hub REST API

Capabilities

The Capabilities operations of the Hub REST API (14 operations).

For BuildersOpen-source podSynap CloudGenerated from Synap-core/backend@c31e261ab (main)

List the capability read-model (verb × grant × approval matrix)

GET
/capabilities

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

workspaceId?string
Formatuuid
intent?string
Match^[a-z][a-z0-9_]{0,63}$

Response Body

Capability read-model

application/json
  1. response
capabilities*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/capabilities'
Example Response
{  "capabilities": [    {      "property1": null,      "property2": null    }  ]}

List capability CONTAINERS (named bundles) the agent can discover

GET
/capabilities/containers

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

workspaceId?string
Formatuuid
query?string
intent?string
Match^[a-z][a-z0-9_]{0,63}$
limit?integer
Range0 < value

Response Body

Capability containers with their member parts

application/json
  1. response
capabilities*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/capabilities/containers'
Example Response
{  "capabilities": [    {      "property1": null,      "property2": null    }  ]}

Apply a capability template

POST
/capabilities/apply

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
definition?
templateKey?string
Match^[a-z0-9-]+$
Lengthlength <= 64
params?
workspaceId?string
Formatuuid

Response Body

Applied capability (created + proposed resources)

application/json
  1. response
capabilityKey*string
created*
proposals*array<string>
webhooks*array<>
Example Request
curl -X POST 'https://pod.example.com/api/hub/capabilities/apply' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "capabilityKey": "string",  "created": {    "vault": [      {        "property1": null,        "property2": null      }    ],    "mcpServers": [      {        "property1": null,        "property2": null      }    ],    "tools": [      {        "property1": null,        "property2": null      }    ],    "skills": [      {        "property1": null,        "property2": null      }    ],    "playbooks": [      {        "property1": null,        "property2": null      }    ],    "automations": [      {        "property1": null,        "property2": null      }    ]  },  "proposals": [    "string"  ],  "webhooks": [    {      "property1": null,      "property2": null    }  ]}

Reconcile installed capabilities to their Control-Plane templates

POST
/capabilities/reconcile

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
dryRun?boolean

Response Body

Reconcile report

application/json
  1. response
checked*number
dryRun*boolean
applied*array<>
skipped*array<>
updatesAvailable*array<>
conflicts*array<>
Example Request
curl -X POST 'https://pod.example.com/api/hub/capabilities/reconcile' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "checked": 0,  "dryRun": true,  "applied": [    {      "containerId": "string",      "name": "string",      "templateKey": "string",      "reason": "string"    }  ],  "skipped": [    {      "containerId": "string",      "name": "string",      "templateKey": "string",      "reason": "string"    }  ],  "updatesAvailable": [    {      "containerId": "string",      "name": "string",      "templateKey": "string",      "reason": "string"    }  ],  "conflicts": [    {      "containerId": "string",      "name": "string",      "templateKey": "string",      "reason": "string"    }  ]}

Reconcile standalone-installed views/skills/automations to their templates

POST
/configs/reconcile

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
dryRun?boolean

Response Body

Reconcile report

application/json
  1. response
checked*number
dryRun*boolean
updated*array<>
ownerOwnedSkipped*array<>
skipped*array<>
conflicts*array<>
Example Request
curl -X POST 'https://pod.example.com/api/hub/configs/reconcile' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "checked": 0,  "dryRun": true,  "updated": [    {      "kind": "view",      "id": "string",      "name": "string",      "packageSlug": "string",      "reason": "string"    }  ],  "ownerOwnedSkipped": [    {      "kind": "view",      "id": "string",      "name": "string",      "packageSlug": "string",      "reason": "string"    }  ],  "skipped": [    {      "kind": "view",      "id": "string",      "name": "string",      "packageSlug": "string",      "reason": "string"    }  ],  "conflicts": [    {      "kind": "view",      "id": "string",      "name": "string",      "packageSlug": "string",      "reason": "string"    }  ]}

Detach a view/skill/automation from its marketplace template

POST
/configs/detach

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
kind*string
Value in"view""skill""automation"
id*string
Formatuuid

Response Body

Detach result

application/json
  1. response
detached*boolean
kind*string
Value in"view""skill""automation"
id*string
outcome?string
Value in"updated""proposed"
reason?string
Example Request
curl -X POST 'https://pod.example.com/api/hub/configs/detach' \  -H 'Content-Type: application/json' \  -d '{  "kind": "view",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"}'
Example Response
{  "detached": true,  "kind": "view",  "id": "string",  "outcome": "updated",  "reason": "string"}

Delete a capability container by id (member parts untouched)

DELETE
/capabilities/containers/{id}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

id*string
Formatuuid

Response Body

Deleted

application/json
  1. response
ok*boolean
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/capabilities/containers/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "ok": true}

Pack-grouped, status-computed capability catalog (one row per pack)

GET
/capabilities/catalog

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

workspaceId*string
Formatuuid
key?string

Response Body

Capability catalog (pack cards)

application/json
  1. response
capabilities*array<>
automations*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/capabilities/catalog?workspaceId=497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "capabilities": [    {      "id": "string",      "key": "string",      "name": "string",      "description": "string",      "source": "installed",      "status": "available",      "connection": {        "required": true,        "kind": "provider",        "provider": "string",        "state": "connected",        "account": "string",        "internal": true,        "unverified": {          "reason": "string",          "message": "string"        }      },      "verbs": [        {          "verbId": "string",          "skillId": "string",          "label": "string",          "description": "string",          "type": "read",          "enabled": true,          "governance": "auto",          "runnable": true,          "params": [            "string"          ],          "paramsSchema": [            {              "name": "string",              "type": "string",              "required": true,              "description": "string"            }          ],          "category": "string",          "intent": "string"        }      ],      "anatomy": {        "tools": [          "string"        ],        "skills": [          "string"        ],        "credential": "string"      },      "installParams": [        {          "name": "string",          "label": "string",          "type": "string",          "required": true,          "description": "string",          "secret": true        }      ],      "builtIn": true,      "nextAction": {        "kind": "add",        "hint": "string",        "url": "string",        "opensIn": "web"      }    }  ],  "automations": [    {      "kind": "automation",      "id": "string",      "key": "string",      "name": "string",      "description": "string",      "source": "installed",      "status": "available",      "lifecycle": "draft",      "triggerType": "event",      "nextAction": {        "kind": "add",        "hint": "string"      }    }  ]}

List only actions an external AI can execute now

GET
/capabilities/actions

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

workspaceId*string
Formatuuid
query?string
kind?string
intent?string
Match^[a-z][a-z0-9_]{0,63}$
limit?integer
Range0 < value <= 100

Response Body

Runnable actions

application/json
  1. response
actions*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/capabilities/actions?workspaceId=497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "actions": [    {      "skillId": "string",      "verbId": "string",      "label": "string",      "description": "string",      "tool": "string",      "connection": {        "required": true,        "state": "connected",        "provider": "string"      },      "governance": "auto",      "enabled": true,      "executionMode": "string",      "kind": "read",      "intent": "string",      "parameters": {        "property1": null,        "property2": null      }    }  ]}

Execute a registered capability (agnostic capability launcher)

POST
/capabilities/execute

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
verbId?string

The capability verb to run — the backing skill's NAME (e.g. 'gmail_send'). One of verbId/skillId is required.

Length1 <= length
skillId?string

Direct backing-skill id (alternative to verbId).

Length1 <= length
parameters?

The capability's own inputs, passed to the skill sandbox as args — e.g. { to, subject, body } for gmail_send.

workspaceId?string

Acting workspace — an optional lens narrowing the skill lookup and the gate. Omit for a pod-wide run.

Formatuuid
connectionSelector?

Which of the capability's connections this run uses, when it has more than one. A selector matching nothing fails the run.

idempotencyKey?string

A stable key correlating retries of THIS logical run, so an external-send verb is at-most-once. Omitted → a content hash is derived.

Length1 <= length
channelId?string

Instruction-provenance: the acting channel of this agent turn. A run triggered from an untrusted-origin channel force-proposes instead of auto-running.

sourceMessageId?string

The triggering inbound message id, resolved server-side to the acting channel when channelId is not passed explicitly.

sessionId?string

The focus session this run belongs to. Persisted as the proposals.session_id column so a reviewer sees which operation the action was part of.

Response Body

Execution result

application/json
  1. response
status*string
Value in"run""dry-run"
skillId*string
result?unknown
dryRun?boolean
correlationId?string
ackState?string
Value in"applied""proposed""duplicate-ignored"
Example Request
curl -X POST 'https://pod.example.com/api/hub/capabilities/execute' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "status": "run",  "skillId": "string",  "result": null,  "dryRun": true,  "correlationId": "string",  "ackState": "applied"}

List a capability's credentials

GET
/capabilities/{capabilityId}/credentials

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

capabilityId*string
Formatuuid

Response Body

Credentials

application/json
  1. response
credentials*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/capabilities/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials'
Example Response
{  "credentials": [    {      "id": "string",      "label": "string",      "contextType": "string",      "contextId": "string",      "isDefault": true,      "accountHint": "string",      "kind": "nango",      "isPodWide": true,      "provider": "string",      "health": "connected",      "persisted": true    }  ]}

Add a credential to a capability

POST
/capabilities/{capabilityId}/credentials

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

capabilityId*string
Formatuuid

Request Body

application/json
  1. body
label*string
Length1 <= length <= 255
value?string
contextType?string|null
contextId?string|null
accountHint?string|null
isDefault?boolean
isPodWide?boolean

Response Body

Created credential

application/json
  1. response
id*string
label*string
contextType*string|null
contextId*string|null
isDefault*boolean
accountHint*string|null
kind*string
Value in"nango""vault"
isPodWide*boolean
provider*string|null
health*string
Value in"connected""needs_reauth"
persisted*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/capabilities/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials' \  -H 'Content-Type: application/json' \  -d '{  "label": "string"}'
Example Response
{  "id": "string",  "label": "string",  "contextType": "string",  "contextId": "string",  "isDefault": true,  "accountHint": "string",  "kind": "nango",  "isPodWide": true,  "provider": "string",  "health": "connected",  "persisted": true}

Update a capability credential

PATCH
/capabilities/{capabilityId}/credentials/{id}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

capabilityId*string
Formatuuid
id*string
Formatuuid

Request Body

application/json
  1. body
label?string
Length1 <= length <= 255
value?string
contextType?string|null
contextId?string|null
accountHint?string|null
isDefault?boolean
isPodWide?boolean

Response Body

Updated credential

application/json
  1. response
id*string
label*string
contextType*string|null
contextId*string|null
isDefault*boolean
accountHint*string|null
kind*string
Value in"nango""vault"
isPodWide*boolean
provider*string|null
health*string
Value in"connected""needs_reauth"
persisted*boolean
Example Request
curl -X PATCH 'https://pod.example.com/api/hub/capabilities/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "label": "string",  "contextType": "string",  "contextId": "string",  "isDefault": true,  "accountHint": "string",  "kind": "nango",  "isPodWide": true,  "provider": "string",  "health": "connected",  "persisted": true}

Remove a capability credential

DELETE
/capabilities/{capabilityId}/credentials/{id}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

capabilityId*string
Formatuuid
id*string
Formatuuid

Response Body

Removed

application/json
  1. response
ok*boolean
promotedDefaultId*string|null
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/capabilities/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "ok": true,  "promotedDefaultId": "string"}

Calendar

The Calendar operations of the Hub REST API (4 operations).

Capture

The Capture operations of the Hub REST API (3 operations).