SynapSynapDocs
Hub REST API

FocusSessions

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

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

List focus sessions for a workspace or a project

GET
/focus-sessions

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
projectId?string
status?string
Value in"active""paused""forming""scheduled""closed""failed""cancelled""stale""all"
lens?string
Value in"default""triage""all"
kind?string
Value in"work""run""receipt""all"
playbookId?string
Formatuuid
automationId?string
Formatuuid
subjectEntityId?string
Formatuuid
subjectProfileSlug?string
Length1 <= length
limit?integer
Range1 <= value <= 50

Response Body

Sessions

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://pod.example.com/api/hub/focus-sessions'
Example Response
[  {    "id": "string",    "workspaceId": "string",    "projectId": "string",    "userId": "string",    "correlationId": "string",    "title": "string",    "goal": "string",    "status": "string",    "templateId": "string",    "expectedOutputs": null,    "channelId": "string",    "progress": 0,    "currentStage": "string",    "agentIds": [      "string"    ],    "closedAt": "string",    "verificationReport": null,    "metadata": null,    "startedAt": "string",    "createdAt": "string",    "updatedAt": "string",    "kind": "work"  }]

Create a focus session

POST
/focus-sessions

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
Match^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
Formatuuid
projectId?string
Length1 <= length
trackId?string
Formatuuid
trackStage?string
Length1 <= length <= 120
userId*string
Length1 <= length
title?string
Lengthlength <= 200
goal*string
Length1 <= length <= 2000
correlationId?string
templateId?string|null
params?
outcomes?array<>
Itemsitems <= 40
expectedOutputs?array<>
criteria?array<unknown>
channelId?string
Formatuuid
agentIds?array<string>
subjectEntityId?string
Formatuuid
parentSessionId?string
Formatuuid
suspendedIntent?string
Length1 <= length <= 2000
blockedBySessionIds?array<>
Itemsitems <= 20
forceCreate?boolean

Response Body

Created or existing session

application/json
  1. response
id*string
workspaceId*string|null
projectId*string|null
userId*string
correlationId*string|null
title*string|null
goal*string
status*string
templateId*string|null
expectedOutputs?unknown
channelId*string|null
progress*number|null
currentStage*string|null
agentIds*array<string>
closedAt*string|null
verificationReport?unknown
metadata?unknown
startedAt*string
createdAt*string
updatedAt*string
kind?string
Value in"work""run""receipt"
Example Request
curl -X POST 'https://pod.example.com/api/hub/focus-sessions' \  -H 'Content-Type: application/json' \  -d '{  "userId": "string",  "goal": "string"}'
Example Response
{  "id": "string",  "workspaceId": "string",  "projectId": "string",  "userId": "string",  "correlationId": "string",  "title": "string",  "goal": "string",  "status": "string",  "templateId": "string",  "expectedOutputs": null,  "channelId": "string",  "progress": 0,  "currentStage": "string",  "agentIds": [    "string"  ],  "closedAt": "string",  "verificationReport": null,  "metadata": null,  "startedAt": "string",  "createdAt": "string",  "updatedAt": "string",  "kind": "work"}

Get a focus session by ID

GET
/focus-sessions/: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

Query Parameters

workspaceId?string

Response Body

Session

application/json
  1. response
id*string
workspaceId*string|null
projectId*string|null
userId*string
correlationId*string|null
title*string|null
goal*string
status*string
templateId*string|null
expectedOutputs?unknown
channelId*string|null
progress*number|null
currentStage*string|null
agentIds*array<string>
closedAt*string|null
verificationReport?unknown
metadata?unknown
startedAt*string
createdAt*string
updatedAt*string
kind?string
Value in"work""run""receipt"
Example Request
curl -X GET 'https://pod.example.com/api/hub/focus-sessions/:id'
Example Response
{  "id": "string",  "workspaceId": "string",  "projectId": "string",  "userId": "string",  "correlationId": "string",  "title": "string",  "goal": "string",  "status": "string",  "templateId": "string",  "expectedOutputs": null,  "channelId": "string",  "progress": 0,  "currentStage": "string",  "agentIds": [    "string"  ],  "closedAt": "string",  "verificationReport": null,  "metadata": null,  "startedAt": "string",  "createdAt": "string",  "updatedAt": "string",  "kind": "work"}

Update a focus session

PATCH
/focus-sessions/: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
workspaceId?string
Match^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
Formatuuid
status?string
Value in"active""paused""forming""scheduled""closed""failed""cancelled"
progress?integer
Range0 <= value <= 100
channelId?string
Formatuuid
correlationId?string
title?|
Lengthlength <= 200
goal?string
Length1 <= length <= 2000
agentIds?array<string>
addAgentId?string
Length1 <= length
outcomes?array<>
Itemsitems <= 40
expectedOutputs?array<>
verificationReport?unknown
currentStage?string
Length1 <= length
subjectEntityId?|
Formatuuid
metadata?
criteria?array<>
Itemsitems <= 12
followPlaybookId?|
Formatuuid
followStageKey?|
Length1 <= length
params?
trackId?|
Formatuuid
trackStage?|
Length1 <= length <= 120
agentUserId?string
Formatuuid
reasoning?string

Response Body

Updated session

application/json
  1. response
id*string
workspaceId*string|null
projectId*string|null
userId*string
correlationId*string|null
title*string|null
goal*string
status*string
templateId*string|null
expectedOutputs?unknown
channelId*string|null
progress*number|null
currentStage*string|null
agentIds*array<string>
closedAt*string|null
verificationReport?unknown
metadata?unknown
startedAt*string
createdAt*string
updatedAt*string
kind?string
Value in"work""run""receipt"
Example Request
curl -X PATCH 'https://pod.example.com/api/hub/focus-sessions/:id' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "workspaceId": "string",  "projectId": "string",  "userId": "string",  "correlationId": "string",  "title": "string",  "goal": "string",  "status": "string",  "templateId": "string",  "expectedOutputs": null,  "channelId": "string",  "progress": 0,  "currentStage": "string",  "agentIds": [    "string"  ],  "closedAt": "string",  "verificationReport": null,  "metadata": null,  "startedAt": "string",  "createdAt": "string",  "updatedAt": "string",  "kind": "work"}

Complete (close) a focus session and return the proposal pack

POST
/focus-sessions/:id/complete

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
summary?string
verificationReport?
terminalStatus?string
Value in"closed""cancelled""failed"

Response Body

Closed session + proposal pack

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

Record an existing object as a session output

POST
/focus-sessions/:id/outputs

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
kind*string
Value in"view""cell""document""entity""url""automation""playbook"
refId*string
Length1 <= length
label?string
Length1 <= length <= 500
expectedLabel?string
Length1 <= length <= 500
workspaceId?string
Formatuuid

Response Body

Recorded

application/json
  1. response
ok*boolean
outputId*string
Example Request
curl -X POST 'https://pod.example.com/api/hub/focus-sessions/:id/outputs' \  -H 'Content-Type: application/json' \  -d '{  "kind": "view",  "refId": "string"}'
Example Response
{  "ok": true,  "outputId": "string"}

Hand a declared deliverable to an agent

POST
/focus-sessions/:id/outputs/delegate

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
expectedLabel*string
Length1 <= length <= 500
agentType?string
Length1 <= length <= 100

Response Body

Delegated

application/json
  1. response
ok*boolean
expectedLabel*string
kind*string
agentType*string
channelId*string
messageId*string
triggered*boolean
agentAttached*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/focus-sessions/:id/outputs/delegate' \  -H 'Content-Type: application/json' \  -d '{  "expectedLabel": "string"}'
Example Response
{  "ok": true,  "expectedLabel": "string",  "kind": "string",  "agentType": "string",  "channelId": "string",  "messageId": "string",  "triggered": true,  "agentAttached": true}

Hand a declared deliverable to the human

POST
/focus-sessions/:id/outputs/block

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
expectedLabel*string
Length1 <= length <= 500
blockedReason*string
Value in"credential""permission""capability""policy""decision""physical"
why?string
Lengthlength <= 500
ref?||null
ask?|||||null

Response Body

Blocked on the human

application/json
  1. response
ok*boolean
expectedLabel*string
kind*string
blockGuidelines?unknown
Example Request
curl -X POST 'https://pod.example.com/api/hub/focus-sessions/:id/outputs/block' \  -H 'Content-Type: application/json' \  -d '{  "expectedLabel": "string",  "blockedReason": "credential"}'
Example Response
{  "ok": true,  "expectedLabel": "string",  "kind": "string",  "blockGuidelines": null}

Reclaim a deliverable handed to the human

POST
/focus-sessions/:id/outputs/unblock

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
expectedLabel*string
Length1 <= length <= 500

Response Body

Reclaimed

application/json
  1. response
ok*boolean
expectedLabel*string
kind*string
Example Request
curl -X POST 'https://pod.example.com/api/hub/focus-sessions/:id/outputs/unblock' \  -H 'Content-Type: application/json' \  -d '{  "expectedLabel": "string"}'
Example Response
{  "ok": true,  "expectedLabel": "string",  "kind": "string"}

Answer what an agent asked about a deliverable (people only)

POST
/focus-sessions/:id/outputs/answer

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
expectedLabel*string
Length1 <= length <= 500
text?string
Lengthlength <= 4000
value?||||
askFingerprint?string
Length1 <= length <= 64
expectedGranteeId?string
Length1 <= length <= 200

Response Body

Answered

application/json
  1. response
ok*boolean
expectedLabel*string
kind*string
answer?unknown
handedBack*boolean
messageId*string|null
questionId*string|null
wokeAgentType*string|null
triggered*boolean
decision?unknown
Example Request
curl -X POST 'https://pod.example.com/api/hub/focus-sessions/:id/outputs/answer' \  -H 'Content-Type: application/json' \  -d '{  "expectedLabel": "string"}'
Example Response
{  "ok": true,  "expectedLabel": "string",  "kind": "string",  "answer": null,  "handedBack": true,  "messageId": "string",  "questionId": "string",  "wokeAgentType": "string",  "triggered": true,  "decision": null}

Wait (bounded long-poll) for the session owner's next answer

GET
/focus-sessions/:id/answers/wait

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

Query Parameters

since?string
timeoutSeconds?integer
Range1 <= value <= 90
limit?integer
Range1 <= value <= 100

Response Body

Answered, or timed out

application/json
  1. response
status*string
Value in"answered""timeout"
sessionId*string
since*string|null
answers?array<unknown>
nextSince*string|null
hasMore?boolean
waitedSeconds?number
Example Request
curl -X GET 'https://pod.example.com/api/hub/focus-sessions/:id/answers/wait'
Example Response
{  "status": "answered",  "sessionId": "string",  "since": "string",  "answers": [    null  ],  "nextSince": "string",  "hasMore": true,  "waitedSeconds": 0}

Poll the session owner's answers since a cursor

GET
/focus-sessions/:id/answers

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

Query Parameters

since?string
limit?integer
Range1 <= value <= 100

Response Body

A page of answers

application/json
  1. response
sessionId*string
since*string|null
answers*array<unknown>
nextSince*string|null
hasMore*boolean
Example Request
curl -X GET 'https://pod.example.com/api/hub/focus-sessions/:id/answers'
Example Response
{  "sessionId": "string",  "since": "string",  "answers": [    null  ],  "nextSince": "string",  "hasMore": true}

Events

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

Governance

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