Abilities

Tags: abilities, automation, workflows

Workflow ability configuration and management

In the product: Abilities

Resources

Request and response models used by the endpoints on this page.

AbilityRequirementResponse

Field	Type	Required	Description
kind	Literal[feature, connection, member_credential, phone_number]	✓
slug	String	✓
subject	Literal[org, workspace, member]		Default: workspace

Example:

{
  "kind": null  // Literal[feature, connection, member_credential, phone_number],
  "slug": "string"  // String,
  "subject": null  // Literal[org, workspace, member], optional, default: workspace
}

AbilityResponse

Field	Type	Required	Description
abilityType	String	✓
celCondition	String
config	Dict[str, Any]	✓
enabled	Boolean	✓
id	Integer	✓
uuid	String	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "abilityType": "string"  // String,
  "config": {}  // Dict[str, Any],
  "enabled": false  // Boolean,
  "celCondition": "string"  // String, optional
}

AbilityTypeResponse

Field	Type	Required	Description
attachmentScopes	Array<Literal[workflow, task, toolkit, tool, supervisor]>		Parent surfaces where new instances of this ability may be attached
category	String
channels	Array		Channels this ability is available on (sorted). null means all channels. Declarative introspection metadata, not an enforcement point — the ability's resolve() remains authoritative.
configSchema	Dict[str, Any]
description	String
requiredFeature	String		Workspace feature slug required for this ability to be available
requires	Array		Effective workspace-resource requirements (GRA-6204), e.g. [{kind: 'feature', slug: 'gmail'}, {kind: 'connection', slug: 'gmail'}]. Includes requiredFeature adapted as a feature-kind entry. Enabling the ability with unmet connection requirements returns a correctible 400 unless allowMissingConnections is passed.
requiresChat	Boolean		If true, the ability only resolves inside a chat context (default: False)
singleton	Boolean		If true, only one instance of this ability can exist per scope (default: False)
slug	String	✓
system	Boolean		If true, this is an auto-injected system ability hidden from users (default: False)
title	String	✓

Example:

{
  "slug": "string"  // String,
  "title": "string"  // String,
  "category": "string"  // String, optional,
  "description": "string"  // String, optional,
  "configSchema": {}  // Dict[str, Any], optional, default: PydanticUndefined,
  "singleton": false  // Boolean, optional, default: False, If true, only one instance of this ability can exist per scope,
  "system": false  // Boolean, optional, default: False, If true, this is an auto-injected system ability hidden from users,
  "attachmentScopes": []  // Array<Literal[workflow, task, toolkit, tool, supervisor]>, optional, default: PydanticUndefined, Parent surfaces where new instances of this ability may be attached,
  "requiredFeature": "string"  // String, optional, Workspace feature slug required for this ability to be available,
  "requires": []  // Array<AbilityRequirementResponse>, optional, default: PydanticUndefined, Effective workspace-resource requirements (GRA-6204), e.g. [{kind: 'feature', slug: 'gmail'}, {kind: 'connection', slug: 'gmail'}]. Includes requiredFeature adapted as a feature-kind entry. Enabling the ability with unmet connection requirements returns a correctible 400 unless allowMissingConnections is passed.,
  "requiresChat": false  // Boolean, optional, default: False, If true, the ability only resolves inside a chat context,
  "channels": "string"  // Array<String>, optional, Channels this ability is available on (sorted). null means all channels. Declarative introspection metadata, not an enforcement point — the ability's resolve() remains authoritative.
}

AbilityTypesResponse

Field	Type	Required	Description
types	Array	✓

Example:

{
  "types": []  // Array<AbilityTypeResponse>
}

CreateAbilityRequest

Field	Type	Required	Description
abilityType	String	✓	The ability type slug (e.g., 'oversight:supervisor')
allowMissingConnections	Boolean		Skip the ability↔app-connection dependency check (GRA-6204). Pass true to deliberately add the ability before its required app connection(s) are enabled; workflow validation will still report the gap as a correctible finding. (default: False)
celCondition	String		CEL condition for activation
config	Dict[str, Any]		Ability configuration
customToolId	Integer		Optional tool ID (if tool-scoped)
customToolkitId	Integer		The toolkit ID to attach to
enabled	Boolean		Whether the ability is enabled (default: True)
order	Integer		Execution order (lower = earlier) (default: 0)
taskId	Integer		Optional task ID (if task-scoped)
workflowId	WorkflowId		Stable Workflow root id. Resolved server-side to the workflow's draft revision (ability edits always target the draft).
workflowRevisionId	WorkflowRevisionId		Explicit WorkflowRevision pin. Use when attaching to a specific revision rather than the draft pointed at by workflowId.

Example:

{
  "abilityType": "string"  // String, The ability type slug (e.g., 'oversight:supervisor'),
  "workflowId": null  // WorkflowId, optional, Stable Workflow root id. Resolved server-side to the workflow's draft revision (ability edits always target the draft).,
  "workflowRevisionId": null  // WorkflowRevisionId, optional, Explicit WorkflowRevision pin. Use when attaching to a specific revision rather than the draft pointed at by workflowId.,
  "taskId": 0  // Integer, optional, Optional task ID (if task-scoped),
  "customToolkitId": 0  // Integer, optional, The toolkit ID to attach to,
  "customToolId": 0  // Integer, optional, Optional tool ID (if tool-scoped),
  "config": {}  // Dict[str, Any], optional, default: PydanticUndefined, Ability configuration,
  "enabled": false  // Boolean, optional, default: True, Whether the ability is enabled,
  "order": 0  // Integer, optional, default: 0, Execution order (lower = earlier),
  "celCondition": "string"  // String, optional, CEL condition for activation,
  "allowMissingConnections": false  // Boolean, optional, default: False, Skip the ability↔app-connection dependency check (GRA-6204). Pass true to deliberately add the ability before its required app connection(s) are enabled; workflow validation will still report the gap as a correctible finding.
}

UpdateAbilityRequest

Field	Type	Required	Description
allowMissingConnections	Boolean		Skip the ability↔app-connection dependency check when re-enabling (GRA-6204). Pass true to deliberately enable the ability before its required app connection(s) are enabled. (default: False)
celCondition	String		CEL condition for activation
config	Dict[str, Any]		Ability configuration
enabled	Boolean		Whether the ability is enabled
order	Integer		Execution order (lower = earlier)

Example:

{
  "config": {}  // Dict[str, Any], optional, Ability configuration,
  "enabled": false  // Boolean, optional, Whether the ability is enabled,
  "order": 0  // Integer, optional, Execution order (lower = earlier),
  "celCondition": "string"  // String, optional, CEL condition for activation,
  "allowMissingConnections": false  // Boolean, optional, default: False, Skip the ability↔app-connection dependency check when re-enabling (GRA-6204). Pass true to deliberately enable the ability before its required app connection(s) are enabled.
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/abilities - List
• POST /api/v2/w/{workspace_uuid}/abilities - Create
• GET /api/v2/w/{workspace_uuid}/abilities/types - Types
• GET /api/v2/w/{workspace_uuid}/abilities/types/{slug:path} - Types
• DELETE /api/v2/w/{workspace_uuid}/abilities/{ability_uuid} - Delete Ability Uuid
• PATCH /api/v2/w/{workspace_uuid}/abilities/{ability_uuid} - Update Ability Uuid

List

GET /api/v2/w/{workspace_uuid}/abilities

Description:

List configured ability instances for a workflow or task scope.

Provide exactly one of:

• workflow scope: workflowId and/or workflowRevisionId (workflowId resolves to the draft revision; workflowRevisionId pins an explicit revision)
• taskId for task-scoped abilities

When workflow scope is given, only workflow-scoped abilities (task_id IS NULL) on the resolved revision are returned.

Authorization: Requires agents:read scope

Parameters:

• workflowId (Integer)
• workflowRevisionId (Integer)
• taskId (Integer)

Response: List of AbilityResponse

---

Create

POST /api/v2/w/{workspace_uuid}/abilities

Description:

Create (enable) a configured ability on a workflow or task scope.

Backs gr abilities enable. The request must name a workflow scope (workflowId stable root → draft revision, workflowRevisionId explicit pin, or taskId resolved to its owning revision) or a toolkit scope (customToolkitId) — abilities cannot be attached to an agent row directly. workflowId is entity-honest (GRA-6422): it never secretly means a revision id.

Authorization: Requires agents:write scope

Parameters:

• request - See CreateAbilityRequest

Response: See AbilityResponse

---

Types

GET /api/v2/w/{workspace_uuid}/abilities/types

Description:

List available ability types from the code registry.

Returns ability type definitions including slug, title, category, description, channels, flags, and config schema.

System abilities (auto-injected for core functionality) are hidden by default and surfaced only with includeSystem=true. Abilities gated behind workspace features are hidden when the feature is not enabled.

Authorization: Requires agents:read scope

Parameters:

• includeSystem (Boolean)

Response: See AbilityTypesResponse

---

Types {#get-types-slug:path}

GET /api/v2/w/{workspace_uuid}/abilities/types/{slug:path}

Description:

Return the full spec for a single ability type by slug.

Includes title, description, category, channels, singleton/system flags, required feature, and the JSON Schema of the params model. Backs gr abilities get --name X.

The :path converter lets the slug contain a colon (e.g. communication:phone_call_tools).

Authorization: Requires agents:read scope

Parameters:

• slug (String)

Response: See AbilityTypeResponse

---

Delete Ability Uuid

DELETE /api/v2/w/{workspace_uuid}/abilities/{ability_uuid}

Description:

Delete a configured ability instance by UUID.

Backs the removal half of gr abilities management. Distinct from disable (which sets enabled=false but keeps the config).

Authorization: Requires agents:write scope

Parameters:

• ability_uuid (String)

Response: See None

---

Update Ability Uuid

PATCH /api/v2/w/{workspace_uuid}/abilities/{ability_uuid}

Description:

Update a configured ability (configure / enable / disable).

Backs gr abilities configure (config + celCondition) and the enable/disable toggles (enabled). config is merged with the existing config; pass enabled to toggle activation.

Authorization: Requires agents:write scope

Parameters:

• ability_uuid (String)
• request - See UpdateAbilityRequest

Response: See AbilityResponse

---