Set the graph conductor of a v2 avatar
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.
X-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_....
avatarId*stringuuidapplication/json- 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?numberSeconds 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).
double0.1 <= value <= 10Saved; returns the conductor.
application/json- response
avatarId*stringuuidgraph*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?numberAs set; absent when it was not (Causeur's default applies, 0.5 today).
doublenodes*integerThe graph's node count.
edges*integerThe graph's edge count, all nodes together.
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" } ] }}'{ "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}Remove the graph conductor of a v2 avatar DELETE
The next session runs without a conductor, also one the avatar's own config carries (a running session keeps the one it started with).
Sponsor pool balance and settings GET
Callable by an API key (avatars:read) or a signed-in user acting for the account.

