SynapSynapDocs
Hub REST API

Tools

The Tools operations of the Hub REST API (11 operations).

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

List tools

GET
/tools

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
limit?string

Response Body

Tool list

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

Create a tool (capability substrate)

POST
/tools

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 <= 255
kind*string
Value in"builtin""api""mcp""provider""external""script"
description?string
inputSchema?
credentialRef?string
executor?string
Value in"is-agent""external-agent""hybrid"
config?
workspaceId?string
Formatuuid
agentUserId?string
Formatuuid
source?string
reasoning?string

Response Body

Created or proposed tool

application/json
  1. response
tool*|null
status*string
Value in"created""proposed"
proposalId*string|null
Example Request
curl -X POST 'https://pod.example.com/api/hub/tools' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "kind": "builtin"}'
Example Response
{  "tool": {    "id": "string",    "name": "string",    "kind": "string"  },  "status": "created",  "proposalId": "string"}

Get a tool and the skills that require it

GET
/tools/{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

Tool + requiring skills

application/json
  1. response
tool*
skills*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "tool": {    "property1": null,    "property2": null  },  "skills": [    {      "property1": null,      "property2": null    }  ]}

Update a tool (capability substrate)

PATCH
/tools/{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

Request Body

application/json
  1. body
name?string
Length1 <= length <= 255
description?string
credentialRef?string
config?
metadata?
executor?string
Value in"is-agent""external-agent""hybrid"
kind?string
Value in"builtin""api""mcp""provider""external""script"
inputSchema?
status?string
Value in"active""inactive""error"

Response Body

Updated or proposed tool

application/json
  1. response
tool*|null
status*string
Value in"updated""proposed"
proposalId*string|null
Example Request
curl -X PATCH 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "tool": {    "id": "string",    "name": "string",    "kind": "string"  },  "status": "updated",  "proposalId": "string"}

Delete a tool (capability substrate)

DELETE
/tools/{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 or proposed

application/json
  1. response
status*string
Value in"deleted""proposed"
proposalId*string|null
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "status": "deleted",  "proposalId": "string"}

Mint or return a tool's inbound webhook URL

POST
/tools/{id}/webhook

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

Request Body

application/json
  1. body
rotate?boolean

Response Body

The webhook URL

application/json
  1. response
provider*string
url*string
rotated*boolean
missingConfig*array<string>
setupStep*string|null
Example Request
curl -X POST 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08/webhook' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "provider": "string",  "url": "string",  "rotated": true,  "missingConfig": [    "string"  ],  "setupStep": "string"}

Approve or revoke a tool's execution

POST
/tools/{id}/approve

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

Request Body

application/json
  1. body
approved?boolean
Defaulttrue

Response Body

Updated approval state

application/json
  1. response
id*string
approved*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08/approve' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "approved": true}

Set a tool's dynamic auth binding

POST
/tools/{id}/auth-binding

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

Request Body

application/json
  1. body
authBinding*string
Value in"static""per_user""per_agent""per_entity"

Response Body

Updated auth binding

application/json
  1. response
tool*
Example Request
curl -X POST 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08/auth-binding' \  -H 'Content-Type: application/json' \  -d '{  "authBinding": "static"}'
Example Response
{  "tool": {    "id": "string",    "name": "string",    "kind": "string"  }}

List bound credentials for a tool

GET
/tools/{id}/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

id*string
Formatuuid

Response Body

Bound credential list

application/json
  1. response
credentials*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials'
Example Response
{  "credentials": [    {      "linkId": "string",      "principalType": "string",      "principalId": "string",      "secretId": "string"    }  ]}

Bind a credential to a principal/entity for a tool

POST
/tools/{id}/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

id*string
Formatuuid

Request Body

application/json
  1. body
principalType*string
Value in"participant""entity"
principalId*string
Length1 <= length
secretId*string
Formatuuid

Response Body

Bound credential link

application/json
  1. response
linkId*string|null
Example Request
curl -X POST 'https://pod.example.com/api/hub/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials' \  -H 'Content-Type: application/json' \  -d '{  "principalType": "participant",  "principalId": "string",  "secretId": "c39edb4b-1d7b-4287-b1be-9dcaba334a25"}'
Example Response
{  "linkId": "string"}

Unbind a credential from a tool

DELETE
/tools/{id}/credentials/{linkId}

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
linkId*string
Formatuuid

Response Body

Credential unbound

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

Threads

The Threads operations of the Hub REST API (10 operations).

UI

The UI operations of the Hub REST API (1 operation).