Skip to main content
PUT
cURL

Authorizations

Authorization
string
header
required

API Key authentication for programmatic access. Include your API key in the Authorization header as: Bearer your_api_key_here

Path Parameters

agentId
string<uuid>
required

Unique identifier of the agent to update

Body

application/json

Request body for updating agent configuration (all fields optional)

name
string

Optional new name for the agent

description
string

Optional new description for the agent

versionDescription
string

Optional description for the agent version created by this update

systemPrompt
string

Optional new system prompt for the agent

toolNames
string[]

Optional new array of tool names for the agent

toolSelectionMode
enum<string>

Optional new tool selection mode for the agent

Available options:
manual,
all_read_only,
all_read_only_plus_selected
cliNames
string[]

Optional new array of CLI integration ids for the agent

toolActionConfigs
object[]

Optional updated per-tool-action configuration for the agent

Configuration for a specific tool action

modelAlias
any

Model alias must be a valid user-selectable model from the registry

reasoningEffort
enum<string> | null

Optional new reasoning level, from the levels the model offers; null restores the model default. When only the model changes, a level the new model does not offer is cleared. Applies with token-based pricing.

Available options:
none,
minimal,
low,
medium,
high,
xhigh,
max,
null
fastMode
boolean

Optionally turn fast mode on or off. Only models with a fast mode accept true; changing to a model without one turns it off. Applies with token-based pricing.

contextDocs
object[]

Optional new context documents for the agent

tinesStoryImportId
string<uuid> | null

Optional reference to the Tines story import template (can be set to null to clear)

planningMode
enum<string>

Optional new planning behavior for this agent

Available options:
never,
always,
auto
structuredOutputSchema
object | null

Optional updated structured output schema definition for this agent

persistentWorkspaceEnabled
boolean

Optional persistent workspace setting for this agent

slackReplyScope
enum<string> | null

Optional default Slack reply scope for chats not started by a Slack trigger (anyone | cotool_users)

Available options:
anyone,
cotool_users,
null
tags
string[]

Array of tags for categorizing the agent

A tag label for categorizing agents (normalized to lowercase)

Required string length: 1 - 100
skills
object[]

Optional set of skills to attach to this agent

acceptanceCriteria
string[]

Optional list of acceptance criteria evaluated for every run

Maximum array length: 20
Required string length: 1 - 500

Response

Successful response

The updated agent with modified configuration

id
string
required

Unique identifier for the agent

organizationId
string
required

Unique identifier of the organization that owns this agent

name
string
required

Human-readable name of the agent

description
string
required

Description of what the agent does and its purpose

systemPrompt
string
required

The agent's live system prompt (version history lives in agent_versions)

createdAt
string
required

Timestamp when the agent was created

updatedAt
string
required

Timestamp when the agent was last updated

deletedAt
string | null
required

Timestamp when the agent was soft-deleted, or null if not deleted

toolNames
string[]
required

Array of tool names that this agent can use during execution

toolSelectionMode
enum<string>
required

How this agent resolves tools at runtime

Available options:
manual,
all_read_only,
all_read_only_plus_selected
toolActionConfigs
object[]
required

Per-tool-action configuration for this agent

Configuration for a specific tool action

modelAlias
any
required

Model alias specifying which LLM model to use for this agent

planningMode
enum<string>
required

Planning behavior mode for the agent

Available options:
auto,
never,
always
agentType
enum<string>
required

Type of agent: response (standard) or detection (security detection)

Available options:
response,
detection
origin
enum<string>
required

Who created this agent: user or orchestrator

Available options:
user,
orchestrator
isBuiltIn
boolean
required

Whether this agent is built in to the system (true for built-in (system-managed) agents)

builtInAgentType
enum<string>
required

Type of built-in agent (e.g., threat-validation, threat-hunt)

Available options:
threat-relevancy,
threat-research,
autonomous-hunt,
detection-engineer,
code-detection-tuner,
detection-calibrator,
test-agent
inputs
array
required

Deprecated. Always empty; will be removed.

Required array length: 0 element
createdByUserId
string | null

User ID that created this agent, or null for system-created or unknown authorship

updatedByUserId
string | null

User ID that last edited this agent, or null for system edits or unknown authorship

createdBy
object | null

Display identity of the user that created this agent

updatedBy
object | null

Display identity of the user that last edited this agent

invocationCount
integer

All-time number of top-level invocations of this agent

Required range: x >= 0
invocationCount30d
integer

Number of top-level invocations of this agent in the last 30 days

Required range: x >= 0
lastInvokedAt
string | null

Timestamp of the most recent top-level invocation, or null if the agent has never been invoked

cliNames
string[]

Optional array of CLI integration ids that this agent can use during execution

reasoningEffort
enum<string> | null

Reasoning level the agent runs its model with, from the levels the model offers. Null keeps the model default. Applies with token-based pricing.

Available options:
none,
minimal,
low,
medium,
high,
xhigh,
max,
null
fastMode
boolean

Whether the agent runs its model in fast mode, at the fast-mode price. Only models with a fast mode use it. Applies with token-based pricing.

contextDocs
object[]

Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent

tinesStoryImportId
string | null

Optional reference to the Tines story import template used to create this agent

triggerSummary
object[]

Optional array of triggers configured for this agent

structuredOutputSchema
object | null

Optional JSON schema describing the structured output the agent should emit (may include x-cotool metadata for preset UX; metadata is stripped before sending to the LLM)

persistentWorkspaceEnabled
boolean

Whether this agent may use persistent workspace

tags
string[]

Array of tags for categorizing the agent

A tag label for categorizing agents (normalized to lowercase)

Required string length: 1 - 100
skills
object[]

Array of reusable skills attached to this agent

acceptanceCriteria
string[]

Optional list of acceptance criteria evaluated for every run

Maximum array length: 20

A user-configured acceptance criterion that must be satisfied for an agent run

Required string length: 1 - 500
slackReplyScope
enum<string> | null

Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)

Available options:
anyone,
cotool_users,
null
syncKey
string | null

Stable logical key for the agent (slug, immutable, unique per org)

syncSource
string | null

Sync backend managing this agent (e.g. "github"); null/absent when UI-managed

syncFilePath
string | null

Path of the source YAML file for a GitOps-managed agent

syncConfigId
string | null

Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed

syncSourceUrl
string | null

Link to the source YAML file on GitHub for a GitOps-managed agent. Only returned when retrieving a single agent; null when the agent is UI-managed or its repository is not configured

detectionCategory
enum<string> | null

Category of detection (only for detection agents)

Available options:
baseline_anomaly,
first_occurrence,
sequence_pattern,
privilege_escalation,
custom,
null
detectionQuery
string | null

The SIEM query for the detection (only for detection agents)

siemType
string | null

The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)

isSuggestion
boolean

Whether this detection is a suggestion (only for detection agents)

lastDetectionRunAt
string | null

Timestamp of when this detection was last run (only for detection agents)

legacyDetection
boolean

Client-side marker for a migrated legacy customer detection remapped to a unified agent