SynapSynapDocs
Hub REST API

Channels

The Channels operations of the Hub REST API (8 operations).

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

List/search channels

GET
/channels

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

userId?string
workspaceId?string
channelType?string
contextObjectId?string
q?string

Free-text search over channel title / branch purpose.

limit?string
offset?string

Zero-based offset for cursor-free pagination (default 0).

Response Body

Channel list

application/json
  1. response
channels*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/channels'
Example Response
{  "channels": [    {      "id": "string",      "title": "string",      "type": "string",      "family": "string",      "userId": "string",      "workspaceId": "string",      "contextObjectId": "string",      "contextObjectType": "string",      "agentId": "string",      "createdAt": "string",      "updatedAt": "string",      "property1": null,      "property2": null    }  ]}
POST
/channels

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
workspaceId?string
externalSource*string
Length1 <= length
externalChannelId*string
Length1 <= length
contextObjectId?string
contextObjectType?string
Value in"entity""document""view""proposal"
title?string
parentChannelId?string
branchPurpose?string
relink?boolean
metadata?

Response Body

Created-or-linked channel

application/json
  1. response
channelId*string
created*boolean
linked*boolean
channel*
Example Request
curl -X POST 'https://pod.example.com/api/hub/channels' \  -H 'Content-Type: application/json' \  -d '{  "externalSource": "string",  "externalChannelId": "string"}'
Example Response
{  "channelId": "string",  "created": true,  "linked": true,  "channel": {    "id": "string",    "title": "string",    "type": "string",    "family": "string",    "userId": "string",    "workspaceId": "string",    "contextObjectId": "string",    "contextObjectType": "string",    "agentId": "string",    "createdAt": "string",    "updatedAt": "string",    "property1": null,    "property2": null  }}

Find or create a channel by context object

POST
/channels/by-context

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
userId*string
workspaceId?string
contextObjectId*string
contextObjectType*string
Value in"entity""document""view"

Response Body

Resolved channel

application/json
  1. response
channelId*string
title?string|null
created*boolean
channel*
Example Request
curl -X POST 'https://pod.example.com/api/hub/channels/by-context' \  -H 'Content-Type: application/json' \  -d '{  "userId": "string",  "contextObjectId": "string",  "contextObjectType": "entity"}'
Example Response
{  "channelId": "string",  "title": "string",  "created": true,  "channel": {    "id": "string",    "title": "string",    "type": "string",    "family": "string",    "userId": "string",    "workspaceId": "string",    "contextObjectId": "string",    "contextObjectType": "string",    "agentId": "string",    "createdAt": "string",    "updatedAt": "string",    "property1": null,    "property2": null  }}

Get the user's personal channel

GET
/channels/personal

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

userId*string
workspaceId*string

Response Body

Channel

application/json
  1. response
id*string
title?string|null
type?string
family?string
userId?string|null
workspaceId?string|null
contextObjectId?string|null
contextObjectType?string|null
agentId?string|null
createdAt?string|
updatedAt?string|
[key: string]?unknown
Example Request
curl -X GET 'https://pod.example.com/api/hub/channels/personal?userId=string&workspaceId=string'
Example Response
{  "id": "string",  "title": "string",  "type": "string",  "family": "string",  "userId": "string",  "workspaceId": "string",  "contextObjectId": "string",  "contextObjectType": "string",  "agentId": "string",  "createdAt": "string",  "updatedAt": "string",  "property1": null,  "property2": null}

Trigger an AI response in a channel

POST
/channels/trigger-ai

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
channelId*string
userId*string
workspaceId*string
systemPromptOverride*string
skillId?string
entityId?string

Entity to inject as context for the AI response.

Response Body

Trigger result (varies by skill/agent)

application/json
  1. response
[key: string]?unknown
Example Request
curl -X POST 'https://pod.example.com/api/hub/channels/trigger-ai' \  -H 'Content-Type: application/json' \  -d '{  "channelId": "string",  "userId": "string",  "workspaceId": "string",  "systemPromptOverride": "string"}'
Example Response
{  "property1": null,  "property2": null}

Pin a message in a Discord channel

POST
/channels/:externalChannelId/pins/:messageId

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.

Response Body

Queued

application/json
  1. response
ok*true
Value intrue
queued*true
Value intrue
Example Request
curl -X POST 'https://pod.example.com/api/hub/channels/:externalChannelId/pins/:messageId'
Example Response
{  "ok": true,  "queued": true}

Rename a Discord channel

POST
/channels/:externalChannelId/rename

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
name*string
Length1 <= length <= 100
provider?string

Response Body

Queued

application/json
  1. response
ok*true
Value intrue
queued*true
Value intrue
Example Request
curl -X POST 'https://pod.example.com/api/hub/channels/:externalChannelId/rename' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
{  "ok": true,  "queued": true}

Propose binding a channel to a context object

POST
/channels/:channelId/bind

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
userId*string
workspaceId?string
Formatuuid
contextObjectId*string
Formatuuid
contextObjectType?string
Value in"entity""document""view"
branchPurpose?string
Lengthlength <= 500
externalChannelId?string
reasoning?string

Response Body

Proposed / approved / denied

application/json
  1. response
status*string
[key: string]?unknown
Example Request
curl -X POST 'https://pod.example.com/api/hub/channels/:channelId/bind' \  -H 'Content-Type: application/json' \  -d '{  "userId": "string",  "contextObjectId": "5e68e661-1d3e-4197-ae71-923240fce5b9"}'
Example Response
{  "status": "string",  "property1": null,  "property2": null}

Capture

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

Commands

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