Create or fetch a persona

Create a persona binding for a namespace. Idempotent on (orgId, namespace_id) — a second call for the same namespace returns the existing binding with status 200. The first call returns 201. The subject is set on the first call only; later calls with a different value are ignored. Provide exactly one of namespace_id or external_reference_id.

POST /personas

Create or fetch a persona

cURL

curl --request POST \
  --url https://api.deyta.ai/gateway/v1/personas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subject": "<string>",
  "namespace_id": "<string>",
  "external_reference_id": "<string>"
}
'

200

{
  "success": true,
  "data": {
    "agent_id": "8f37a51e-2c09-4d3c-9b4e-1f4f5b9e7a02",
    "namespace_id": "ns_abc123",
    "subject": "Filip Petrovic",
    "role": "primary",
    "has_built": false,
    "created_at": "2026-04-27T12:00:00Z",
    "last_built_at": null
  }
}

Authorizations

Authorization · string · header · required

API key obtained from the Deyta Console

Body

application/json

subject · string · required

Display name for the persona. Set on first create only; ignored on subsequent calls.

Required string length: 1 - 255

namespace_id · string

Namespace ID. Required if external_reference_id is not provided.

external_reference_id · string

External reference ID for the namespace. Case-sensitive — must match exactly the value used on namespace creation.

Response

200

application/json

Existing binding returned (idempotent path)

success · boolean

Example:

true

data · object

Lightweight record returned when a persona is created or fetched. Identifies the underlying Anima agent and its build state.

Show child attributes