Getting Started›First Agent

First Agent

POST/v1/agentsproject:agent

Last updated 2026-02-07

Create request

bash

curl -X POST "$ROOAAK_BASE_URL/v1/agents" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant",
    "externalId": "customer-user-123",
    "personality": "Helpful and concise",
    "contextUrl": "https://your-app.com/api/agent-context/customer-user-123",
    "alwaysOn": false
  }'

Notes from implementation

name is required.
userId is optional, but if provided must be a UUID.
If userId is omitted, Rooaak uses generated agentId as fallback userId.
alwaysOn=true is gated by plan entitlement.
Agent count is checked against project plan limits.

Response

json

{
  "id": "uuid",
  "userId": "uuid",
  "externalId": "customer-user-123",
  "name": "Support Assistant",
  "status": "none",
  "configVersion": 1,
  "appliedConfigVersion": 0,
  "pendingConfig": false,
  "lastAppliedAt": null,
  "createdAt": "2026-02-07T00:00:00.000Z",
  "updatedAt": "2026-02-07T00:00:00.000Z"
}