Skip to main content
The persona routes manage an agent’s persona as numbered versions: create a version, make one current, generate a draft from a structured configuration, apply a preset, and ask for suggested improvements. Version routes are what lua push agent and lua persona call; drafts, presets, and the enhance routes have no CLI equivalent. Verified against lua-cli 3.33.0.

​
Base URL and authentication

Routes under :agentId check an agents scope on that agent: agents:read reads versions, agents:write creates, activates, drafts, publishes, enhances, and applies presets, and agents:manage discards a draft. The preset catalog needs only an authenticated key. The host, the bearer header, and the error envelope are on the REST API overview.

​
Persona version object

A persona is either a string or a channel-aware object { base?, voice?, text? }; both forms are accepted wherever a persona is sent and returned as stored. Creating a version serves it from the agent’s next message, and making an earlier version current switches the served persona at once, on any agent. An agent version records which persona version was current, but promoting one does not change the served persona.
​
number
Version number.
​
number
Unix time in milliseconds.
​
string
User ID of the creator.
​
boolean
Whether this version is the active persona.
​
string | object
The persona text or channel-aware object.

​
Endpoints

​
GET /developer/agents/:agentId/persona/versions

Lists the agent’s persona versions. Scope agents:read. Equivalent: lua persona production versions.
​
string
default:"all"
draft, published, or all.
Response 200 with { status, message, versions }, each entry a persona version object.

​
GET /developer/agents/:agentId/persona/version/:version

Returns one version with the configuration it was built from. Scope agents:read. Response 200 with { status, message, version }, where version carries id, agentId, version, persona, config (the structured configuration used to build it, when any), createdBy, and createdAt, plus the storage fields _id and __v.

​
POST /developer/agents/:agentId/persona/version

Creates a new persona version from text you supply. Scope agents:write. Equivalent: lua push agent, which creates a version from LuaAgent.persona.
​
string | object
required
The persona text, or { base?, voice?, text? }.
Response 201 with { status, message, version }, where version is the new version number.

​
POST /developer/agents/:agentId/persona/version/:version

Makes a version the current persona. Scope agents:write. Equivalent: lua persona production deploy --persona-version <n> or lua deploy persona. The agent serves that version from its next message, and a later agent-version promote does not change it, as described under Persona version object. Response 201 with { status, message, version }.

​
POST /developer/agents/:agentId/persona

Builds a persona from business details and stores it as a new version. Scope agents:write. The model writes the text.
​
string
What the business does.
​
string
Website to draw details from.
​
string
Name the agent should use.
​
string
deprecated
Use the draft routes’ personalityAndVoice instead.
​
string
deprecated
Use the draft routes’ personalityAndVoice instead.
Response 201 with { status, message, persona, version }.

​
POST /developer/agents/:agentId/persona/draft

Generates a draft from a structured configuration. Scope agents:write. A draft is a generated persona version held for testing until you publish or discard it; only one exists at a time, and creating another answers the existing one with status: "draft_exists" instead of replacing it. Each has… flag includes or omits its section; each list supplies that section’s statements.
​
string
Name the agent should use.
​
string
Website to draw details from.
​
string
Preset to base the configuration on.
​
object[]
Each { title, isEnabled }: tone choices.
​
string[]
Role statements. Included when hasRoleAndPurpose is true.
​
string[]
Audience statements. Included when hasContextAndAudience is true.
​
string[]
Personality traits. Included when hasPersonalityAndVoice is true.
​
string[]
Rules. Included when hasRulesAndBoundaries is true.
​
string
What the business does.
​
string[]
Product statements. Included when hasBusinessInfo is true.
​
boolean
Section switches.
​
string
Existing persona text to extract a configuration from, instead of the structured fields.
​
string
deprecated
Use personalityAndVoice.
Response 201 with { status: "draft", message, version, versionStatus: "draft", persona, config }, or status: "draft_exists" and the existing draft’s fields when one already exists.

​
PUT /developer/agents/:agentId/persona/draft

Regenerates the existing draft from a new configuration, with the same body and response as create. Scope agents:write.

​
POST /developer/agents/:agentId/persona/publish

Publishes the draft, making it the current persona. Scope agents:write. A draft whose text is empty is built from its configuration first.
​
number
required
The draft’s version number.
Response 201 with { status: "success", message, version, persona, versionStatus: "published" }.

​
DELETE /developer/agents/:agentId/persona/draft

Discards the draft without publishing. Scope agents:manage. Response 200 with { status, message }.

​
GET /developer/agents/persona/presets

Lists presets. Any authenticated key. A preset is a named, ready-made persona configuration, for example customer-support-expert, that you can start a draft from or apply to an agent’s configuration without generating new persona text. Response 200 with { status, presets: [{ id, title, description }] }.

​
GET /developer/agents/persona/presets/:presetId

Returns one preset. Any authenticated key. Response 200 with { status, preset }, where preset is the configuration object.

​
POST /developer/agents/:agentId/persona/preset/apply

Copies a preset into the agent’s persona configuration. Scope agents:write. Only the configuration changes; no persona version is generated.
​
string
required
Preset to apply.
Response 201 with { status, message, config }, where config is the applied configuration.

​
POST /developer/agents/:agentId/enhance/website

Reads a website and suggests persona text and configuration from it. Scope agents:write. The three enhance routes are non-destructive: each runs the model, can take minutes, and returns a suggestion for you to review without changing the agent. When currentPersona and currentConfig are omitted, the agent’s current values are used.
​
string
required
Site to read.
​
string
Persona text to improve.
​
object
Configuration to improve.
Response 201 with { suggestedPersona, suggestedConfig }.

​
POST /developer/agents/:agentId/enhance/storytelling

Suggests a version with more narrative depth and personality. Scope agents:write.
​
string
Persona text to improve.
​
object
Configuration to improve.
Response 201 with { suggestedPersona, suggestedConfig }.

​
POST /developer/agents/:agentId/enhance/instructions

Refines the persona from written instructions, from example replies that need improving, or both. Scope agents:write.
​
string
For example Make the agent more formal and professional.
​
object[]
Each { agentReply, reason, expectedReply }: a reply the agent gave, why it was wrong, and what it should have said.
​
string
Persona text to improve.
​
object
Configuration to improve.
Response 201 with { suggestedPersona, suggestedConfig }.

​
Errors

​
Example

Create a persona version from text; the agent serves it from its next message. The second call, POST …/persona/version/:version, is how you switch back to an earlier version, and on the version just created it changes nothing. To keep agent versions in step with the served persona, follow with lua version create and lua version promote.

​
See also