Skip to main content
POST
/
agents
cURL
curl --request POST \
  --url https://api.useanima.sh/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "slug": "<string>",
  "orgId": "<string>",
  "email": "jsmith@example.com",
  "provisionPhone": false,
  "metadata": {},
  "inboxId": "<string>"
}
'
{
  "id": "<string>",
  "orgId": "<string>",
  "name": "<string>",
  "slug": "<string>",
  "apiKeyPrefix": "<string>",
  "keyRotatedAt": "2023-11-07T05:31:56Z",
  "metadata": {},
  "emailIdentities": [
    {
      "id": "<string>",
      "email": "jsmith@example.com",
      "domain": "<string>",
      "localPart": "<string>",
      "isPrimary": true,
      "verified": true,
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "phoneIdentities": [
    {
      "id": "<string>",
      "phoneNumber": "<string>",
      "provider": "<unknown>",
      "providerId": "<string>",
      "capabilities": {
        "sms": false,
        "mms": false,
        "voice": false
      },
      "isPrimary": true,
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "readiness": {
    "canSendEmail": true,
    "canReceiveEmail": true,
    "canSendSms": true,
    "canPlaceVoiceCall": true,
    "blockers": [
      {
        "field": "<string>",
        "hint": "<string>",
        "remediationUrl": "<string>"
      }
    ]
  }
}

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

Request body for creating a new agent

name
string
required

Human-readable display name for the agent

Required string length: 2 - 100
slug
string
required

URL-friendly unique identifier (lowercase alphanumeric and hyphens only)

Required string length: 2 - 64
Pattern: ^[a-z0-9-]+$
orgId
string

Organization ID that owns this agent (derived from auth if omitted)

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
email
string<email>

Optional email address to provision for this agent

provisionPhone
boolean
default:false

Whether to automatically provision a phone number for this agent

metadata
object

Arbitrary key-value metadata associated with the agent

inboxId
string

ID of an existing inbox to associate with this agent. If omitted, a new inbox is created automatically.

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$

Response

200 - application/json

OK

Full agent resource representation

id
string
required

Unique identifier of the agent

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
orgId
string
required

Organization ID that owns this agent

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
name
string
required

Human-readable display name

slug
string
required

URL-friendly unique identifier

status
enum<string>
required

Current lifecycle status

Available options:
ACTIVE,
SUSPENDED,
DELETED
apiKeyPrefix
string | null
required

Prefix of the agent's API key for identification, or null if no key is set

keyRotatedAt
string<date-time> | null
required

ISO 8601 timestamp of the last API-key rotation, null if never rotated

metadata
object
required

Arbitrary key-value metadata

emailIdentities
object[]
required

Email identities associated with this agent

phoneIdentities
object[]
required

Phone identities associated with this agent

createdAt
string<date-time>
required

Timestamp when the agent was created

updatedAt
string<date-time>
required

Timestamp when the agent was last updated

readiness
object

Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed.