Agents
Curated Agent definitions and Workspace-owned desired Agent configuration. Execution remains in the private Knowledge service.
List curated Agent definitions available to a Workspace
/api/v1/workspaces/{workspace_id}/agents/definitionsReturns customer-safe product metadata only. Confidential instructions, model/runtime configuration, internal skills, and raw tool policy are never returned.
Path Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List custom Agent definitions editable by Workspace managers
/api/v1/workspaces/{workspace_id}/agents/studio/definitionsReturns updated-at ordered pages under current Studio authority. A continuation cursor binds the prior page's commit-ordered Workspace journal position. A catalog change returns 409 catalog_changed; restart from the first page.
Path Parameters
Query Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Save a bounded, versioned custom Agent definition
/api/v1/workspaces/{workspace_id}/agents/studio/definitionsRequires the distinct custom-Agent entitlement and Workspace management authority. Saving never executes the Agent.
Path Parameters
Header Parameters
Request Body
application/jsonstring·max 500Safe description used to select this Agent for a request; responsibility is used when omitted.
string <uuid>[]·max 8Same-Workspace custom Agent definitions this Agent may delegate to. Self-references and cycles are rejected.
booleanAllow permitted Assign MCP operations under this Agent identity. New definitions default to false; omitted updates preserve the current value. Saving false revokes operational access.
Responses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringUTC RFC3339 current catalog sort position when returned by the Studio list; absent from immutable revision snapshots and detail responses.
booleanAllow permitted Assign MCP operations under this Agent identity. New definitions default to false; omitted updates preserve the current value. Saving false revokes operational access.
Read the current editable custom Agent definition
/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}Path Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
stringQuoted decimal optimistic-concurrency version.
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringUTC RFC3339 current catalog sort position when returned by the Studio list; absent from immutable revision snapshots and detail responses.
booleanAllow permitted Assign MCP operations under this Agent identity. New definitions default to false; omitted updates preserve the current value. Saving false revokes operational access.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Save a new immutable revision of a custom Agent definition
/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}Path Parameters
Header Parameters
Request Body
application/jsonstring·max 500Safe description used to select this Agent for a request; responsibility is used when omitted.
string <uuid>[]·max 8Same-Workspace custom Agent definitions this Agent may delegate to. Self-references and cycles are rejected.
booleanAllow permitted Assign MCP operations under this Agent identity. New definitions default to false; omitted updates preserve the current value. Saving false revokes operational access.
Responses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringUTC RFC3339 current catalog sort position when returned by the Studio list; absent from immutable revision snapshots and detail responses.
booleanAllow permitted Assign MCP operations under this Agent identity. New definitions default to false; omitted updates preserve the current value. Saving false revokes operational access.
List permission-filtered custom Agent request outcomes
/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}/requestsPath Parameters
Query Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
Durably admit a manual or preview-only test request
/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}/requestsTest is the only preview-only source kind. Each request pins the current definition revision and charges actual settled compute.
Path Parameters
Header Parameters
Request Body
application/jsonstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·max 2000Original bounded request input for its requester and Studio managers; returned as an empty string in member-visible history.
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
Read a member-visible custom Agent profile
/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}/profileReturns stable identity and current permission-filtered run facts without definition instructions, binding identifiers, private input, or provider traces.
Path Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Add a revision-fenced Agent responsibility overlay to a Task
/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}/delegations/{task_id}Preserves the primary human assignment and Task lifecycle. The request body must use source_kind delegation and the same task_id.
Path Parameters
Header Parameters
Request Body
application/jsonstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·max 2000Original bounded request input for its requester and Studio managers; returned as an empty string in member-visible history.
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
Read settled and pending credit usage for one custom Agent and period
/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}/usagePath Parameters
Query Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
Path Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Hire one curated Agent into a Workspace
/api/v1/workspaces/{workspace_id}/agentsCreates Core-owned desired state. It does not synchronously invoke the Knowledge runtime or imply that a run succeeded.
Path Parameters
Header Parameters
Request Body
application/jsonstring <uuid>Stable Assign-owned identifier for a curated Agent definition. Definition identifiers are not resource UUIDv7 identifiers and clients must treat them as opaque.
string <uuid>[]·max 1000Must be empty for Workspace scope and non-empty for selected-Projects scope.
Responses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>[]·max 1000Empty for Workspace scope and non-empty for selected-Projects scope.
Fixed recurrence interval. Zero uses the local-time weekday schedule.
string <date-time>Next occurrence as an unambiguous UTC instant; clients render it with schedule_timezone and the local offset.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Path Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
stringQuoted decimal optimistic-concurrency version.
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>[]·max 1000Empty for Workspace scope and non-empty for selected-Projects scope.
Fixed recurrence interval. Zero uses the local-time weekday schedule.
string <date-time>Next occurrence as an unambiguous UTC instant; clients render it with schedule_timezone and the local offset.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Update one Workspace Agent's bounded configuration
/api/v1/workspaces/{workspace_id}/agents/{agent_id}Updates scope, supported trigger selection, additional instructions, or active/paused state. Definition, model, provider, prompt, skill, MCP, and raw capability controls are not accepted.
Path Parameters
Header Parameters
Request Body
application/jsonstring <uuid>[]·max 1000Must be empty for Workspace scope and non-empty for selected-Projects scope.
Responses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>[]·max 1000Empty for Workspace scope and non-empty for selected-Projects scope.
Fixed recurrence interval. Zero uses the local-time weekday schedule.
string <date-time>Next occurrence as an unambiguous UTC instant; clients render it with schedule_timezone and the local offset.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Soft-remove one Agent and stop all unfinished work
/api/v1/workspaces/{workspace_id}/agents/{agent_id}Path Parameters
Header Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>[]·max 1000Empty for Workspace scope and non-empty for selected-Projects scope.
Fixed recurrence interval. Zero uses the local-time weekday schedule.
string <date-time>Next occurrence as an unambiguous UTC instant; clients render it with schedule_timezone and the local offset.
Quarantine an Agent, cancel unfinished runs, and invalidate pending approvals
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/quarantinePath Parameters
Header Parameters
Request Body
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>[]·max 1000Empty for Workspace scope and non-empty for selected-Projects scope.
Fixed recurrence interval. Zero uses the local-time weekday schedule.
string <date-time>Next occurrence as an unambiguous UTC instant; clients render it with schedule_timezone and the local offset.
Restore the prior qualified definition version in paused state
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/rollbackPath Parameters
Header Parameters
Request Body
application/jsonResponses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>[]·max 1000Empty for Workspace scope and non-empty for selected-Projects scope.
Fixed recurrence interval. Zero uses the local-time weekday schedule.
string <date-time>Next occurrence as an unambiguous UTC instant; clients render it with schedule_timezone and the local offset.
List retained safe run history for one Agent
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/runsReturns only Core-owned safe projections. Prompts, retrieved context, raw model output, chain of thought, provider details, and private runtime traces are never returned.
Path Parameters
Query Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
integer <int64>·min 0Authorized collection size before cursor bounds; refreshed at read time. Activity counts admitted events before display grouping and Comments include retained ordinals.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Durably request a manual Agent run
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/runsCreates the Core-owned queued run before returning. Admission requires an active, reconciled Agent with manual execution enabled; execution remains asynchronous.
Path Parameters
Header Parameters
Request Body
application/jsonResponses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Stable Assign-owned identifier for a curated Agent definition. Definition identifiers are not resource UUIDv7 identifiers and clients must treat them as opaque.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1·max 100Safe failure code. agent_resolution_exhausted indicates an unstarted dispatch exhausted resolution attempts and was reconciled; it does not imply an action occurred.
string <date-time>RFC 3339 timestamp in UTC.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read one safe Agent run projection
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/runs/{run_id}Path Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Stable Assign-owned identifier for a curated Agent definition. Definition identifiers are not resource UUIDv7 identifiers and clients must treat them as opaque.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1·max 100Safe failure code. agent_resolution_exhausted indicates an unstarted dispatch exhausted resolution attempts and was reconciled; it does not imply an action occurred.
string <date-time>RFC 3339 timestamp in UTC.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Request cancellation of a non-terminal Agent run
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/runs/{run_id}/cancelThe initiating actor or an Agent manager may cancel. Already terminal runs return a conflict and committed actions remain intact.
Path Parameters
Header Parameters
Request Body
application/jsonResponses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Stable Assign-owned identifier for a curated Agent definition. Definition identifiers are not resource UUIDv7 identifiers and clients must treat them as opaque.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1·max 100Safe failure code. agent_resolution_exhausted indicates an unstarted dispatch exhausted resolution attempts and was reconciled; it does not imply an action occurred.
string <date-time>RFC 3339 timestamp in UTC.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List the run's attributable action and exact approval records
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/runs/{run_id}/actionsPath Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
List customer-safe comments, reports, and notifications with full Agent provenance
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/runs/{run_id}/outputsPath Parameters
Header Parameters
stringUpcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.
1Responses
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
Approve or reject the exact immutable Agent action proposal once
/api/v1/workspaces/{workspace_id}/agents/{agent_id}/runs/{run_id}/actions/{action_id}/approvals/{approval_id}/decisionPath Parameters
Header Parameters
Request Body
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.