--- title: "List agent versions" method: GET path: "/api/agents/{agentId}/versions" tags: ["Agents"] --- # List agent versions `GET /api/agents/{agentId}/versions` ## Request - Base URL: `https://app.cotool.ai` - URL: `https://app.cotool.ai/api/agents/{agentId}/versions` - Auth: HTTP bearer List the whole-definition version timeline for an agent (newest first) ## Path parameters - `agentId` string, uuid, required ## Response `200` Successful response - object[] - `id` string, uuid, required - `agentId` string, uuid, required - `definition` object, required - `name` string, required - `description` string - `tags` string[] - `modelAlias` unknown, required - `reasoningEffort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' - `fastMode` boolean - `planningMode` 'auto' | 'never' | 'always': Planning behavior mode: auto (plan when needed), never (skip planning), or always (always create a plan first) - `agentFilesystem` boolean - `toolNames` string[] - `toolSelectionMode` 'manual' | 'all_read_only' | 'all_read_only_plus_selected': Tool selection behavior: manual uses the stored tool and CLI lists, all_read_only resolves all non-mutating tools at runtime, all_read_only_plus_selected resolves all non-mutating tools at runtime plus the stored tool and CLI lists - `slackReplyScope` 'anyone' | 'cotool_users': Who may reply in a Slack thread to continue this agent: anyone (any Slack user) or cotool_users (only mapped Cotool users with execute permission) - `toolActionConfigs` union[]: Optional per-tool-action configuration entries for the agent - union: Configuration for a specific tool action - object - `type` 'cotool-email_sendEmail', required - `allowedRecipients` string[], required: Email addresses and domains this agent may send email to. A domain allows every address at that domain, not its subdomains. With no entries the agent cannot send email. - object - `type` 'slack_sendMessage', required - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action - `id` string, required: Slack channel ID (for example C123ABC456) - `name` string, required: Slack channel name without the leading # - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown). - object - `type` 'slack_replyToThread', required - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action - `id` string, required: Slack channel ID (for example C123ABC456) - `name` string, required: Slack channel name without the leading # - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown). - object - `type` 'slack_readChannelMessages', required - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action - `id` string, required: Slack channel ID (for example C123ABC456) - `name` string, required: Slack channel name without the leading # - object - `type` 'slack_readThreadMessages', required - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action - `id` string, required: Slack channel ID (for example C123ABC456) - `name` string, required: Slack channel name without the leading # - object - `type` 'slack_downloadMessageFiles', required - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action - `id` string, required: Slack channel ID (for example C123ABC456) - `name` string, required: Slack channel name without the leading # - object - `type` 'slack_waitForUserResponse', required - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action - `id` string, required: Slack channel ID (for example C123ABC456) - `name` string, required: Slack channel name without the leading # - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown). - `timeout` object: Optional fixed timeout for unanswered prompts. When omitted, the wait follows the severity of the run's alert: 15 minutes for critical, 1 hour for high, 4 hours for medium, 24 hours for low, and 24 hours when the run has no alert. - `amount` integer, required: Number of units to wait before an unanswered prompt times out. - `unit` 'minutes' | 'hours' | 'days', required: Unit for the timeout amount. - `agentTools` object[] - `sync_key` string, required - `cliNames` string[] - `skills` string[] - `acceptanceCriteria` string[] - `contextDocs` object[] - `provider` 'googleDocs' | 'notion' | 'confluence' | 'mcp', required - `id` string, required - `name` string, required - `mimeType` string - `triggers` object[] - `source` 'cron' | 'webhook' | 'jira-automation' | 'jira' | 'slack' | 'linear' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required - `sync_key` string - `name` string, required - `description` string - `enabled` boolean - `eventMode` 'direct' | 'alert_source': Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent. - `schedule` string - `events` string[] - `jqlFilter` string - `issuePropertyKeysFilter` string[] - `fieldIdsFilter` string[] - `allowedChannelIds` string[] - `allowedUserIds` string[] - `allowedUsergroupIds` string[] - `replyScope` 'anyone' | 'cotool_users': Who may reply in a Slack thread to continue this agent: anyone (any Slack user) or cotool_users (only mapped Cotool users with execute permission) - `reactionEmojis` string[] - `mode` 'agent-session' | 'legacy-webhook' - `resourceTypes` string[] - `emailAddress` string - `structuredOutputSchema` CotoolJsonSchema: A JSON Schema definition with Cotool-specific extensions for structured output presets - `type` 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array', required - `title` string - `description` string - `properties` object - `items` CotoolJsonSchema (recursive) - `minItems` integer - `maxItems` integer - `required` string[] - `enum` string[] - `additionalProperties` boolean - `x-cotool` object - `presetId` 'classification' | 'markdown' | 'templatedReport' | 'toolCallEvidence' - `viewerId` string - `systemPrompt` string, required - `syncKey` string - `origin` 'user' | 'sync' | 'model', required - `sourceCommitSha` string, nullable, required - `changedByUserId` string, uuid, nullable, required - `changedByEmail` string, nullable, required - `changedBy` object, nullable - `name` string, nullable, required: The user's profile display name, falling back to their email - `imageUrl` string, nullable, required: The user's profile image URL, if one is available - `description` string, nullable, required - `resolvedModelAlias` string, nullable, required - `createdAt` string, required ## Other responses - `400`: Bad request — input validation failed or the request was malformed - `401`: Unauthorized — missing or invalid API key / session - `403`: Forbidden — the authenticated user lacks the required permissions - `500`: Internal server error --- [API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)