# agent tools 7 routes, from the API’s own OpenAPI document. URL: https://docs.qaldy.com/reference/api/agent-tools/ 7 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/). ## Routes | Method | Path | What it does | |---|---|---| | [[GET]] | [`/​v1/​automations/​{id}/​agent-tool`](#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`](#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`](#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`](#delete-v1-automations-id-agent-tool) | Take an automation back from the agents: it stays an automation | | [[POST]] | [`/​v1/​automations/​{id}/​agent-tool/​runs`](#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`](#get-v1-workspaces-ws-agent-events) | What needs the connected agent: finished and failed runs, approvals, alerts | | [[GET]] | [`/​v1/​workspaces/​{ws}/​agent-tools`](#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](https://docs.qaldy.com/openapi.json). Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[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](https://docs.qaldy.com/reference/api/#errors)). ### [[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](https://docs.qaldy.com/reference/api/#errors)). ### [[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](https://docs.qaldy.com/reference/api/#errors)). ### [[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](https://docs.qaldy.com/reference/api/#errors)). ### [[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](https://docs.qaldy.com/reference/api/#errors)). ### [[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](https://docs.qaldy.com/reference/api/#errors)).