SynapSynapDocs
Hub REST API

Workspaces

The Workspaces operations of the Hub REST API (12 operations).

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

List accessible workspaces

GET
/workspaces

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

Workspaces accessible to the authenticated user

application/json
  1. response
workspaces*array<>
podEntityCount?number

Count of pod-scoped entities (workspaceId = null).

Example Request
curl -X GET 'https://pod.example.com/api/hub/workspaces'
Example Response
{  "workspaces": [    {      "id": "string",      "name": "string",      "entityCount": 0,      "usedByProjectIds": [        "string"      ],      "provisioningStatus": "string",      "failedStep": "string",      "failedStepError": "string"    }  ],  "podEntityCount": 0}

Get a workspace by id

GET
/workspaces/{workspaceId}

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

Workspace

Example Request
curl -X GET 'https://pod.example.com/api/hub/workspaces/{workspaceId}'
Example Response
Empty

Read Eve provider routing policy

GET
/workspaces/{workspaceId}/eve-provider-routing

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

workspaceId*string

Response Body

Provider routing policy

application/json
  1. response
ok*boolean
workspaceId*string
eveProviderRouting*|null
Example Request
curl -X GET 'https://pod.example.com/api/hub/workspaces/string/eve-provider-routing'
Example Response
{  "ok": true,  "workspaceId": "string",  "eveProviderRouting": {    "mode": "local",    "defaultProvider": "ollama",    "fallbackProvider": "ollama",    "providers": [      {        "id": "ollama",        "enabled": true,        "baseUrl": "string",        "defaultModel": "string"      }    ],    "syncToSynap": true  }}

Update Eve provider routing policy

PATCH
/workspaces/{workspaceId}/eve-provider-routing

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

workspaceId*string

Request Body

application/json
  1. body
mode?string
Value in"local""provider""hybrid"
defaultProvider?string
Value in"ollama""openrouter""anthropic""openai"
fallbackProvider?string
Value in"ollama""openrouter""anthropic""openai"
providers?array<>
syncToSynap?boolean

Response Body

Updated policy

application/json
  1. response
ok*boolean
workspaceId*string
eveProviderRouting*|null
Example Request
curl -X PATCH 'https://pod.example.com/api/hub/workspaces/string/eve-provider-routing' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "ok": true,  "workspaceId": "string",  "eveProviderRouting": {    "mode": "local",    "defaultProvider": "ollama",    "fallbackProvider": "ollama",    "providers": [      {        "id": "ollama",        "enabled": true,        "baseUrl": "string",        "defaultModel": "string"      }    ],    "syncToSynap": true  }}

Declare workspace data edges (sourceRoles / defaultSources)

PATCH
/workspaces/{workspaceId}/source-edges

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

workspaceId*string

Request Body

application/json
  1. body
sourceRoles?
defaultSources?

Response Body

Merged edge fields

application/json
  1. response
[key: string]?unknown
Example Request
curl -X PATCH 'https://pod.example.com/api/hub/workspaces/string/source-edges' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "property1": null,  "property2": null}

Set workspace public-projection config

PATCH
/workspaces/{workspaceId}/public-projection

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

workspaceId*string

Request Body

application/json
  1. body
enabled*boolean
roles*array<string>
fields?array<string>

Response Body

Applied public-projection config

application/json
  1. response
[key: string]?unknown
Example Request
curl -X PATCH 'https://pod.example.com/api/hub/workspaces/string/public-projection' \  -H 'Content-Type: application/json' \  -d '{  "enabled": true,  "roles": [    "string"  ]}'
Example Response
{  "property1": null,  "property2": null}

Read workspace governance policy

GET
/workspaces/{workspaceId}/governance

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

workspaceId*string

Response Body

Governance policy

application/json
  1. response
[key: string]?unknown
Example Request
curl -X GET 'https://pod.example.com/api/hub/workspaces/string/governance'
Example Response
{  "property1": null,  "property2": null}

Workspace data digest

GET
/workspaces/{workspaceId}/digest

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

workspaceId*string

Response Body

Workspace digest

application/json
  1. response
[key: string]?unknown
Example Request
curl -X GET 'https://pod.example.com/api/hub/workspaces/string/digest'
Example Response
{  "property1": null,  "property2": null}

Get a user's context

GET
/users/{userId}/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.

Path Parameters

userId*string

Response Body

User context

application/json
  1. response
[key: string]?unknown
Example Request
curl -X GET 'https://pod.example.com/api/hub/users/string/context'
Example Response
{  "property1": null,  "property2": null}

Enroll an agent user into the caller's workspaces

POST
/workspaces/enroll-agent

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
agentUserId*string
Formatuuid
workspaceId?string
Formatuuid
role?string
Value in"viewer""editor""admin"

Response Body

List of workspace IDs the agent was enrolled into

application/json
  1. response
enrolled*array<string>
skipped*array<string>
Example Request
curl -X POST 'https://pod.example.com/api/hub/workspaces/enroll-agent' \  -H 'Content-Type: application/json' \  -d '{  "agentUserId": "f9abe370-14d5-447c-8b38-a304830fd620"}'
Example Response
{  "enrolled": [    "string"  ],  "skipped": [    "string"  ]}

Provision an agent-owned workspace (idempotent)

POST
/workspaces/provision-agent

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
agentUserId*string
Formatuuid
workspaceName?string
idempotencyKey?string

Response Body

Workspace id and creation outcome

application/json
  1. response
workspaceId*string
created*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/workspaces/provision-agent' \  -H 'Content-Type: application/json' \  -d '{  "agentUserId": "f9abe370-14d5-447c-8b38-a304830fd620"}'
Example Response
{  "workspaceId": "string",  "created": true}

Create a workspace from a WorkspaceProposal definition

POST
/workspaces/from-definition

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
proposalId?string
Length1 <= length
workspaceName?string
templateId?string
templateName?string
workspaceType?string
Value in"personal""agent""project""operational"
ownerUserId?string
[key: string]?unknown

Response Body

Workspace id and creation outcome

application/json
  1. response
workspaceId*string
created*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/workspaces/from-definition' \  -H 'Content-Type: application/json' \  -d '{  "property1": null,  "property2": null}'
Example Response
{  "workspaceId": "string",  "created": true}

Workflows

The Workflows operations of the Hub REST API (2 operations).