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

string

required

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

string

required

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

Request body

string

required

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

string

Optional human-readable description of what the agent does.

string

required

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

Response

number

1 on success.

string

"agent_created" on success.

object

Hide properties

object

Hide properties

string

UUID of the newly created agent.

string

Agent display name.

string

Agent description (empty string if not provided).

string

LLM provider name.

string

UUID of the project this agent belongs to.

string

UUID of the user who created the agent.

string

ISO 8601 timestamp of when the agent was created.

object

Hide properties

string

UUID of the generated AgentKey record.

string

Short prefix used to look up the key during authentication.

string

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

string

UUID of the agent this key belongs to.

string

ISO 8601 timestamp of key creation.

string

ISO 8601 timestamp — 30 days after creation.

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

​Endpoint

​Request headers

​Request body

​Response

​Example

​Errors

Endpoint

Request headers

Request body

Response

Example

Errors