v1

latestOpenAPI 3.0.02026-07-26870415.2 KB

agents

Patch V2 chat agent

Updates mutable V2 chat agent fields. skill_ids and triggers replace the existing values when provided.

patch/v1/agents/{id}

Path parameters

idstring required

Agent id.

Example:ag77c0dy0mgdpzmqz6tesry8w184002s

Query parameters

workspace_idstring

Optional workspace override. If omitted, Conduit resolves the agent's workspace automatically.

Example:j57demo8f8x7c9v0n2q4r6t8y1u3i5o

Request body

namestring

descriptionstring nullable

colorstring nullable

icon_idinteger nullable

instructionsstring nullable

modelstring nullable

Override the LLM this agent runs on. Must be a model_string from GET /v1/models (MCP: list_supported_models), e.g. openai:gpt-4o. Omit to leave unchanged; send null to reset to the workspace default. Reads return the configured value, or default when none is set.

skill_idsstring[]

operation_mode'autopilot' | 'copilot' | 'inactive'

custom_response_delay_msinteger nullable

auto_mark_as_doneboolean

responseflowboolean

enabledboolean

Example request

{
  "description": "Handles reservation, cancellation, and refund flows.",
  "color": "#2563EB",
  "icon_id": 12,
  "operation_mode": "copilot",
  "skill_ids": [
    "ks77c0dy0mgdpzmqz6tesry8w184002s"
  ],
  "triggers": [
    {
      "id": "tr77c0dy0mgdpzmqz6tesry8w184002s",
      "name": "All Messages",
      "description": "Runs for every inbound message.",
      "type": "message",
      "config": {
        "scopeType": "all"
      },
      "enabled": true
    },
    {
      "id": "tr88c0dy0mgdpzmqz6tesry8w184003s",
      "name": "SMS Channel",
      "description": "Runs only for SMS channel messages.",
      "type": "message",
      "config": {
        "scopeType": "channel",
        "channelType": "sms"
      },
      "enabled": true
    }
  ]
}

Response

Agent updated

Example response

{
  "data": {
    "id": "ag77c0dy0mgdpzmqz6tesry8w184002s",
    "workspace_id": "j57demo8f8x7c9v0n2q4r6t8y1u3i5o",
    "name": "Reservations",
    "description": "Handles booking and cancellation flows.",
    "color": "#2563EB",
    "icon_id": 12,
    "version": "v2",
    "instructions": "Answer booking questions, use policies before escalating, and keep replies concise.",
    "model": "default",
    "guardrails": [
      {
        "id": "guardrail_1",
        "title": "Do not promise refunds",
        "knowledge": "Only cite refund terms from approved policy docs or escalate."
      }
    ],
    "operation_mode": "autopilot",
    "autopilot_schedule": null,
    "custom_response_delay_ms": 10000,
    "auto_mark_as_done": false,
    "response_language": "English",
    "responseflow": true,
    "output_schema": [
      {
        "name": "resolution",
        "description": "Short summary of the final outcome.",
        "type": "string",
        "is_required": true
      }
    ],
    "skill_ids": [
      "ks77c0dy0mgdpzmqz6tesry8w184002s"
    ],
    "connection_ids": [
      "cn77c0dy0mgdpzmqz6tesry8w184002s"
    ],
    "enabled": true,
    "triggers": [
      {
        "id": "tr77c0dy0mgdpzmqz6tesry8w184002s",
        "workspace_id": "j57demo8f8x7c9v0n2q4r6t8y1u3i5o",
        "name": "All Messages",
        "description": "Runs for every inbound message.",
        "type": "message",
        "config": {
          "scopeType": "all"
        },
        "enabled": true,
        "created_at": "2026-04-01T17:22:10.000Z",
        "updated_at": "2026-04-03T03:14:15.000Z"
      },
      {
        "id": "tr88c0dy0mgdpzmqz6tesry8w184003s",
        "workspace_id": "j57demo8f8x7c9v0n2q4r6t8y1u3i5o",
        "name": "Contact Inbox",
        "description": "Runs only for contact-type inbox messages.",
        "type": "message",
        "config": {
          "scopeType": "inbox",
          "inboxTypeId": "guest"
        },
        "enabled": true,
        "created_at": "2026-04-01T17:22:10.000Z",
        "updated_at": "2026-04-03T03:14:15.000Z"
      },
      {
        "id": "tr99c0dy0mgdpzmqz6tesry8w184004s",
        "workspace_id": "j57demo8f8x7c9v0n2q4r6t8y1u3i5o",
        "name": "SMS Channel",
        "description": "Runs only for SMS channel messages.",
        "type": "message",
        "config": {
          "scopeType": "channel",
          "channelType": "sms"
        },
        "enabled": true,
        "created_at": "2026-04-01T17:22:10.000Z",
        "updated_at": "2026-04-03T03:14:15.000Z"
      }
    ],
    "created_at": "2026-04-01T17:22:10.000Z",
    "updated_at": "2026-04-03T03:14:15.000Z"
  }
}