Agents
The AI agents a workspace runs — their prompt, model, tools and knowledge.
List agents
Returns the agents available to the workspace, including ones published by the platform. An agent the workspace does not own is listed without its prompt or model settings.
query Parameters
agent_activeagent_audienceagent_descriptionagent_dsagent_idagent_managed_byagent_modelagent_nameagent_tenant_enabledcursor^[A-Za-z0-9_-]+$limitoffsetsort^-?[a-z0-9_]+$Headers
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
List agents › Responses
Success
has_moreWhether more rows exist past this page.
next_cursorPass back as cursor for the next page. Null on the last page.
Create an agent
agent_model is restricted: a workspace may use the platform's own genai- models, and foundation models only where they have been enabled for it.
Knowledge bases may be set at creation: agent_ds names the agent's default set in kebab-case, agent_tenant_ds is this workspace's selection of knowledge-base ids. Either can be changed later through the knowledge-bases endpoint.
Headers
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Create an agent › Request Body
agent_nameagent_descriptionagent_modelagent_top_p^-?[0-9]+(\.[0-9]+)?… · requiredagent_temperature^-?[0-9]+(\.[0-9]+)?… · requiredagent_activeagent_toolsagent_audienceagent_dsagent_tenant_dsCreate an agent › Responses
Created
agent_idagent_nameagent_descriptionagent_iconagent_modelagent_temperatureagent_top_pagent_audienceagent_dsagent_system_promptagent_configagent_toolsagent_connsagent_metadataagent_managed_byagent_activeagent_createdagent_updatedagent_tenant_idagent_tenant_enabledagent_tenant_dsagent_tenant_instructionsagent_tenant_metadataGet an agent
An agent the workspace does not own — one published by the platform — comes back without its prompt or model settings.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get an agent › Responses
Success
agent_idagent_nameagent_descriptionagent_iconagent_modelagent_temperatureagent_top_pagent_audienceagent_dsagent_system_promptagent_configagent_toolsagent_connsagent_metadataagent_managed_byagent_activeagent_createdagent_updatedagent_tenant_idagent_tenant_enabledagent_tenant_dsagent_tenant_instructionsagent_tenant_metadataDelete an agent
Soft delete: the agent stops being listed and stops answering, and is not erased.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Delete an agent › Responses
Success. No content.
Update an agent
Only the fields present in the body change. The same model restriction as create applies.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Update an agent › Request Body optional
agent_nameagent_descriptionagent_modelagent_top_p^-?[0-9]+(\.[0-9]+)?…agent_temperature^-?[0-9]+(\.[0-9]+)?…agent_activeagent_toolsagent_audienceagent_tenant_instructionsUpdate an agent › Responses
Success
agent_idagent_nameagent_descriptionagent_iconagent_modelagent_temperatureagent_top_pagent_audienceagent_dsagent_system_promptagent_configagent_toolsagent_connsagent_metadataagent_managed_byagent_activeagent_createdagent_updatedagent_tenant_idagent_tenant_enabledagent_tenant_dsagent_tenant_instructionsagent_tenant_metadataSet knowledge bases
Two separate things, which is why they are two fields. agent_ds is the agent's own default set, named in kebab-case, and can only be changed on an agent this workspace manages. agent_tenant_ds is this workspace's selection of knowledge-base ids layered on top of that default — send null to drop the override and fall back to the agent's own set.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Set knowledge bases › Responses
Success
agent_idagent_nameagent_descriptionagent_iconagent_modelagent_temperatureagent_top_pagent_audienceagent_dsagent_system_promptagent_configagent_toolsagent_connsagent_metadataagent_managed_byagent_activeagent_createdagent_updatedagent_tenant_idagent_tenant_enabledagent_tenant_dsagent_tenant_instructionsagent_tenant_metadataList agent history
Every recorded change, newest first, each as a per-field {from, to} changeset.
Agents are audited under the workspace that manages them, so for a platform-published agent this returns only the calling workspace's own overrides — its knowledge-base selection and extra instructions — and not the edit history of the underlying agent.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
List agent history › Responses
Success
history_idhistory_timestamphistory_userhistory_opThe kind of change — insert, update or delete.
One entry per field that changed, keyed by column name.
history_refWhat the writer noted about the change rather than the columns: the action that made it, or the reason it was made.
Revert to a version
Puts the agent back to the state a history entry recorded, and audits the restore itself so it can be undone in turn. Only the fields the history view shows are written.
A restore can write less than the version held, and skipped says what it left alone and why: a field whose stored value was last written outside the app has no audited value to restore over, and one the workspace may no longer set — a model it is no longer licensed for, a public audience without the chat-widget module — is refused rather than applied.
For a platform-published agent this restores only the calling workspace's own overrides, the same fields its history returns.
path Parameters
history_ididHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Revert to a version › Responses
Success
restoredColumns written back, by name.
Columns the version carried that were deliberately not written.
Preview the prompt
Returns what the agent would actually be sent: its prompt with the workspace's extra instructions and knowledge-base section appended.
For a platform-published agent the base prompt is withheld — the response is only the parts this workspace contributed.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Preview the prompt › Responses
Success
systemPrompt