Agents
List agents
Newest first.
Required scope: agents:read.
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
statusslugExact match on the agent slug.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List agents › Responses
Create an agent
Creates a draft agent from scratch (name, instructions and llmConfig) or from a template with fromTemplate. Anything you send overrides the template. llmConfig.model is a public id from GET /v2/models such as anthropic/claude-sonnet-4.6. Activate it when it is ready. audience internal creates a copilot for your team that can use the tools of your data connector (dct_): it needs the scope agents:internal, cannot come from a template and cannot be changed later; you operate it afterwards like any agent.
Required scope: agents:write.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Create an agent › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: fromTemplate | |
| type = object · requires: name, instructions, llmConfig |
fromTemplateA template from GET /v2/agent-templates.
audiencecustomers: the agent talks to your customers. internal: a copilot that answers your team and can use the tools of your data connector (dct_) to read your back office. Creating an internal one needs the scope agents:internal (403 scope_missing otherwise) and it cannot be made from a template. It cannot be changed later.
nameRequired unless fromTemplate is set.
descriptioninstructionsHow the agent behaves. Required unless fromTemplate is set. May hold {{name}} placeholders.
Values for the {{name}} placeholders in the instructions, and any fact the agent should know. Replaces the whole map. Every placeholder needs a value or the answer is 422 template_variable_missing.
Required unless fromTemplate is set.
maxTokensmaxIterationschannelsWhere the agent answers. An empty list means every channel.
avatarCreate an agent › Responses
objectidnameaudiencecustomers: talks to your customers. internal: a copilot for your team created with the scope agents:internal.
descriptionstatusversionGoes up on every change. Send it back as expectedVersion.
instructionsAs you wrote them, with the {{name}} placeholders still in place.
maxTokensmaxIterationschannelsavatarcreatedAtupdatedAtRetrieve an agent
Returns one agent by id. Use it to refresh a single record you already know; to find records, use the list route. To change it, use the update route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.
Required scope: agents:read.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Retrieve an agent › Responses
objectidnameaudiencecustomers: talks to your customers. internal: a copilot for your team created with the scope agents:internal.
descriptionstatusversionGoes up on every change. Send it back as expectedVersion.
instructionsAs you wrote them, with the {{name}} placeholders still in place.
maxTokensmaxIterationschannelsavatarcreatedAtupdatedAtDelete an agent
Answers 409 resource_in_use while the agent has open conversations or serves a pipeline stage.
Required scope: agents:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Delete an agent › Responses
Deleted.
Update an agent
Changes only what you send. Changing instructions or variables creates a version. Send expectedVersion so two people cannot overwrite each other: if someone saved first you get 409 agent_version_conflict. llmConfig replaces the whole model configuration; send model as a public id from GET /v2/models.
Required scope: agents:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Update an agent › Request Body optional
namedescriptioninstructionsCreates a version. May hold {{name}} placeholders; they are filled with variables.
Values for the {{name}} placeholders in the instructions, and any fact the agent should know. Replaces the whole map. Every placeholder needs a value or the answer is 422 template_variable_missing. Creates a version.
maxTokensmaxIterationschannelsWhere the agent answers. An empty list means every channel.
Merged into the current behaviors, key by key.
avatarexpectedVersionThe version you read. If someone saved first the answer is 409 agent_version_conflict and nothing is written.
Update an agent › Responses
objectidnameaudiencecustomers: talks to your customers. internal: a copilot for your team created with the scope agents:internal.
descriptionstatusversionGoes up on every change. Send it back as expectedVersion.
instructionsAs you wrote them, with the {{name}} placeholders still in place.
maxTokensmaxIterationschannelsavatarcreatedAtupdatedAtActivate an agent
Turns the agent on, so it starts answering real people, and says in readiness what still keeps people from reaching it: no stage, not the entry stage, or no api channel. An empty readiness.missing means it is reachable. Use dryRun=true first: it runs the same checks (422 agent_not_ready when something is missing) and answers with the agent as it would be once active and its readiness, without turning it on.
Required scope: agents:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Activate an agent › Responses
objectidnameaudiencecustomers: talks to your customers. internal: a copilot for your team created with the scope agents:internal.
descriptionstatusversionGoes up on every change. Send it back as expectedVersion.
instructionsAs you wrote them, with the {{name}} placeholders still in place.
maxTokensmaxIterationschannelsavatarcreatedAtupdatedAtdryRunPresent and true when the request had dryRun=true.
Pause an agent
Stops answering. Open conversations stay; it answers again when activated.
Required scope: agents:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Pause an agent › Responses
objectidnameaudiencecustomers: talks to your customers. internal: a copilot for your team created with the scope agents:internal.
descriptionstatusversionGoes up on every change. Send it back as expectedVersion.
instructionsAs you wrote them, with the {{name}} placeholders still in place.
maxTokensmaxIterationschannelsavatarcreatedAtupdatedAtList versions
Newest first, without the text. A version is saved each time the instructions or variables change, and says who made it.
Required scope: agents:read.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List versions › Responses
objecthasMorenextCursorRetrieve a version
Includes the instructions and variables of that version.
Required scope: agents:read.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
versionId^agv_[0-9A-Za-z]{22}… · requiredThe id of the agent version (agv_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Retrieve a version › Responses
objectidagentIdversionThe agent version this one left in place.
charsLength of the instructions.
createdAtinstructionsThe instructions as written, with placeholders in place.
Restore a version
Writes that version's instructions and variables as a new version. History never shrinks.
Required scope: agents:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
versionId^agv_[0-9A-Za-z]{22}… · requiredThe id of the agent version (agv_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Restore a version › Responses
objectidnameaudiencecustomers: talks to your customers. internal: a copilot for your team created with the scope agents:internal.
descriptionstatusversionGoes up on every change. Send it back as expectedVersion.
instructionsAs you wrote them, with the {{name}} placeholders still in place.
maxTokensmaxIterationschannelsavatarcreatedAtupdatedAtList the fixed facts of an agent
The facts the agent keeps in its memory and receives in every conversation: the ones you save here and the ones it saved on its own. Most recently updated first, up to 50 in total. Add q to keep the facts whose key or value contains that text. Facts are not versioned: saving one replaces the previous value. Read only. It is safe to repeat.
Required scope: agents:read.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
qOnly the facts whose key or value contains this text.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List the fixed facts of an agent › Responses
objecthasMorenextCursorSave a fixed fact of an agent
Saves the value under the key. If the agent already has a fact with that key, the value is replaced; otherwise it is added. key is snake_case. It is safe to repeat with the same body: the result does not change.
Required scope: agents:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Save a fixed fact of an agent › Responses
objectkeyvaluesourcemanual when someone wrote it through the API or the dashboard, auto when the agent saved it on its own.
createdAtupdatedAtForget a fixed fact of an agent
The agent stops receiving that fact. Repeating the call returns 404 not_found, because the fact no longer exists, so do not retry a 404 as a failure.
Required scope: agents:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
keyThe key of the fact.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Forget a fixed fact of an agent › Responses
Forgotten.