---
title: "Change an agent"
method: PATCH
path: "/agents/{id}"
tags: ["Agents"]
---

# Change an agent

`PATCH /agents/{id}`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/agents/{id}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `project:write`)

Changes the name, instructions, trigger, actions (the whole set: anything not listed is denied), limits or status. Fields you leave out stay as they are. status paused stops new runs; active starts them again.

## Path parameters

- `id` string, uuid, required

## Request body

- object: Changes to an agent. Fields you leave out stay as they are.
  - `name` string: A short name, like New contact request follow-up.
  - `instructions` string: What the agent should do, in plain language, like: Send the owner a short summary of every new contact request and propose a call back.
  - `trigger` union: When the agent runs: a new document in a collection, a finished call, a closed chat conversation (once its summary is ready), or a schedule (every_minutes, at least 15).
    - object
      - `type` 'document.created', required
      - `collection` string, required: The id or the name of the collection, like contact_requests.
      - `phone_field` string: The field of the document that holds the phone number, like phone. Needed for send_sms and start_call; the agent never takes a number from anywhere else.
      - `email_field` string: The field of the document that holds the email address, like email. Needed for email_contact; the agent never takes an address from anywhere else.
    - object
      - `type` 'call.completed', required
    - object
      - `type` 'conversation.closed', required
    - object
      - `type` 'schedule', required
      - `every_minutes` integer, required
  - `actions` object: The actions this agent may take. Anything not listed is denied.
    - `read_document` object: Read a document of the trigger's collection, or of the collections you list. Always without asking.
      - `collections` string[]: The collections (names or ids) this action may use. Default: only the collection of a document.created trigger.
    - `update_document` object: Change fields of a document (a merge) in the trigger's collection, or in the collections you list. Default mode auto.
      - `mode` 'auto' | 'approve': auto: the agent does it without asking. approve: the action waits until the owner approves it (in the portal or with approve_agent_action).
      - `collections` string[]: The collections (names or ids) this action may use. Default: only the collection of a document.created trigger.
    - `email_owner` object: Email the project owner (the billing email of the project). Nobody else. Default mode auto.
      - `mode` 'auto' | 'approve': auto: the agent does it without asking. approve: the action waits until the owner approves it (in the portal or with approve_agent_action).
    - `email_contact` object: Only with the Mail module. Email the person of the event: the address in trigger.email_field of the document, or the customer of the chat. No other address. Default mode approve; always approve for a public form or a chat. At most one per address per day. Simulated in test mode.
      - `mode` 'auto' | 'approve': auto: the agent does it without asking. approve: the action waits until the owner approves it (in the portal or with approve_agent_action).
      - `from` string, required: The sender, on a verified sending domain of this project, like "Acme Plumbing <hello@acmeplumbing.com>".
      - `reply_to` string: Optional. Where replies go, like the owner's mailbox.
    - `send_sms` object: Send an SMS to the phone number of the event (trigger.phone_field of the document, the other side of the call, or the customer of the chat). Default mode approve; always approve for a public form, a call or a chat. At most one per number per day. Simulated in test mode.
      - `mode` 'auto' | 'approve': auto: the agent does it without asking. approve: the action waits until the owner approves it (in the portal or with approve_agent_action).
    - `start_call` object: Let the project's assistant call the phone number of the event (as for send_sms). Default mode approve; always approve for a public form, a call or a chat. At most one per number per day. Simulated in test mode.
      - `mode` 'auto' | 'approve': auto: the agent does it without asking. approve: the action waits until the owner approves it (in the portal or with approve_agent_action).
    - `send_webhook` object: POST a signed agent.action event to one of the project's own webhook endpoints (list_webhooks). Default mode auto.
      - `mode` 'auto' | 'approve': auto: the agent does it without asking. approve: the action waits until the owner approves it (in the portal or with approve_agent_action).
      - `endpoint_id` string, uuid, required
  - `limits` object: The limits of the agent.
    - `runs_per_day` integer: Runs in any 24 hours; above it a run is skipped and logged. Default 20.
    - `actions_per_run` integer: Actions the agent may take in one run, refused ones included. Default 3.
  - `status` 'active' | 'paused': paused stops new runs; active starts them again.

## Response `200`

The agent as it is now.

- object: An agent that keeps working for the project: a trigger, instructions, actions and limits.
  - `id` string, uuid, required
  - `name` string, required
  - `instructions` string, required
  - `trigger` object, required
  - `actions` object, required
  - `limits` object, required
    - `runs_per_day` integer, required
    - `actions_per_run` integer, required
  - `status` 'active' | 'paused', required
  - `mode` 'live' | 'test', required
  - `next_run_at` string, nullable, required
  - `pending_approvals` integer, required
  - `created_by` string, nullable, required: The key (key:<id>) or connected app (oauth:<id>) that created the agent.
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `402`: Payment Required: insufficient_balance.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `404`: Not Found: not_found.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)