POST /api/agent/v1/create/

Creating an agent registers an AI system with OTAS under a specific project and automatically generates the initial AgentKey used to authenticate sessions. The full API key is included in this response — it is never retrievable again after creation, so store it immediately in a secrets manager or environment variable.

Only users with Admin privilege (privilege=1) on the project can create agents.

Endpoint

POST /api/agent/v1/create/

Base URL: http://localhost:8000

Request headers

X-OTAS-USER-TOKEN

string

required

JWT obtained from the OTAS login endpoint, identifying the calling user.

X-OTAS-PROJECT-ID

string

required

UUID of the project in which the agent will be created.

Request body

agent_name

string

required

Display name for the agent. Whitespace is trimmed before storage.

agent_description

string

Optional human-readable description of what the agent does.

agent_provider

string

required

LLM provider for this agent, e.g. "Anthropic" or "OpenAI".

Response

status

number

1 on success.

status_description

string

"agent_created" on success.

response

object

Hide properties

agent

object

Hide properties

string

UUID of the newly created agent.

name

string

Agent display name.

description

string

Agent description (empty string if not provided).

provider

string

LLM provider name.

project_id

string

UUID of the project this agent belongs to.

created_by

string

UUID of the user who created the agent.

created_at

string

ISO 8601 timestamp of when the agent was created.

agent_key

object

Hide properties

string

UUID of the generated AgentKey record.

prefix

string

Short prefix used to look up the key during authentication.

api_key

string

Full API key in the format agent_<prefix>_<secret>. Shown only once.

agent_id

string

UUID of the agent this key belongs to.

created_at

string

ISO 8601 timestamp of key creation.

expires_at

string

ISO 8601 timestamp — 30 days after creation.

active

boolean

true immediately after creation.

The full api_key value is returned only in this response. The plaintext key is never stored by OTAS and cannot be retrieved later. Save it to a secrets manager or environment variable immediately.

Example

cURL

curl --request POST \
  --url http://localhost:8000/api/agent/v1/create/ \
  --header "X-OTAS-USER-TOKEN: <your-user-jwt>" \
  --header "X-OTAS-PROJECT-ID: 4b7e2f1a-9c3d-4e8b-a012-3f5d6e7c8b9a" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_name": "Summarizer",
    "agent_description": "Summarizes long documents",
    "agent_provider": "Anthropic"
  }'

Response (201)

{
  "status": 1,
  "status_description": "agent_created",
  "response": {
    "agent": {
      "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
      "name": "Summarizer",
      "description": "Summarizes long documents",
      "provider": "Anthropic",
      "project_id": "4b7e2f1a-9c3d-4e8b-a012-3f5d6e7c8b9a",
      "created_by": "a1b2c3d4-e5f6-7890-abcd-ef0987654321",
      "created_at": "2026-04-16T10:00:00.000000+00:00"
    },
    "agent_key": {
      "id": "c9d8e7f6-a5b4-3210-fedc-ba9876543210",
      "prefix": "xYz1Ab2C",
      "api_key": "agent_xYz1Ab2C_s3cr3tT0k3nV4lueG0esH3re...",
      "agent_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
      "created_at": "2026-04-16T10:00:00.000000+00:00",
      "expires_at": "2026-05-16T10:00:00.000000+00:00",
      "active": true
    }
  }
}

Errors

Status	`status_description`	Cause
403	`forbidden`	Caller does not have Admin privilege on the project.
400	`agent_creation_failed`	`agent_name` or `agent_provider` is missing, or the request body is not valid JSON.

UASAM — Users & Auth

UASAM — Projects & Keys

UASAM — Agents

Brain — Event Capture

Brain — Analytics

POST /api/agent/v1/create/

Endpoint

Request headers

Request body

Response

Example

Errors

Build docs developers (and LLMs) love

UASAM — Users & Auth

UASAM — Projects & Keys

UASAM — Agents

Brain — Event Capture

Brain — Analytics

​Endpoint

​Request headers

​Request body

​Response

​Example

​Errors

Build docs developers (and LLMs) love

Endpoint

Request headers

Request body

Response

Example

Errors