---
title: "Create an agent"
method: POST
path: "/agents"
tags: ["Agents"]
---

# Create an agent

`POST /agents`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/agents`
- 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`)

An agent keeps working for your project after the chat: on a trigger (a new document in a collection, a finished call, a closed chat conversation, or a schedule of at least every 15 minutes) it follows your instructions with a small set of actions on Hypamoon: read or update a document, email the owner, send an SMS, start a call, send a webhook to one of your own endpoints. Default deny: an action that is not turned on is refused. SMS and calls go only 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), at most once per number per day, never to the project's own numbers; they wait for the owner's approval, and always do so when the trigger can come from a stranger (a public form, a call, a chat). In test mode they are simulated; in live mode they need a verified project. Limits: runs per day (default 20) and actions per run (default 3). At most 10 agents per project. Every run is logged with its trigger, a short thought, each action and the model cost. The key needs the scope of every action it turns on (calls:write for start_call, messages:write for send_sms, data:write for update_document, webhooks:write for send_webhook) and of the trigger.

## Request body

- object: A new agent.
  - `name` string, required: A short name, like New contact request follow-up.
  - `instructions` string, required: 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, required: 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, required: 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': active (default) or paused.

## Response `201`

The new agent.

- 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.
- `409`: Conflict: conflict.
- `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)