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

# Create agent

`POST /agents`

Create an agent

## Headers

- `Idempotency-Key` string, required
- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `name` string, required — Agent display name.
      - `description` string — Agent description.
      - `slug` string — Agent-specific part of the handle, such as support in @acme-support.
      - `limits` object — Agent spending limits. Agent credentials cannot set them.
        - `perTransaction` integer, nullable — Per-transaction spending limit in cents, or null for no limit.
        - `perDay` integer, nullable — Daily spending limit in cents, or null for no limit.
        - `perMonth` integer, nullable — Monthly spending limit in cents, or null for no limit.
      - `walletId` string — Wallet the agent is granted access to. Defaults to the party's default wallet when omitted.

## Response `201`

Successful Response

- object
  - `data` object, required
    - `type` 'agent', required
    - `id` string, required — Agent ID (agt_*).
    - `attributes` object, required
      - `name` string, required — Agent display name.
      - `description` string, nullable, required — Agent description.
      - `handle` string, nullable, required — Agent handle, such as @acme-support, or null if none is configured.
      - `status` 'ACTIVE' | 'REVOKED', required — Agent status.
      - `limits` object, nullable, required — Spend caps for actions this agent initiates on its owner's party.
        - `perTransaction` integer, nullable — Per-transaction spending limit in cents, or null for no limit.
        - `perDay` integer, nullable — Daily spending limit in cents, or null for no limit.
        - `perMonth` integer, nullable — Monthly spending limit in cents, or null for no limit.
      - `createdAt` string, date-time, nullable, required — When this agent was created.
      - `createdBy` string, nullable, required — User who created this agent (usr_*).
      - `lastActiveAt` string, date-time, nullable, required — When the agent last authenticated, or null if it has never authenticated.
    - `relationships` object, required
      - `party` object, required — Party that owns the agent.
        - `data` object, required — Related resource identifier.
          - `type` 'party', required
          - `id` string, required

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.net/natural/apis/natural-api.md) · [All operations](https://skmtc.net/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/natural/natural-api/versions/0123533d8361/schema)