Agentuity Documentation

Region

https://catalyst-usw.agentuity.cloud

Authentication

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

Header	Value
`Authorization`	`Bearer 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

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the discovered Coder URL.

Status	Description
200	Coder URL discovered
401	Unauthorized — 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

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Request Body

Session creation payload.

Field	Type	Description
`task`	string	Primary task prompt for the session
`label`	string	Human-readable session label (optional)
`agent`	string	Default agent identifier to use for execution (optional)
`defaultAgent`	string	Preferred default agent identifier for routing session prompts (optional)
`visibility`	string	Session visibility setting (optional)
`workflowMode`	string	Workflow execution mode (optional)
`loop`	object	Loop mode settings for the session (optional)
`loop.goal`	string	High-level goal for loop mode execution (optional)
`loop.maxIterations`	number	Maximum loop iterations before completion (optional)
`loop.autoContinue`	boolean	Whether the loop auto-continues without manual approval (optional)
`loop.allowDetached`	boolean	Whether loop execution can continue when no client is actively attached (optional)
`tags`	string[]	Tags applied to the session for filtering (optional)
`enabledAgents`	string[]	Enabled agent roster to include in the session (optional)
`savedSkillIds`	string[]	Saved skill IDs to attach to the session on creation (optional)
`skillBucketIds`	string[]	Skill bucket IDs to attach to the session on creation (optional)
`skills`	object[]	Skill definitions attached to the session (optional)
`skills[].skillId`	string	Unique skill identifier
`skills[].repo`	string	Repository slug for the skill source
`skills[].name`	string	Human-readable skill name (optional)
`skills[].url`	string	Canonical URL for the skill repository or page (optional)
`skills[].content`	string	Inline SKILL.md content for custom skills (optional)
`repo`	object	Primary repository mounted for the session (optional)
`repo.repoId`	string	Repository identifier when available (optional)
`repo.type`	string	Repository type (e.g., GitHub, GitLab) (optional)
`repo.provider`	string	Git provider identifier (optional)
`repo.owner`	string	Repository owner or organization (optional)
`repo.name`	string	Repository name (optional)
`repo.fullName`	string	Fully qualified repository name (optional)
`repo.url`	string	Repository web URL (optional)
`repo.cloneUrl`	string	Repository clone URL (optional)
`repo.defaultBranch`	string	Default branch for the repository (optional)
`repo.branch`	string	Selected branch for the session workspace (optional)
`repo.ref`	string	Selected ref for the session workspace (optional)
`repo.commit`	string	Pinned commit SHA for the session workspace (optional)
`repo.path`	string	Subpath of the repository mounted in session (optional)
`repo.rootPath`	string	Absolute workspace root path for the repository (optional)
`repos`	object[]	Multiple repositories mounted for the session (optional)
`repos[].repoId`	string	Repository identifier when available (optional)
`repos[].type`	string	Repository type (e.g., GitHub, GitLab) (optional)
`repos[].provider`	string	Git provider identifier (optional)
`repos[].owner`	string	Repository owner or organization (optional)
`repos[].name`	string	Repository name (optional)
`repos[].fullName`	string	Fully qualified repository name (optional)
`repos[].url`	string	Repository web URL (optional)
`repos[].cloneUrl`	string	Repository clone URL (optional)
`repos[].defaultBranch`	string	Default branch for the repository (optional)
`repos[].branch`	string	Selected branch for the session workspace (optional)
`repos[].ref`	string	Selected ref for the session workspace (optional)
`repos[].commit`	string	Pinned commit SHA for the session workspace (optional)
`repos[].path`	string	Subpath of the repository mounted in session (optional)
`repos[].rootPath`	string	Absolute workspace root path for the repository (optional)
`workspaceId`	string	Workspace identifier associated with the session (optional)
`projectId`	string	Project ID to associate the session sandbox with (optional)
`runtime`	string	Runtime name for the session sandbox (e.g., "bun:1", "python:3.14") (optional)
`runtimeId`	string	Runtime ID for the session sandbox (e.g., "srt_xxx") (optional)
`name`	string	Optional sandbox name (optional)
`description`	string	Optional sandbox description (optional)
`resources`	object	Resource limits for the session sandbox (optional)
`resources.memory`	string	Memory limit (e.g., "500Mi", "1Gi") (optional)
`resources.cpu`	string	CPU limit in millicores (e.g., "500m", "1000m") (optional)
`resources.disk`	string	Disk limit (e.g., "500Mi", "1Gi") (optional)
`env`	object	Environment variables injected into session runtime (optional)
`network`	object	Network configuration for the session sandbox (optional)
`network.enabled`	boolean	Whether to enable outbound network access (default: false) (optional)
`network.port`	number	Port to expose from the sandbox to the outside Internet (1024-65535) (optional)
`stream`	object	Stream configuration for the session sandbox (optional)
`stream.stdout`	string	Stream ID for stdout (or "ignore" to discard) (optional)
`stream.stderr`	string	Stream ID for stderr (or "ignore" to discard) (optional)
`stream.stdin`	string	Stream ID for stdin input (optional)
`stream.timestamps`	boolean	Include timestamps in output (default: true) (optional)
`timeout`	object	Timeout configuration for the session sandbox (optional)
`timeout.idle`	string	Idle timeout before sandbox is reaped (e.g., "10m", "1h") (optional)
`timeout.execution`	string	Maximum execution time per command (e.g., "5m", "1h") (optional)
`timeout.paused`	string	Maximum duration a sandbox can remain paused before termination (e.g., "24h", "0" for infinite) (optional)
`command`	object	Initial command to run in the session sandbox (optional)
`command.exec`	string[]	Command and arguments to execute
`command.files`	object[]	Files to create before execution (optional)
`command.files[].path`	string	Path to the file relative to the sandbox workspace
`command.files[].content`	any	File content as bytes
`command.mode`	string	Execution mode: "oneshot" auto-destroys sandbox on exit (optional)
`files`	object[]	Files to write to the session sandbox workspace on creation (optional)
`files[].path`	string	Path to the file relative to the sandbox workspace
`files[].content`	any	File content as bytes
`snapshot`	string	Snapshot ID or tag to restore the sandbox from (optional)
`dependencies`	string[]	Apt packages to install when creating the session sandbox (optional)
`packages`	string[]	npm/bun packages to install globally when creating the session sandbox (optional)
`metadata`	object	Arbitrary metadata associated with the session (optional)
`scopes`	string[]	Permission scopes for automatic service access (e.g., "services:read", "services:write") (optional)

Response

Returns the created session.

Status	Description
201	Session created
401	Unauthorized — invalid or missing API key

Response Fields

Field	Type	Description
`sessionId`	string	Created session identifier
`sandboxId`	string \| null	Associated sandbox identifier
`status`	string	Initial session status
`mode`	string	Session mode
`visibility`	string	Session 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"
}'

Create Agent Builder Session

Creates a dedicated Lead + agent-builder session for designing, editing, or publishing a custom agent.

POST/hub/session/builder

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

Parameters

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Request Body

Agent-builder launch payload.

Field	Type	Description
`label`	string	Builder session label override (optional)
`prompt`	string	Optional user focus for the builder session kickoff (optional)
`mode`	string	Builder launch mode override (optional)
`visibility`	string	Builder session visibility (optional)
`sourceSessionId`	string	Source session identifier for build-from-session launches (optional)
`targetAgentId`	string	Target custom-agent identifier for edit launches (optional)
`targetAgentSlug`	string	Target custom-agent slug for edit launches (optional)

Response

Returns the created builder session.

Status	Description
201	Builder session created
404	Source session or target agent not found

Response Fields

Field	Type	Description
`sessionId`	string	Created session identifier
`sandboxId`	string \| null	Associated sandbox identifier
`status`	string	Initial session status
`mode`	string	Session mode
`visibility`	string	Session visibility

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/hub/session/builder' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "from_session",
  "sourceSessionId": "codesess_123",
  "label": "Build from release triage",
  "prompt": "Turn the repeated release-triage workflow into a reusable QA agent"
}'

List Sessions

Lists sessions with optional filters and pagination.

GET/hub/sessions

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

Parameters

query

Name	Type	Required	Description
`search`	string	No	Search query
`includeArchived`	boolean	No	Include archived sessions
`limit`	number	No	Maximum results
`offset`	number	No	Pagination offset
`orgId`	string	No	Organization ID

Response

Returns a session list.

Status	Description
200	Sessions returned
401	Unauthorized — invalid or missing API key

Response Fields

Field	Type	Description
`sessions`	object	Sessions grouped by transport
`sessions.websocket`	object[]	Websocket-backed sessions returned by the hub
`sessions.websocket[].sessionId`	string	Unique session identifier
`sessions.websocket[].label`	string	Human-readable session label
`sessions.websocket[].status`	string	Current session status
`sessions.websocket[].mode`	string	Runtime mode used by this session
`sessions.websocket[].visibility`	string	Visibility value assigned to the session
`sessions.websocket[].owner`	object	Session owner identity
`sessions.websocket[].owner.userId`	string	Owner user identifier
`sessions.websocket[].owner.name`	string	Owner display name
`sessions.websocket[].origin`	string \| object	Session origin metadata
`sessions.websocket[].repo`	object	Primary repository reference
`sessions.websocket[].repo.repoId`	string	Repository identifier when available
`sessions.websocket[].repo.type`	string	Repository type (e.g., GitHub, GitLab)
`sessions.websocket[].repo.provider`	string	Git provider identifier
`sessions.websocket[].repo.owner`	string	Repository owner or organization
`sessions.websocket[].repo.name`	string	Repository name
`sessions.websocket[].repo.fullName`	string	Fully qualified repository name
`sessions.websocket[].repo.url`	string	Repository web URL
`sessions.websocket[].repo.cloneUrl`	string	Repository clone URL
`sessions.websocket[].repo.defaultBranch`	string	Default branch for the repository
`sessions.websocket[].repo.branch`	string	Selected branch for the session workspace
`sessions.websocket[].repo.ref`	string	Selected ref for the session workspace
`sessions.websocket[].repo.commit`	string	Pinned commit SHA for the session workspace
`sessions.websocket[].repo.path`	string	Subpath of the repository mounted in session
`sessions.websocket[].repo.rootPath`	string	Absolute workspace root path for the repository
`sessions.websocket[].repos`	object[]	Repository references mounted in session
`sessions.websocket[].repos[].repoId`	string	Repository identifier when available
`sessions.websocket[].repos[].type`	string	Repository type (e.g., GitHub, GitLab)
`sessions.websocket[].repos[].provider`	string	Git provider identifier
`sessions.websocket[].repos[].owner`	string	Repository owner or organization
`sessions.websocket[].repos[].name`	string	Repository name
`sessions.websocket[].repos[].fullName`	string	Fully qualified repository name
`sessions.websocket[].repos[].url`	string	Repository web URL
`sessions.websocket[].repos[].cloneUrl`	string	Repository clone URL
`sessions.websocket[].repos[].defaultBranch`	string	Default branch for the repository
`sessions.websocket[].repos[].branch`	string	Selected branch for the session workspace
`sessions.websocket[].repos[].ref`	string	Selected ref for the session workspace
`sessions.websocket[].repos[].commit`	string	Pinned commit SHA for the session workspace
`sessions.websocket[].repos[].path`	string	Subpath of the repository mounted in session
`sessions.websocket[].repos[].rootPath`	string	Absolute workspace root path for the repository
`sessions.websocket[].workspace`	object	Associated workspace information
`sessions.websocket[].workspace.id`	string	Workspace identifier
`sessions.websocket[].workspace.name`	string	Workspace display name
`sessions.websocket[].workspace.scope`	string	Workspace ownership scope
`sessions.websocket[].sessionKind`	string	Session kind category emitted by backend
`sessions.websocket[].parentSessionId`	string	Parent session identifier when session is derived
`sessions.websocket[].coordinationJobId`	string	Coordination job identifier for orchestration
`sessions.websocket[].workflowMode`	string	Workflow mode currently active for session
`sessions.websocket[].loopStatus`	string	Current loop status if workflow mode is loop
`sessions.websocket[].loopIteration`	number	Current loop iteration counter when applicable
`sessions.websocket[].createdAt`	string	Session creation timestamp (ISO-8601)
`sessions.websocket[].lastActivityAt`	string	Timestamp of most recent activity (ISO-8601)
`sessions.websocket[].taskCount`	number	Number of tasks associated with the session
`sessions.websocket[].subAgentCount`	number	Number of sub-agents associated with the session
`sessions.websocket[].observerCount`	number	Number of observer participants in the session
`sessions.websocket[].participantCount`	number	Total number of participants in the session
`sessions.websocket[].tags`	string[]	Tag values attached to the session
`sessions.websocket[].skills`	object[]	Skills attached to the session
`sessions.websocket[].skills[].skillId`	string	Unique skill identifier
`sessions.websocket[].skills[].repo`	string	Repository slug for the skill source
`sessions.websocket[].skills[].name`	string	Human-readable skill name
`sessions.websocket[].skills[].url`	string	Canonical URL for the skill repository or page
`sessions.websocket[].skills[].content`	string	Inline SKILL.md content for custom skills
`sessions.websocket[].enabledAgents`	string[]	Enabled agent roster attached to the session
`sessions.websocket[].builder`	object	Projected builder-session summary when this session is an agent-builder flow
`sessions.websocket[].builder.mode`	string	Builder session mode
`sessions.websocket[].builder.sourceSession`	object	Linked source session when the builder was launched from an existing session
`sessions.websocket[].builder.sourceSession.sessionId`	string	Source session identifier linked to the builder session
`sessions.websocket[].builder.sourceSession.label`	string	Source session label when available
`sessions.websocket[].builder.targetAgent`	object	Target agent baseline when the builder is editing an existing custom agent
`sessions.websocket[].builder.targetAgent.agentId`	string	Target custom-agent identifier when editing
`sessions.websocket[].builder.targetAgent.slug`	string	Target custom-agent slug
`sessions.websocket[].builder.targetAgent.displayName`	string	Target custom-agent display name
`sessions.websocket[].builder.durable`	object	Linked durable draft/publish state
`sessions.websocket[].builder.durable.draftAgentId`	string	Linked draft custom-agent identifier
`sessions.websocket[].builder.durable.draftAgentSlug`	string	Linked draft custom-agent slug
`sessions.websocket[].builder.durable.lastPublishedVersion`	number	Latest published version created through the builder flow
`sessions.websocket[].builder.lastAction`	object	Most recent durable builder action
`sessions.websocket[].builder.lastAction.kind`	string	Last durable builder action
`sessions.websocket[].builder.lastAction.status`	string	Result of the last durable builder action
`sessions.websocket[].builder.lastAction.occurredAt`	string	Timestamp of the last durable builder action
`sessions.websocket[].builder.lastAction.message`	string	Human-readable builder action result summary
`sessions.websocket[].builder.lastAction.agentId`	string	Affected custom-agent identifier
`sessions.websocket[].builder.lastAction.agentSlug`	string	Affected custom-agent slug
`sessions.websocket[].builder.lastAction.publishedVersion`	number	Published version number when publish succeeded
`sessions.websocket[].defaultAgent`	string	Default agent assigned to session operations
`sessions.websocket[].bucket`	string	Derived bucket for session listing
`sessions.websocket[].runtimeAvailable`	boolean	Whether runtime is currently reachable
`sessions.websocket[].controlAvailable`	boolean	Whether control operations are currently available
`sessions.websocket[].manageAvailable`	boolean	Whether management operations are currently available
`sessions.websocket[].wakeAvailable`	boolean	Whether wake operation is currently available
`sessions.websocket[].historyOnly`	boolean	Whether session is history-only and no longer interactive
`sessions.websocket[].liveExpected`	boolean	Whether live connectivity is expected for the session
`sessions.sandbox`	array	Non-websocket session entries returned by the hub
`total`	number	Total 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the full session object.

Status	Description
200	Session returned
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Unique session identifier
`label`	string	Human-readable session label
`status`	string	Current session status
`mode`	string	Runtime mode used by this session
`visibility`	string	Visibility value assigned to the session
`owner`	object	Session owner identity
`owner.userId`	string	Owner user identifier
`owner.name`	string	Owner display name
`origin`	string \| object	Session origin metadata
`repo`	object	Primary repository reference
`repo.repoId`	string	Repository identifier when available
`repo.type`	string	Repository type (e.g., GitHub, GitLab)
`repo.provider`	string	Git provider identifier
`repo.owner`	string	Repository owner or organization
`repo.name`	string	Repository name
`repo.fullName`	string	Fully qualified repository name
`repo.url`	string	Repository web URL
`repo.cloneUrl`	string	Repository clone URL
`repo.defaultBranch`	string	Default branch for the repository
`repo.branch`	string	Selected branch for the session workspace
`repo.ref`	string	Selected ref for the session workspace
`repo.commit`	string	Pinned commit SHA for the session workspace
`repo.path`	string	Subpath of the repository mounted in session
`repo.rootPath`	string	Absolute workspace root path for the repository
`repos`	object[]	Repository references mounted in session
`repos[].repoId`	string	Repository identifier when available
`repos[].type`	string	Repository type (e.g., GitHub, GitLab)
`repos[].provider`	string	Git provider identifier
`repos[].owner`	string	Repository owner or organization
`repos[].name`	string	Repository name
`repos[].fullName`	string	Fully qualified repository name
`repos[].url`	string	Repository web URL
`repos[].cloneUrl`	string	Repository clone URL
`repos[].defaultBranch`	string	Default branch for the repository
`repos[].branch`	string	Selected branch for the session workspace
`repos[].ref`	string	Selected ref for the session workspace
`repos[].commit`	string	Pinned commit SHA for the session workspace
`repos[].path`	string	Subpath of the repository mounted in session
`repos[].rootPath`	string	Absolute workspace root path for the repository
`workspace`	object	Associated workspace information
`workspace.id`	string	Workspace identifier
`workspace.name`	string	Workspace display name
`workspace.scope`	string	Workspace ownership scope
`sessionKind`	string	Session kind category emitted by backend
`parentSessionId`	string	Parent session identifier when session is derived
`coordinationJobId`	string	Coordination job identifier for orchestration
`workflowMode`	string	Workflow mode currently active for session
`loopStatus`	string	Current loop status if workflow mode is loop
`loopIteration`	number	Current loop iteration counter when applicable
`createdAt`	string	Session creation timestamp (ISO-8601)
`lastActivityAt`	string	Timestamp of most recent activity (ISO-8601)
`taskCount`	number	Number of tasks associated with the session
`subAgentCount`	number	Number of sub-agents associated with the session
`observerCount`	number	Number of observer participants in the session
`participantCount`	number	Total number of participants in the session
`tags`	string[]	Tag values attached to the session
`skills`	object[]	Skills attached to the session
`skills[].skillId`	string	Unique skill identifier
`skills[].repo`	string	Repository slug for the skill source
`skills[].name`	string	Human-readable skill name
`skills[].url`	string	Canonical URL for the skill repository or page
`skills[].content`	string	Inline SKILL.md content for custom skills
`enabledAgents`	string[]	Enabled agent roster attached to the session
`builder`	object	Full builder-session state when this session is an agent-builder flow
`builder.mode`	string	Builder session mode
`builder.sourceSession`	object	Linked source session when the builder was launched from an existing session
`builder.sourceSession.sessionId`	string	Source session identifier linked to the builder session
`builder.sourceSession.label`	string	Source session label when available
`builder.targetAgent`	object	Target agent baseline when the builder is editing an existing custom agent
`builder.targetAgent.agentId`	string	Target custom-agent identifier when editing
`builder.targetAgent.slug`	string	Target custom-agent slug
`builder.targetAgent.displayName`	string	Target custom-agent display name
`builder.durable`	object	Linked durable draft/publish state
`builder.durable.draftAgentId`	string	Linked draft custom-agent identifier
`builder.durable.draftAgentSlug`	string	Linked draft custom-agent slug
`builder.durable.lastPublishedVersion`	number	Latest published version created through the builder flow
`builder.lastAction`	object	Most recent durable builder action
`builder.lastAction.kind`	string	Last durable builder action
`builder.lastAction.status`	string	Result of the last durable builder action
`builder.lastAction.occurredAt`	string	Timestamp of the last durable builder action
`builder.lastAction.message`	string	Human-readable builder action result summary
`builder.lastAction.agentId`	string	Affected custom-agent identifier
`builder.lastAction.agentSlug`	string	Affected custom-agent slug
`builder.lastAction.publishedVersion`	number	Published version number when publish succeeded
`builder.proposal`	object	Full builder proposal state projected in session detail responses
`builder.proposal.slug`	string	Proposed custom-agent slug
`builder.proposal.displayName`	string	Proposed custom-agent name
`builder.proposal.description`	string	Proposed custom-agent description
`builder.proposal.instructions`	string	Proposed custom-agent system prompt
`builder.proposal.model`	string	Proposed model override
`builder.proposal.thinkingLevel`	string	Proposed thinking level override
`builder.proposal.headlessCompatible`	boolean	Whether the proposed agent is safe for non-interactive callers
`builder.proposal.tools`	string[]	Proposed workspace tools for the agent
`builder.proposal.serviceTools`	string[]	Proposed service tools for the agent
`builder.proposal.savedSkills`	object[]	Proposed frozen skill refs to attach
`builder.proposal.savedSkills[].skillId`	string	Unique skill identifier
`builder.proposal.savedSkills[].repo`	string	Repository slug for the skill source
`builder.proposal.savedSkills[].name`	string	Human-readable skill name
`builder.proposal.savedSkills[].url`	string	Canonical URL for the skill repository or page
`builder.proposal.savedSkills[].content`	string	Inline SKILL.md content for custom skills
`builder.proposal.companionAgents`	string[]	Proposed companion agents to auto-include
`defaultAgent`	string	Default agent assigned to session operations
`bucket`	string	Derived bucket for session listing
`runtimeAvailable`	boolean	Whether runtime is currently reachable
`controlAvailable`	boolean	Whether control operations are currently available
`manageAvailable`	boolean	Whether management operations are currently available
`wakeAvailable`	boolean	Whether wake operation is currently available
`historyOnly`	boolean	Whether session is history-only and no longer interactive
`liveExpected`	boolean	Whether live connectivity is expected for the session
`task`	string	Primary task prompt associated with the session
`env`	object	Environment variables associated with the session
`metadata`	object	Additional metadata associated with the session
`updatedAt`	string	Last 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Request Body

Session update payload.

Field	Type	Description
`label`	string	Updated session label (optional)
`agent`	string	Updated default agent identifier (optional)
`defaultAgent`	string	Updated preferred default agent identifier (optional)
`enabledAgents`	string[]	Updated enabled agent roster for the session (optional)
`visibility`	string	Updated visibility setting (optional)
`tags`	string[]	Updated set of tags for the session (optional)
`skills`	object[]	Updated attached skills for the session (optional)
`skills[].skillId`	string	Unique skill identifier
`skills[].repo`	string	Repository slug for the skill source
`skills[].name`	string	Human-readable skill name (optional)
`skills[].url`	string	Canonical URL for the skill repository or page (optional)
`skills[].content`	string	Inline SKILL.md content for custom skills (optional)
`metadata`	object	Updated arbitrary metadata associated with the session (optional)
`savedSkillIds`	string[]	Updated saved skill ids (optional)
`skillBucketIds`	string[]	Updated skill bucket ids (optional)

Response

Returns the updated session fields.

Status	Description
200	Session updated
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Updated session identifier
`label`	string	Updated label
`visibility`	string	Updated visibility
`tags`	string[]	Updated tags
`skills`	array	Updated skills
`defaultAgent`	string \| null	Updated default agent
`enabledAgents`	string[]	Updated enabled agents
`metadata`	object	Updated arbitrary metadata associated with the session

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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the session identifier and optional updated status.

Status	Description
200	Lifecycle action applied
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Session identifier
`status`	string	New 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the session identifier and optional updated status.

Status	Description
200	Session resume initiated
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Session identifier
`status`	string	New 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the deleted session identifier and status.

Status	Description
200	Session deleted
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Session identifier
`status`	string	New 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns loop state payload including iteration and status.

Status	Description
200	Loop state returned
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Session identifier for the loop state payload
`workflowMode`	string	Workflow mode for the target session
`loop`	object \| null	Loop 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

Name	Type	Required	Description
`search`	string	No	Search query
`limit`	number	No	Maximum results
`offset`	number	No	Pagination offset
`orgId`	string	No	Organization ID

Response

Returns known users.

Status	Description
200	Users returned
401	Unauthorized — invalid or missing API key

Response Fields

Field	Type	Description
`users`	object[]	List of known users
`users[].userId`	string	User identifier
`users[].displayName`	string	Human-readable user display name
`users[].email`	string	User email address
`users[].provider`	string	Identity provider for this user
`users[].avatarUrl`	string	Avatar URL for the user profile image
`users[].lastLoginAt`	string	Timestamp of the user's last login (ISO-8601)
`users[].lastSeenAt`	string	Timestamp of the user's most recent presence (ISO-8601)
`users[].createdAt`	string	Timestamp when the user identity was first observed (ISO-8601)
`total`	number	Total users matching the query
`limit`	number	Pagination limit used by backend response
`offset`	number	Pagination 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns replay data for the session.

Status	Description
200	Replay returned
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Session identifier for replay payload
`entriesSource`	string	Source used to reconstruct replay entries
`sourceCounts`	object	Counts of replay entries by source
`sourceCounts.durableStream`	number	Replay entries loaded from durable stream storage
`sourceCounts.sessionEntries`	number	Replay entries loaded from session entry storage
`sourceCounts.eventHistory`	number	Replay entries synthesized from event history
`entries`	array	Replay 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`limit`	number	No	Maximum records
`includeDisconnected`	boolean	No	Include disconnected participants
`orgId`	string	No	Organization ID

Response

Returns participants for the session.

Status	Description
200	Participants returned
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Session identifier for the participant list
`participants`	object[]	Participant entries associated with session
`participants[].id`	string	Participant identifier
`participants[].role`	string	Participant role in the session
`participants[].transport`	string	Transport protocol used by the participant
`participants[].agentRole`	string	Agent role when participant is an agent
`participants[].connectedAt`	string	Timestamp when participant connected (ISO-8601)
`participants[].disconnectedAt`	string	Timestamp when participant disconnected (ISO-8601)
`participants[].lastActivityAt`	string	Timestamp of last participant activity (ISO-8601)
`participants[].metadata`	object	Additional 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

Name	Type	Required	Description
`sessionId`	string	Yes	Session ID

query

Name	Type	Required	Description
`limit`	number	No	Maximum records
`beforeId`	number	No	Return events before the given event identifier
`orgId`	string	No	Organization ID

Response

Returns session event history.

Status	Description
200	Event history returned
404	Session not found

Response Fields

Field	Type	Description
`sessionId`	string	Session identifier for event history payload
`events`	object[]	Event history items for the session
`events[].id`	number	Event sequence identifier
`events[].event`	string	Event name
`events[].category`	string	Event category
`events[].agent`	string	Agent identifier responsible for the event
`events[].taskId`	string	Task identifier associated with the event
`events[].payload`	any	Event payload data
`events[].occurredAt`	string	Timestamp when event occurred (ISO-8601)
`events[].ingestedAt`	string	Timestamp 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'

Agents

List Custom Agents

Lists custom agents visible to the caller.

GET/hub/agents

https://catalyst-usw.agentuity.cloud/hub/agents

Parameters

query

Name	Type	Required	Description
`includeArchived`	boolean	No	Include archived custom agents
`orgId`	string	No	Organization ID

Response

Returns custom agents visible to the caller.

Status	Description
200	Custom agents returned
401	Unauthorized — invalid or missing API key

Response Fields

Field	Type	Description
`agents`	object[]	Custom agents returned by coder hub
`agents[].slug`	string	Stable custom agent slug
`agents[].displayName`	string	Human-readable custom agent name
`agents[].description`	string	Optional custom agent description
`agents[].instructions`	string	Standalone custom-agent system prompt
`agents[].model`	string	Optional model override
`agents[].thinkingLevel`	string	Optional thinking level override
`agents[].headlessCompatible`	boolean	Whether the custom agent is safe for non-interactive callers
`agents[].tools`	string[]	Workspace tools granted to the custom agent
`agents[].serviceTools`	string[]	Service tools granted to the custom agent
`agents[].savedSkills`	object[]	Frozen saved-skill refs attached to the custom agent snapshot
`agents[].savedSkills[].skillId`	string	Unique skill identifier
`agents[].savedSkills[].repo`	string	Repository slug for the skill source
`agents[].savedSkills[].name`	string	Human-readable skill name
`agents[].savedSkills[].url`	string	Canonical URL for the skill repository or page
`agents[].savedSkills[].content`	string	Inline SKILL.md content for custom skills
`agents[].companionAgents`	string[]	Companion agents auto-included alongside this custom agent
`agents[].id`	string	Custom agent record identifier
`agents[].ownerUserId`	string	Owner user identifier
`agents[].lifecycle`	string	Current lifecycle state for the custom agent
`agents[].visibility`	string	Visibility tier for the custom agent
`agents[].createdAt`	string	Creation timestamp (ISO-8601)
`agents[].updatedAt`	string	Last update timestamp (ISO-8601)
`agents[].hasPublishedVersion`	boolean	Whether the agent has at least one published version
`agents[].hasUnpublishedChanges`	boolean	Whether the current draft differs from the latest published version
`agents[].latestPublishedVersion`	number	Latest published version number
`agents[].latestPublishedAt`	string	Latest published timestamp (ISO-8601)
`agents[].published`	object	Latest published version snapshot
`agents[].published.slug`	string	Stable custom agent slug
`agents[].published.displayName`	string	Human-readable custom agent name
`agents[].published.description`	string	Optional custom agent description
`agents[].published.instructions`	string	Standalone custom-agent system prompt
`agents[].published.model`	string	Optional model override
`agents[].published.thinkingLevel`	string	Optional thinking level override
`agents[].published.headlessCompatible`	boolean	Whether the custom agent is safe for non-interactive callers
`agents[].published.tools`	string[]	Workspace tools granted to the custom agent
`agents[].published.serviceTools`	string[]	Service tools granted to the custom agent
`agents[].published.savedSkills`	object[]	Frozen saved-skill refs attached to the custom agent snapshot
`agents[].published.savedSkills[].skillId`	string	Unique skill identifier
`agents[].published.savedSkills[].repo`	string	Repository slug for the skill source
`agents[].published.savedSkills[].name`	string	Human-readable skill name
`agents[].published.savedSkills[].url`	string	Canonical URL for the skill repository or page
`agents[].published.savedSkills[].content`	string	Inline SKILL.md content for custom skills
`agents[].published.companionAgents`	string[]	Companion agents auto-included alongside this custom agent
`agents[].published.id`	string	Published custom agent version identifier
`agents[].published.agentId`	string	Parent custom agent identifier
`agents[].published.version`	number	Published version number
`agents[].published.createdByUserId`	string	User who published the version
`agents[].published.createdAt`	string	Version creation timestamp (ISO-8601)
`agents[].draft`	object	Owner-visible draft snapshot
`agents[].draft.slug`	string	Stable custom agent slug
`agents[].draft.displayName`	string	Human-readable custom agent name
`agents[].draft.description`	string	Optional custom agent description
`agents[].draft.instructions`	string	Standalone custom-agent system prompt
`agents[].draft.model`	string	Optional model override
`agents[].draft.thinkingLevel`	string	Optional thinking level override
`agents[].draft.headlessCompatible`	boolean	Whether the custom agent is safe for non-interactive callers
`agents[].draft.tools`	string[]	Workspace tools granted to the custom agent
`agents[].draft.serviceTools`	string[]	Service tools granted to the custom agent
`agents[].draft.savedSkills`	object[]	Frozen saved-skill refs attached to the custom agent snapshot
`agents[].draft.savedSkills[].skillId`	string	Unique skill identifier
`agents[].draft.savedSkills[].repo`	string	Repository slug for the skill source
`agents[].draft.savedSkills[].name`	string	Human-readable skill name
`agents[].draft.savedSkills[].url`	string	Canonical URL for the skill repository or page
`agents[].draft.savedSkills[].content`	string	Inline SKILL.md content for custom skills
`agents[].draft.companionAgents`	string[]	Companion agents auto-included alongside this custom agent

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/agents?includeArchived=true' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Create Custom Agent

Creates a new custom-agent draft.

POST/hub/agents

https://catalyst-usw.agentuity.cloud/hub/agents

Parameters

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Request Body

Custom-agent creation payload.

Field	Type	Description
`slug`	string	Stable custom agent slug
`displayName`	string	Human-readable custom agent name
`description`	string	Optional custom agent description (optional)
`instructions`	string	Standalone custom-agent system prompt
`model`	string	Optional model override (optional)
`thinkingLevel`	string	Optional thinking level override (optional)
`headlessCompatible`	boolean	Whether the custom agent is safe for non-interactive callers (optional)
`tools`	string[]	Workspace tools to grant to the custom agent (optional)
`serviceTools`	string[]	Service tools to grant to the custom agent (optional)
`savedSkillIds`	string[]	Saved skill row ids to snapshot onto the custom agent (optional)
`companionAgents`	string[]	Agent names to auto-include alongside this custom agent (optional)

Response

Returns the created custom agent.

Status	Description
201	Custom agent created
401	Unauthorized — invalid or missing API key

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/hub/agents' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "slug": "code-review",
  "displayName": "Code Review",
  "instructions": "Focus on correctness, regressions, and missing tests.",
  "tools": [
    "read",
    "grep",
    "ls"
  ],
  "serviceTools": [
    "session_todo_list",
    "session_todo_update"
  ]
}'

Get Custom Agent

Fetches a custom agent by id or slug.

GET/hub/agents/{agentIdOrSlug}

https://catalyst-usw.agentuity.cloud/hub/agents/{agentIdOrSlug}

Parameters

path

Name	Type	Required	Description
`agentIdOrSlug`	string	Yes	Custom agent id or slug

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the requested custom agent.

Status	Description
200	Custom agent returned
404	Custom agent not found

Example

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

Update Custom Agent

Updates an owned custom-agent draft.

PATCH/hub/agents/{agentIdOrSlug}

https://catalyst-usw.agentuity.cloud/hub/agents/{agentIdOrSlug}

Parameters

path

Name	Type	Required	Description
`agentIdOrSlug`	string	Yes	Custom agent id or slug

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Request Body

Custom-agent update payload.

Field	Type	Description
`slug`	string	Stable custom agent slug (optional)
`displayName`	string	Human-readable custom agent name (optional)
`description`	string \| null	Optional custom agent description (optional)
`instructions`	string	Standalone custom-agent system prompt (optional)
`model`	string \| null	Optional model override (optional)
`thinkingLevel`	string \| null	Optional thinking level override (optional)
`headlessCompatible`	boolean	Whether the custom agent is safe for non-interactive callers (optional)
`tools`	string[]	Workspace tools to grant to the custom agent (optional)
`serviceTools`	string[]	Service tools to grant to the custom agent (optional)
`savedSkillIds`	string[]	Saved skill row ids to snapshot onto the custom agent (optional)
`companionAgents`	string[]	Agent names to auto-include alongside this custom agent (optional)

Response

Returns the updated custom agent.

Status	Description
200	Custom agent updated
404	Custom agent not found

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/hub/agents/code-review' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "displayName": "Code Review Draft"
}'

Publish Custom Agent

Publishes an owned custom agent.

POST/hub/agents/{agentIdOrSlug}/publish

https://catalyst-usw.agentuity.cloud/hub/agents/{agentIdOrSlug}/publish

Parameters

path

Name	Type	Required	Description
`agentIdOrSlug`	string	Yes	Custom agent id or slug

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the updated custom agent.

Status	Description
200	Custom agent published
404	Custom agent not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/hub/agents/code-review/publish' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Archive Custom Agent

Archives an owned custom agent.

POST/hub/agents/{agentIdOrSlug}/archive

https://catalyst-usw.agentuity.cloud/hub/agents/{agentIdOrSlug}/archive

Parameters

path

Name	Type	Required	Description
`agentIdOrSlug`	string	Yes	Custom agent id or slug

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns the updated custom agent.

Status	Description
200	Custom agent archived
404	Custom agent not found

Example

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

List Custom Agent Versions

Lists immutable published versions for a custom agent.

GET/hub/agents/{agentIdOrSlug}/versions

https://catalyst-usw.agentuity.cloud/hub/agents/{agentIdOrSlug}/versions

Parameters

path

Name	Type	Required	Description
`agentIdOrSlug`	string	Yes	Custom agent id or slug

query

Name	Type	Required	Description
`orgId`	string	No	Organization ID

Response

Returns published versions for the custom agent.

Status	Description
200	Custom agent versions returned
404	Custom agent not found

Response Fields

Field	Type	Description
`versions`	object[]	Published custom agent versions returned by coder hub
`versions[].slug`	string	Stable custom agent slug
`versions[].displayName`	string	Human-readable custom agent name
`versions[].description`	string	Optional custom agent description
`versions[].instructions`	string	Standalone custom-agent system prompt
`versions[].model`	string	Optional model override
`versions[].thinkingLevel`	string	Optional thinking level override
`versions[].headlessCompatible`	boolean	Whether the custom agent is safe for non-interactive callers
`versions[].tools`	string[]	Workspace tools granted to the custom agent
`versions[].serviceTools`	string[]	Service tools granted to the custom agent
`versions[].savedSkills`	object[]	Frozen saved-skill refs attached to the custom agent snapshot
`versions[].savedSkills[].skillId`	string	Unique skill identifier
`versions[].savedSkills[].repo`	string	Repository slug for the skill source
`versions[].savedSkills[].name`	string	Human-readable skill name
`versions[].savedSkills[].url`	string	Canonical URL for the skill repository or page
`versions[].savedSkills[].content`	string	Inline SKILL.md content for custom skills
`versions[].companionAgents`	string[]	Companion agents auto-included alongside this custom agent
`versions[].id`	string	Published custom agent version identifier
`versions[].agentId`	string	Parent custom agent identifier
`versions[].version`	number	Published version number
`versions[].createdByUserId`	string	User who published the version
`versions[].createdAt`	string	Version creation timestamp (ISO-8601)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/hub/agents/code-review/versions' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'