agent tools

7 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.

Routes#

Method	Path	What it does
GET	`/v1/automations/{id}/agent-tool`	What to read before publishing an automation as a tool: the permissions of the app that runs, a suggested name and schema, and the published tool if there is one
PUT	`/v1/automations/{id}/agent-tool`	Publish an automation as a tool, or change the published one. The body carries the hash of the permissions the person read.
PATCH	`/v1/automations/{id}/agent-tool`	Switch a published tool off or on. Switching on needs the permissions to be current.
DELETE	`/v1/automations/{id}/agent-tool`	Take an automation back from the agents: it stays an automation
POST	`/v1/automations/{id}/agent-tool/runs`	Call a published tool: starts the automation through the normal run path, as the person asking
GET	`/v1/workspaces/{ws}/agent-events`	What needs the connected agent: finished and failed runs, approvals, alerts
GET	`/v1/workspaces/{ws}/agent-tools`	Published tools you can see, with whether you can run each. An agent lists the live ones it can run.

Reference#

GET `/v1/automations/{id}/agent-tool`#

What to read before publishing an automation as a tool: the permissions of the app that runs, a suggested name and schema, and the published tool if there is one.

Authentication: the console’s session cookie.
Token: not available. This route is for a signed-in person in the console (403 console_only for a token).
Who: can_view on every app it stops at

Parameter	In	Type	Required	Notes
`id`	path	string	yes	1 to 128 characters

Response 200

Field	Type	Required	Notes
`automationId`	string	yes	at least 1 characters
`automationName`	string	yes	at least 1 characters
`appId`	string or null	yes
`appName`	string or null	yes
`blocked`	"no_app" · "not_deployed" · "no_input_path" · "not_runnable" · null or null	yes
`manifest`	object or null	yes
`manifest.name`	string	yes	2 to 60 characters
`manifest.description`	string	yes	4 to 280 characters
`manifest.archetype`	"kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · …	yes
`manifest.category`	"interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth"	yes
`manifest.permissions`	object	yes
`manifest.triggers`	object[]	yes
`manifest.sharing`	object	yes
`manifest.roi`	object	yes
`hash`	string or null	yes
`suggested`	object	yes
`suggested.name`	string	yes
`suggested.title`	string	yes	1 to 60 characters
`suggested.description`	string	yes	1 to 400 characters
`suggested.inputSchema`	object	yes
`startsAs`	"manual" · "webhook" · "form" · "schedule" · null or null	yes
`published`	object or null	yes
`published.id`	string	yes	at least 1 characters
`published.automationId`	string	yes	at least 1 characters
`published.automationName`	string	yes	at least 1 characters
`published.appId`	string	yes	at least 1 characters
`published.appName`	string	yes	at least 1 characters
`published.name`	string	yes
`published.title`	string	yes	1 to 60 characters
`published.description`	string	yes	1 to 400 characters

…and 9 more fields. The full schema is in openapi.json.

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

PUT `/v1/automations/{id}/agent-tool`#

Publish an automation as a tool, or change the published one. The body carries the hash of the permissions the person read..

Authentication: the console’s session cookie.
Token: not available. This route is for a signed-in person in the console (403 console_only for a token).
Who: can_edit on the driving app; console only

Parameter	In	Type	Required	Notes
`id`	path	string	yes	1 to 128 characters

Request body (application/json)

Field	Type	Required	Notes
`name`	string	yes
`title`	string	yes	1 to 60 characters
`description`	string	yes	8 to 400 characters
`inputSchema`	object	yes
`inputSchema.type`	"object"	yes
`inputSchema.properties`	map of object	yes
`inputSchema.required`	string[]		up to 20 items
`inputSchema.additionalProperties`	false
`reviewedHash`	string	yes
`enabled`	boolean		default true

Response 200

Field	Type	Required	Notes
`id`	string	yes	at least 1 characters
`automationId`	string	yes	at least 1 characters
`automationName`	string	yes	at least 1 characters
`appId`	string	yes	at least 1 characters
`appName`	string	yes	at least 1 characters
`name`	string	yes
`title`	string	yes	1 to 60 characters
`description`	string	yes	1 to 400 characters
`inputSchema`	object	yes
`inputSchema.type`	"object"	yes
`inputSchema.properties`	map of object	yes
`inputSchema.required`	string[]		up to 20 items
`inputSchema.additionalProperties`	false
`state`	"live" · "off" · "needs_review" · "paused"	yes
`canRun`	boolean	yes
`canEdit`	boolean	yes
`reviewedAt`	string (date-time)	yes
`reviewedBy`	string	yes	at least 1 characters
`publishedAt`	string (date-time)	yes
`callsWeek`	integer	yes	at least 0
`lastCalledAt`	string (date-time) or null	yes

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

PATCH `/v1/automations/{id}/agent-tool`#

Switch a published tool off or on. Switching on needs the permissions to be current..

Authentication: the console’s session cookie.
Token: not available. This route is for a signed-in person in the console (403 console_only for a token).
Who: can_edit; console only

Parameter	In	Type	Required	Notes
`id`	path	string	yes	1 to 128 characters

Request body (application/json)

Field	Type	Required	Notes
`enabled`	boolean	yes

Response 200

Field	Type	Required	Notes
`id`	string	yes	at least 1 characters
`automationId`	string	yes	at least 1 characters
`automationName`	string	yes	at least 1 characters
`appId`	string	yes	at least 1 characters
`appName`	string	yes	at least 1 characters
`name`	string	yes
`title`	string	yes	1 to 60 characters
`description`	string	yes	1 to 400 characters
`inputSchema`	object	yes
`inputSchema.type`	"object"	yes
`inputSchema.properties`	map of object	yes
`inputSchema.required`	string[]		up to 20 items
`inputSchema.additionalProperties`	false
`state`	"live" · "off" · "needs_review" · "paused"	yes
`canRun`	boolean	yes
`canEdit`	boolean	yes
`reviewedAt`	string (date-time)	yes
`reviewedBy`	string	yes	at least 1 characters
`publishedAt`	string (date-time)	yes
`callsWeek`	integer	yes	at least 0
`lastCalledAt`	string (date-time) or null	yes

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

DELETE `/v1/automations/{id}/agent-tool`#

Take an automation back from the agents: it stays an automation.

Authentication: the console’s session cookie.
Token: not available. This route is for a signed-in person in the console (403 console_only for a token).
Who: can_edit; console only

Parameter	In	Type	Required	Notes
`id`	path	string	yes	1 to 128 characters

Response 200

Field	Type	Required	Notes
`ok`	true	yes

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

POST `/v1/automations/{id}/agent-tool/runs`#

Call a published tool: starts the automation through the normal run path, as the person asking.

Authentication: the console’s session cookie.
Token: a personal access token or an MCP sign-in with the write scope.
Who: can_run; tokens need write

Parameter	In	Type	Required	Notes
`id`	path	string	yes	1 to 128 characters

Request body (application/json)

Field	Type	Required	Notes
`input`	map of any or null		default [object Object]

Response 200

Field	Type	Required	Notes
`runId`	string	yes	at least 1 characters
`toolName`	string	yes
`automationId`	string	yes	at least 1 characters
`held`	boolean

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET `/v1/workspaces/{ws}/agent-events`#

What needs the connected agent: finished and failed runs, approvals, alerts.

Authentication: the console’s session cookie.
Token: a personal access token or an MCP sign-in with the read scope.
Who: member; tokens need read

Parameter	In	Type	Required	Notes
`ws`	path	string	yes	1 to 128 characters
`since`	query	integer or null		at least 0
`wait`	query	integer or null		0 to 25. default 0

Response 200

Field	Type	Required	Notes
`items`	object[]	yes	up to 100 items
`items[].seq`	integer	yes	at least 1
`items[].at`	string (date-time)	yes
`items[].kind`	"run_finished" · "run_failed" · "approval_needed" · "alert"	yes
`items[].alert`	"app_failing" · "automation_failing" · "connector_down" · "blocked_call" · "cap_reached" · null or null	yes
`items[].appId`	string or null	yes
`items[].appName`	string or null	yes
`items[].runId`	string or null	yes
`items[].approvalId`	string or null	yes
`items[].code`	string or null	yes	up to 64 characters
`items[].askedByAgent`	boolean	yes
`cursor`	integer	yes	at least 0

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

GET `/v1/workspaces/{ws}/agent-tools`#

Published tools you can see, with whether you can run each. An agent lists the live ones it can run..

Authentication: the console’s session cookie.
Token: a personal access token or an MCP sign-in with the read scope.
Who: member (only automations you can view); tokens need read

Parameter	In	Type	Required	Notes
`ws`	path	string	yes	1 to 128 characters

Response 200

Field	Type	Required	Notes
`items`	object[]	yes
`items[].id`	string	yes	at least 1 characters
`items[].automationId`	string	yes	at least 1 characters
`items[].automationName`	string	yes	at least 1 characters
`items[].appId`	string	yes	at least 1 characters
`items[].appName`	string	yes	at least 1 characters
`items[].name`	string	yes
`items[].title`	string	yes	1 to 60 characters
`items[].description`	string	yes	1 to 400 characters
`items[].inputSchema`	object	yes
`items[].state`	"live" · "off" · "needs_review" · "paused"	yes
`items[].canRun`	boolean	yes
`items[].canEdit`	boolean	yes
`items[].reviewedAt`	string (date-time)	yes
`items[].reviewedBy`	string	yes	at least 1 characters
`items[].publishedAt`	string (date-time)	yes
`items[].callsWeek`	integer	yes	at least 0
`items[].lastCalledAt`	string (date-time) or null	yes

Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).

Routes#

Reference#

GET /v1/automations/{id}/agent-tool#

PUT /v1/automations/{id}/agent-tool#

PATCH /v1/automations/{id}/agent-tool#

DELETE /v1/automations/{id}/agent-tool#

POST /v1/automations/{id}/agent-tool/runs#

GET /v1/workspaces/{ws}/agent-events#

GET /v1/workspaces/{ws}/agent-tools#

GET `/v1/automations/{id}/agent-tool`#

PUT `/v1/automations/{id}/agent-tool`#

PATCH `/v1/automations/{id}/agent-tool`#

DELETE `/v1/automations/{id}/agent-tool`#

POST `/v1/automations/{id}/agent-tool/runs`#

GET `/v1/workspaces/{ws}/agent-events`#

GET `/v1/workspaces/{ws}/agent-tools`#