Create an agent

Create a new AI agent. Supports the Idempotency-Key header for safe retries.

POST /api/v1/agents

Create a new AI agent. Honors the Idempotency-Key header so retries don't create duplicates, see Idempotency.

Scope: agents:write

Request body

Field	Type	Required	Notes
`handle`	string	yes	camelCase alphanumeric. Must be unique within the org (case-insensitive).
`name`	string	yes	Display name.
`instructions`	string	yes*	Plain text. Required unless `instructions_html` is provided.
`instructions_html`	string	no	Rich text (HTML subset). Plain text is auto-derived for the system prompt.
`description`	string \| null	no	Short summary, surfaced in the dashboard agent list.
`model`	string	no	Model ID. Defaults to org default.
`color`	string	no	Hex color. Defaults to `#6366f1`.
`avatar`	string	no	Emoji or URL.
`include_system_prompt`	boolean	no	Defaults to `true`.
`tools`	array	no	Array of `{ name, connector_id }` tool refs. See below.
`connectors`	array	no	Array of connector IDs. Derived from `tools[].connector_id` if omitted.
`sub_agents`	array	no	Array of agent IDs to delegate to (handoff pattern). Cannot include this agent's own ID.
`data_sources`	array	no	Array of `{ source_id, scope, documents }` data source refs.

Sub-shapes

Tool reference

{
  "name": "zendesk_get_ticket",
  "connector_id": "connector_64f1c0ef2ec711ef6dc1dcf"
}

name is the base tool name (never the multi-instance suffix). connector_id may be null for built-in / knowledge tools.

Data source reference

{
  "source_id": "source_64f1c0ef2ec711ef6dc1dcf",
  "scope": "selected",
  "documents": ["doc_abc...", "doc_def..."]
}

scope is "all" or "selected". When "selected", documents[] is required.

Example request

curl -X POST https://dashboard.getmacha.com/api/v1/agents \
  -H "Authorization: Bearer $MACHA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "handle": "wismo",
    "name": "WISMO",
    "instructions": "Answer Where Is My Order questions using the Shopify order tool. Never make up tracking info.",
    "model": "gpt-5",
    "tools": [
      { "name": "shopify_get_order",        "connector_id": "connector_abc..." },
      { "name": "shopify_search_orders",    "connector_id": "connector_abc..." },
      { "name": "zendesk_add_public_reply", "connector_id": "connector_def..." }
    ]
  }'

Example response (201)

{
  "data": {
    "id": "agent_6a39a4f1c0ef2ec711ef6dc1",
    "handle": "wismo",
    "name": "WISMO",
    "model": "gpt-5",
    "is_active": true,
    "color": "#6366f1",
    "tools_count": 3,
    "sub_agents_count": 0,
    "created_at": "2026-06-24T10:42:00.000Z",
    "updated_at": "2026-06-24T10:42:00.000Z"
  },
  "meta": { "request_id": "req_..." }
}

Errors

Status	Code	When
`401`	`unauthorized`	Bad / missing key.
`403`	`insufficient_scope`	Key lacks `agents:write`.
`409`	`agent_handle_taken`	Another agent already uses this handle.
`409`	`idempotency_key_reused`	`Idempotency-Key` already used with a different body.
`422`	`validation_failed`	Missing required field, bad handle format, unknown sub-agent, plan limit reached.
`429`	`rate_limited`	Per-key ceiling exceeded.