v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Update an agent

Updates one or more fields on an existing agent. Only the fields you supply are changed; omitted fields retain their current values.

To clear the agent's default model, pass model as an empty string. The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

patch/api/v1/agents/{agent}

Path parameters

agentstring required

ID (agi_...) or lookup_key of the agent to update.

Request body

emailstring

New email address for the agent.

identitystring

Replacement identity system-prompt string describing who the agent is.

lookup_keystring

New lookup_key slug. Must be unique within the owning app or org.

metadataobject

Replacement key-value metadata map. The entire map is replaced, not merged.

modelstring

New default AI model identifier, e.g. claude-sonnet-4-5. Pass an empty string to clear the agent's default model.

namestring

New display name for the agent.

orgstring

Organization ID (org_...) to transfer ownership to.

originatorstring

Replacement originator label identifying the source or author of the agent.

phone_numberstring

New phone number for the agent in E.164 format, e.g. +15550001234.

teamstring

Team ID (team_...) to transfer ownership to.

userstring

User ID (usr_...) to transfer ownership to.

Example request

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "email": "user@example.com",
  "identity": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "model": "string",
  "name": "Example Name",
  "org": "string",
  "originator": "string",
  "phone_number": "+15555550123",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "team": "string",
  "user": "string"
}

Response

Successful response

appstring

ID of the application that owns this agent (dap_...).

created_atstring date-time

When the agent was created (ISO 8601).

default_modelstring

Default LLM model identifier used by this agent when no model is specified at runtime (e.g. "claude-3-7-sonnet-latest").

emailstring

Email address provisioned for this agent. null if email delivery is not configured.

idstring required

Agent ID (agi_...).

identitystring

System-level identity prompt that shapes the agent's persona and behavior.

last_applied_template_configstring

ID of the AgentTemplate config (cfg_...) this agent was last provisioned or updated from. null for manually created agents.

lookup_keystring

Stable, user-defined identifier for this agent within the application. Unique per app.

metadataobject

Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.

namestring

Human-readable display name for the agent. null if not set.

orgstring

ID of the organization this agent belongs to (org_...). null if the agent is not org-scoped.

org_namestring

Display name of the organization this agent belongs to. null when the agent is not org-scoped or when the org association was not preloaded.

originatorstring

Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).

phone_numberstring

Phone number provisioned for this agent. null if SMS is not configured.

sandboxstring

ID of the sandbox environment this agent is scoped to (dsb_...). null in production deployments.

teamstring

ID of the team that owns this agent (tem_...). null if the agent is not team-scoped.

updated_atstring date-time

When the agent was last modified (ISO 8601).

userstring

ID of the user that owns this agent (usr_...). null if the agent is not user-scoped.

Example response

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "default_model": "claude-3-7-sonnet-latest",
  "email": "user@example.com",
  "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "identity": "You are a helpful assistant that answers questions about ArchAstro products.",
  "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "org_name": "Example Name",
  "originator": "deploy-pipeline",
  "phone_number": "+15555550123",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "source_solution": {
    "solution": {
      "category_keys": [
        "string"
      ],
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "Solution",
      "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "latest_version": "1.0.0",
      "lookup_key": "string",
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "org_logo": {
        "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
        "height": 600,
        "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
        "mime_type": "application/json",
        "refresh_url": "https://example.com",
        "url": "https://example.com",
        "width": 800
      },
      "org_name": "Example Name",
      "org_slug": "example-slug",
      "owners": [
        "string"
      ],
      "readme_url": "https://example.com",
      "solution_id": "01234567-89ab-cdef-0123-456789abcdef",
      "solution_version": "1.2.0",
      "tag_keys": [
        "string"
      ],
      "template_kind": "AgentTemplate",
      "templates": [
        {
          "description": "An example description.",
          "display_name": "Example Name",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "AgentTemplate",
          "lookup_key": "string",
          "name": "Example Name",
          "readme_url": "https://example.com",
          "virtual_path": "string"
        }
      ],
      "updated_at": "2024-01-01T00:00:00Z",
      "upgrade_available": true,
      "virtual_path": "string"
    },
    "template": {
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "display_name": "Example Name",
      "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "agent_tool_template",
      "lookup_key": "string",
      "name": "Example Name",
      "updated_at": "2024-01-01T00:00:00Z",
      "virtual_path": "string"
    }
  },
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}