Coder API — Agentuity Documentation

Coder API

Manage Coder sessions, session data, loop state, and known users through the HTTP API

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your API or SDK key in the Authorization header.

HeaderValue
AuthorizationBearer YOUR_SDK_KEY

You can find your SDK key in the Agentuity Console under your project settings.


Discovery

Discover Coder URL

Discovers the org-specific Coder base URL.

GET/coder
https://catalyst-usw.agentuity.cloud/coder

Parameters

query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Response

Returns the discovered Coder URL.

StatusDescription
200Coder URL discovered
401Unauthorized — invalid or missing API key

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/coder' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Sessions

Create Session

Creates a new coder session.

POST/hub/session
https://catalyst-usw.agentuity.cloud/hub/session

Parameters

query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Request Body

Session creation payload.

FieldTypeDescription
taskstringPrimary task prompt for the session
labelstringHuman-readable session label (optional)
agentstringDefault agent identifier to use for execution (optional)
visibilitystringSession visibility setting (optional)
workflowModestringWorkflow execution mode (optional)
loopobjectLoop mode settings for the session (optional)
loop.goalstringHigh-level goal for loop mode execution (optional)
loop.maxIterationsnumberMaximum loop iterations before completion (optional)
loop.autoContinuebooleanWhether the loop auto-continues without manual approval (optional)
loop.allowDetachedbooleanWhether loop execution can continue when no client is actively attached (optional)
tagsstring[]Tags applied to the session for filtering (optional)
savedSkillIdsstring[]Saved skill IDs to attach to the session on creation (optional)
skillBucketIdsstring[]Skill bucket IDs to attach to the session on creation (optional)
skillsobject[]Skill definitions attached to the session (optional)
skills[].skillIdstringUnique skill identifier
skills[].repostringRepository slug for the skill source
skills[].namestringHuman-readable skill name (optional)
skills[].urlstringCanonical URL for the skill repository or page (optional)
repoobjectPrimary repository mounted for the session (optional)
repo.repoIdstringRepository identifier when available (optional)
repo.typestringRepository type (e.g., GitHub, GitLab) (optional)
repo.providerstringGit provider identifier (optional)
repo.ownerstringRepository owner or organization (optional)
repo.namestringRepository name (optional)
repo.fullNamestringFully qualified repository name (optional)
repo.urlstringRepository web URL (optional)
repo.cloneUrlstringRepository clone URL (optional)
repo.defaultBranchstringDefault branch for the repository (optional)
repo.branchstringSelected branch for the session workspace (optional)
repo.refstringSelected ref for the session workspace (optional)
repo.commitstringPinned commit SHA for the session workspace (optional)
repo.pathstringSubpath of the repository mounted in session (optional)
repo.rootPathstringAbsolute workspace root path for the repository (optional)
reposobject[]Multiple repositories mounted for the session (optional)
repos[].repoIdstringRepository identifier when available (optional)
repos[].typestringRepository type (e.g., GitHub, GitLab) (optional)
repos[].providerstringGit provider identifier (optional)
repos[].ownerstringRepository owner or organization (optional)
repos[].namestringRepository name (optional)
repos[].fullNamestringFully qualified repository name (optional)
repos[].urlstringRepository web URL (optional)
repos[].cloneUrlstringRepository clone URL (optional)
repos[].defaultBranchstringDefault branch for the repository (optional)
repos[].branchstringSelected branch for the session workspace (optional)
repos[].refstringSelected ref for the session workspace (optional)
repos[].commitstringPinned commit SHA for the session workspace (optional)
repos[].pathstringSubpath of the repository mounted in session (optional)
repos[].rootPathstringAbsolute workspace root path for the repository (optional)
workspaceIdstringWorkspace identifier associated with the session (optional)
envobjectEnvironment variables injected into session runtime (optional)
metadataobjectArbitrary metadata associated with the session (optional)

Response

Returns the created session.

StatusDescription
201Session created
401Unauthorized — invalid or missing API key

Response Fields

FieldTypeDescription
sessionIdstringCreated session identifier
sandboxIdstring | nullAssociated sandbox identifier
statusstringInitial session status
modestringSession mode
visibilitystringSession visibility

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/hub/session' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "task": "Implement feature X",
  "workflowMode": "standard"
}'

List Sessions

Lists sessions with optional filters and pagination.

GET/hub/sessions
https://catalyst-usw.agentuity.cloud/hub/sessions

Parameters

query
NameTypeRequiredDescription
searchstringNoSearch query
includeArchivedbooleanNoInclude archived sessions
limitnumberNoMaximum results
offsetnumberNoPagination offset
orgIdstringNoOrganization ID

Response

Returns a session list.

StatusDescription
200Sessions returned
401Unauthorized — invalid or missing API key

Response Fields

FieldTypeDescription
sessionsobjectSessions grouped by transport
sessions.websocketobject[]Websocket-backed sessions returned by the hub
sessions.websocket[].sessionIdstringUnique session identifier
sessions.websocket[].labelstringHuman-readable session label
sessions.websocket[].statusstringCurrent session status
sessions.websocket[].modestringRuntime mode used by this session
sessions.websocket[].visibilitystringVisibility value assigned to the session
sessions.websocket[].ownerobjectSession owner identity
sessions.websocket[].owner.userIdstringOwner user identifier
sessions.websocket[].owner.namestringOwner display name
sessions.websocket[].originstring | objectSession origin metadata
sessions.websocket[].repoobjectPrimary repository reference
sessions.websocket[].repo.repoIdstringRepository identifier when available
sessions.websocket[].repo.typestringRepository type (e.g., GitHub, GitLab)
sessions.websocket[].repo.providerstringGit provider identifier
sessions.websocket[].repo.ownerstringRepository owner or organization
sessions.websocket[].repo.namestringRepository name
sessions.websocket[].repo.fullNamestringFully qualified repository name
sessions.websocket[].repo.urlstringRepository web URL
sessions.websocket[].repo.cloneUrlstringRepository clone URL
sessions.websocket[].repo.defaultBranchstringDefault branch for the repository
sessions.websocket[].repo.branchstringSelected branch for the session workspace
sessions.websocket[].repo.refstringSelected ref for the session workspace
sessions.websocket[].repo.commitstringPinned commit SHA for the session workspace
sessions.websocket[].repo.pathstringSubpath of the repository mounted in session
sessions.websocket[].repo.rootPathstringAbsolute workspace root path for the repository
sessions.websocket[].reposobject[]Repository references mounted in session
sessions.websocket[].repos[].repoIdstringRepository identifier when available
sessions.websocket[].repos[].typestringRepository type (e.g., GitHub, GitLab)
sessions.websocket[].repos[].providerstringGit provider identifier
sessions.websocket[].repos[].ownerstringRepository owner or organization
sessions.websocket[].repos[].namestringRepository name
sessions.websocket[].repos[].fullNamestringFully qualified repository name
sessions.websocket[].repos[].urlstringRepository web URL
sessions.websocket[].repos[].cloneUrlstringRepository clone URL
sessions.websocket[].repos[].defaultBranchstringDefault branch for the repository
sessions.websocket[].repos[].branchstringSelected branch for the session workspace
sessions.websocket[].repos[].refstringSelected ref for the session workspace
sessions.websocket[].repos[].commitstringPinned commit SHA for the session workspace
sessions.websocket[].repos[].pathstringSubpath of the repository mounted in session
sessions.websocket[].repos[].rootPathstringAbsolute workspace root path for the repository
sessions.websocket[].workspaceobjectAssociated workspace information
sessions.websocket[].workspace.idstringWorkspace identifier
sessions.websocket[].workspace.namestringWorkspace display name
sessions.websocket[].workspace.scopestringWorkspace ownership scope
sessions.websocket[].sessionKindstringSession kind category emitted by backend
sessions.websocket[].parentSessionIdstringParent session identifier when session is derived
sessions.websocket[].coordinationJobIdstringCoordination job identifier for orchestration
sessions.websocket[].workflowModestringWorkflow mode currently active for session
sessions.websocket[].loopStatusstringCurrent loop status if workflow mode is loop
sessions.websocket[].loopIterationnumberCurrent loop iteration counter when applicable
sessions.websocket[].createdAtstringSession creation timestamp (ISO-8601)
sessions.websocket[].lastActivityAtstringTimestamp of most recent activity (ISO-8601)
sessions.websocket[].taskCountnumberNumber of tasks associated with the session
sessions.websocket[].subAgentCountnumberNumber of sub-agents associated with the session
sessions.websocket[].observerCountnumberNumber of observer participants in the session
sessions.websocket[].participantCountnumberTotal number of participants in the session
sessions.websocket[].tagsstring[]Tag values attached to the session
sessions.websocket[].skillsobject[]Skills attached to the session
sessions.websocket[].skills[].skillIdstringUnique skill identifier
sessions.websocket[].skills[].repostringRepository slug for the skill source
sessions.websocket[].skills[].namestringHuman-readable skill name
sessions.websocket[].skills[].urlstringCanonical URL for the skill repository or page
sessions.websocket[].defaultAgentstringDefault agent assigned to session operations
sessions.websocket[].bucketstringDerived bucket for session listing
sessions.websocket[].runtimeAvailablebooleanWhether runtime is currently reachable
sessions.websocket[].controlAvailablebooleanWhether control operations are currently available
sessions.websocket[].manageAvailablebooleanWhether management operations are currently available
sessions.websocket[].wakeAvailablebooleanWhether wake operation is currently available
sessions.websocket[].historyOnlybooleanWhether session is history-only and no longer interactive
sessions.websocket[].liveExpectedbooleanWhether live connectivity is expected for the session
sessions.sandboxarrayNon-websocket session entries returned by the hub
totalnumberTotal sessions matching the query

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/sessions?limit=20&offset=0' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Session

Retrieve a single coder session by ID.

GET/hub/session/{sessionId}
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Response

Returns the full session object.

StatusDescription
200Session returned
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringUnique session identifier
labelstringHuman-readable session label
statusstringCurrent session status
modestringRuntime mode used by this session
visibilitystringVisibility value assigned to the session
ownerobjectSession owner identity
owner.userIdstringOwner user identifier
owner.namestringOwner display name
originstring | objectSession origin metadata
repoobjectPrimary repository reference
repo.repoIdstringRepository identifier when available
repo.typestringRepository type (e.g., GitHub, GitLab)
repo.providerstringGit provider identifier
repo.ownerstringRepository owner or organization
repo.namestringRepository name
repo.fullNamestringFully qualified repository name
repo.urlstringRepository web URL
repo.cloneUrlstringRepository clone URL
repo.defaultBranchstringDefault branch for the repository
repo.branchstringSelected branch for the session workspace
repo.refstringSelected ref for the session workspace
repo.commitstringPinned commit SHA for the session workspace
repo.pathstringSubpath of the repository mounted in session
repo.rootPathstringAbsolute workspace root path for the repository
reposobject[]Repository references mounted in session
repos[].repoIdstringRepository identifier when available
repos[].typestringRepository type (e.g., GitHub, GitLab)
repos[].providerstringGit provider identifier
repos[].ownerstringRepository owner or organization
repos[].namestringRepository name
repos[].fullNamestringFully qualified repository name
repos[].urlstringRepository web URL
repos[].cloneUrlstringRepository clone URL
repos[].defaultBranchstringDefault branch for the repository
repos[].branchstringSelected branch for the session workspace
repos[].refstringSelected ref for the session workspace
repos[].commitstringPinned commit SHA for the session workspace
repos[].pathstringSubpath of the repository mounted in session
repos[].rootPathstringAbsolute workspace root path for the repository
workspaceobjectAssociated workspace information
workspace.idstringWorkspace identifier
workspace.namestringWorkspace display name
workspace.scopestringWorkspace ownership scope
sessionKindstringSession kind category emitted by backend
parentSessionIdstringParent session identifier when session is derived
coordinationJobIdstringCoordination job identifier for orchestration
workflowModestringWorkflow mode currently active for session
loopStatusstringCurrent loop status if workflow mode is loop
loopIterationnumberCurrent loop iteration counter when applicable
createdAtstringSession creation timestamp (ISO-8601)
lastActivityAtstringTimestamp of most recent activity (ISO-8601)
taskCountnumberNumber of tasks associated with the session
subAgentCountnumberNumber of sub-agents associated with the session
observerCountnumberNumber of observer participants in the session
participantCountnumberTotal number of participants in the session
tagsstring[]Tag values attached to the session
skillsobject[]Skills attached to the session
skills[].skillIdstringUnique skill identifier
skills[].repostringRepository slug for the skill source
skills[].namestringHuman-readable skill name
skills[].urlstringCanonical URL for the skill repository or page
defaultAgentstringDefault agent assigned to session operations
bucketstringDerived bucket for session listing
runtimeAvailablebooleanWhether runtime is currently reachable
controlAvailablebooleanWhether control operations are currently available
manageAvailablebooleanWhether management operations are currently available
wakeAvailablebooleanWhether wake operation is currently available
historyOnlybooleanWhether session is history-only and no longer interactive
liveExpectedbooleanWhether live connectivity is expected for the session
taskstringPrimary task prompt associated with the session
envobjectEnvironment variables associated with the session
metadataobjectAdditional metadata associated with the session
updatedAtstringLast update timestamp for session metadata (ISO-8601)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Update Session

Update an existing session.

PATCH/hub/session/{sessionId}
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Request Body

Session update payload.

FieldTypeDescription
labelstringUpdated session label (optional)
agentstringUpdated default agent identifier (optional)
visibilitystringUpdated visibility setting (optional)
tagsstring[]Updated set of tags for the session (optional)
skillsobject[]Updated attached skills for the session (optional)
skills[].skillIdstringUnique skill identifier
skills[].repostringRepository slug for the skill source
skills[].namestringHuman-readable skill name (optional)
skills[].urlstringCanonical URL for the skill repository or page (optional)

Response

Returns the updated session fields.

StatusDescription
200Session updated
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringUpdated session identifier
labelstringUpdated label
visibilitystringUpdated visibility
tagsstring[]Updated tags
skillsarrayUpdated skills
defaultAgentstring | nullUpdated default agent

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "label": "Updated Session",
  "tags": [
    "auth",
    "phase-2"
  ]
}'

Archive Session

Archives an existing session.

POST/hub/session/{sessionId}/archive
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}/archive

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Response

Returns the session identifier and optional updated status.

StatusDescription
200Lifecycle action applied
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringSession identifier
statusstringNew session status

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123/archive' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Resume Session

Resumes a paused session.

POST/hub/session/{sessionId}/resume
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}/resume

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Response

Returns the session identifier and optional updated status.

StatusDescription
200Session resume initiated
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringSession identifier
statusstringNew session status

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123/resume' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Session

Permanently deletes a session.

DELETE/hub/session/{sessionId}
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Response

Returns the deleted session identifier and status.

StatusDescription
200Session deleted
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringSession identifier
statusstringNew session status

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Loop

Get Loop State

Returns loop workflow state for a session.

GET/hub/session/{sessionId}/loop
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}/loop

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Response

Returns loop state payload including iteration and status.

StatusDescription
200Loop state returned
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringSession identifier for the loop state payload
workflowModestringWorkflow mode for the target session
loopobject | nullLoop state details, or null when not in loop mode

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123/loop' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Users

List Users

Lists known coder users with optional search.

GET/hub/users
https://catalyst-usw.agentuity.cloud/hub/users

Parameters

query
NameTypeRequiredDescription
searchstringNoSearch query
limitnumberNoMaximum results
offsetnumberNoPagination offset
orgIdstringNoOrganization ID

Response

Returns known users.

StatusDescription
200Users returned
401Unauthorized — invalid or missing API key

Response Fields

FieldTypeDescription
usersobject[]List of known users
users[].userIdstringUser identifier
users[].displayNamestringHuman-readable user display name
users[].emailstringUser email address
users[].providerstringIdentity provider for this user
users[].avatarUrlstringAvatar URL for the user profile image
users[].lastLoginAtstringTimestamp of the user's last login (ISO-8601)
users[].lastSeenAtstringTimestamp of the user's most recent presence (ISO-8601)
users[].createdAtstringTimestamp when the user identity was first observed (ISO-8601)
totalnumberTotal users matching the query
limitnumberPagination limit used by backend response
offsetnumberPagination offset used by backend response

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/users?search=jane' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Session Data

Get Session Replay

Retrieve replay data for a session.

GET/hub/session/{sessionId}/replay
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}/replay

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
orgIdstringNoOrganization ID

Response

Returns replay data for the session.

StatusDescription
200Replay returned
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringSession identifier for replay payload
entriesSourcestringSource used to reconstruct replay entries
sourceCountsobjectCounts of replay entries by source
sourceCounts.durableStreamnumberReplay entries loaded from durable stream storage
sourceCounts.sessionEntriesnumberReplay entries loaded from session entry storage
sourceCounts.eventHistorynumberReplay entries synthesized from event history
entriesarrayReplay conversation entries for the session

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123/replay' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Session Participants

Retrieve participants for a session.

GET/hub/session/{sessionId}/participants
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}/participants

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
limitnumberNoMaximum records
includeDisconnectedbooleanNoInclude disconnected participants
orgIdstringNoOrganization ID

Response

Returns participants for the session.

StatusDescription
200Participants returned
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringSession identifier for the participant list
participantsobject[]Participant entries associated with session
participants[].idstringParticipant identifier
participants[].rolestringParticipant role in the session
participants[].transportstringTransport protocol used by the participant
participants[].agentRolestringAgent role when participant is an agent
participants[].connectedAtstringTimestamp when participant connected (ISO-8601)
participants[].disconnectedAtstringTimestamp when participant disconnected (ISO-8601)
participants[].lastActivityAtstringTimestamp of last participant activity (ISO-8601)
participants[].metadataobjectAdditional participant metadata

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123/participants?limit=200&includeDisconnected=true' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Session Event History

Retrieve historical events for a session.

GET/hub/session/{sessionId}/events/history
https://catalyst-usw.agentuity.cloud/hub/session/{sessionId}/events/history

Parameters

path
NameTypeRequiredDescription
sessionIdstringYesSession ID
query
NameTypeRequiredDescription
limitnumberNoMaximum records
beforeIdnumberNoReturn events before the given event identifier
orgIdstringNoOrganization ID

Response

Returns session event history.

StatusDescription
200Event history returned
404Session not found

Response Fields

FieldTypeDescription
sessionIdstringSession identifier for event history payload
eventsobject[]Event history items for the session
events[].idnumberEvent sequence identifier
events[].eventstringEvent name
events[].categorystringEvent category
events[].agentstringAgent identifier responsible for the event
events[].taskIdstringTask identifier associated with the event
events[].payloadanyEvent payload data
events[].occurredAtstringTimestamp when event occurred (ISO-8601)
events[].ingestedAtstringTimestamp when event was ingested (ISO-8601)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/session/sess_123/events/history?limit=50&beforeId=1234' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'