Atmee.aiDocs
APIAPI referenceAvatars

Set the graph conductor of a v2 avatar

PUT
/v1/avatars/{avatarId}/conductor

Gives the avatar's conversations an agenda: a graph of steps, each with the avatar's instructions while the conversation is in it, and edges that say when it moves on. At the end of every turn a judge model gives each condition (when) of the current step the probability that it holds; edges without a condition share the probability that none holds, by weight. The step then takes its likeliest edge (or, marked random, draws one). A step without edges is the end. An edge marked speak, taken after an avatar turn, has the avatar go on under the next step without waiting for the user (speakAfterS seconds later; absent, Causeur's default).

v2 avatars only: a v1 avatar is refused (409 not_v2_avatar). The conductor runs on Causeur, the conversation runtime v2 sessions are moving to; it has no effect on a session the behavior module runs. It replaces any earlier conductor, and any conductor the avatar's own config carries, and applies from the next session (a running session keeps what it started with). Nothing is rebuilt or captured, and the serving candidate stays. A session whose whole payload would exceed Causeur's limit (262,144 characters, the avatar's persona and config included) starts without the conductor.

The graph is checked before it is saved, with Causeur's own rules and limits; a refusal names the field (400 invalid_conductor, /graph/nodes/2/edges/0/weight: ...; a value of the wrong JSON type is 422). Limits: at most 100 nodes and 100 edges in all; node ids [a-z][a-z0-9_]{0,39} and not none, unique; instructions at most 1000 characters; a condition at most 300; a weight above 0 and at most 1000, and only on an edge without a condition (default 1); one edge with a condition and one without per target at most; every node reachable from start, every edge to a node of the graph, a speak edge only into a step with instructions. Not accepted here: replan steps (the graph runs as given), text holding a !<...>! placeholder or starting with supabase/, and a graph over 150,000 characters of JSON (non-ASCII characters count as their \uXXXX escapes), which leaves over 110,000 characters for the rest of the session (a v2 avatar's own config is typically under 15,000). Only graph and speakAfterS are accepted at the top level. The request body may be up to 512 KiB.

Authorization

headerX-Api-Key<token>

Secret embed API key (sk_atmee_...; keys minted before 2026-09 carry sk_live_...), held by the customer's own backend and never sent to a browser. Format: X-Api-Key: sk_atmee_....

Path Parameters

avatarId*string
Formatuuid

Request Body

application/json
  1. body
graph*

The steps of the conversation (nodes) and the one it starts in (start). Every node must be reachable from start. Only start, nodes and reasoning are accepted.

speakAfterS?number

Seconds after an avatar turn before the avatar speaks again along a speak edge, if the user has not taken the floor. 0.1 to 10; absent or null: Causeur's default (0.5 today).

Formatdouble
Range0.1 <= value <= 10

Response Body

Saved; returns the conductor.

application/json
  1. response
avatarId*string
Formatuuid
graph*

The steps of the conversation (nodes) and the one it starts in (start). Every node must be reachable from start. Only start, nodes and reasoning are accepted.

speakAfterS?number

As set; absent when it was not (Causeur's default applies, 0.5 today).

Formatdouble
nodes*integer

The graph's node count.

edges*integer

The graph's edge count, all nodes together.

Example Request
curl -X PUT 'https://api.atmanity.us/v1/avatars/497f6eca-6276-4993-bfeb-53cbbbba6f08/conductor' \  -H 'Content-Type: application/json' \  -d '{  "graph": {    "start": "string",    "nodes": [      {        "id": "string"      }    ]  }}'
Example Response
{  "avatarId": "ac572b6e-802b-4b9e-a602-0786d4441e67",  "graph": {    "start": "string",    "nodes": [      {        "id": "string",        "instructions": "string",        "edges": [          {            "to": "string",            "when": "string",            "weight": 0.1,            "speak": true          }        ],        "random": true,        "emotion": "string",        "role_play": true,        "languages": [          "string"        ],        "replan": true      }    ],    "reasoning": null  },  "speakAfterS": 0.1,  "nodes": 0,  "edges": 0}
Set the graph conductor of a v2 avatar — Atmee Docs