Skip to main content
POST
Refine a composed agent
Change the agent a composer session is holding, by saying what you want changed.
The response is the same shape the session started with: the updated agent preview, and a message saying what changed.
Still no agent. Refining changes the preview the session is holding. Nothing exists in your account until you post to POST /agents.

You do not send the agent back

The session holds the agent, so a follow-up carries only your instruction. There is nothing to keep in sync on your side, and no way to accidentally send back a stale version of the conversation. You can refine as many times as you like within the session’s 30 days.

What a message can do

Anything the visual builder can do to a custom agent — the composer and the in-app copilot are the same thing behind different doors:
Renaming is only ever on request. If you pinned a name when you started the session, it stays pinned — the composer will not quietly relabel your agent while doing something else.

A rejected change stores nothing

Every turn is validated the same way the create route validates a flow. If a change would break the conversation — emptying a required message, leaving a conditional with one branch — the turn is rejected with a 422 and the session is untouched: no half-applied edit, and no record of a message that did not land. Send a different instruction and carry on. This is also what keeps the promise that the preview is postable: the agent a session hands you has passed the create route’s checks at every step, not just at the start.

Errors

An unknown session, an expired one, and one belonging to another company are all a 404. They are deliberately indistinguishable.
A refinement takes a few seconds — it is a language-model call. Allow up to a minute on your client. Asking for one thing at a time is faster than a compound instruction, and much easier to review afterwards.

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

sessionId
string<uuid>
required

The composer session id returned by POST /agents/composer.

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
message
string
required

What to change, in plain language.

Maximum string length: 4000
Example:

"Also ask about relocation, and make the whole call Slovak."

Response

The updated preview and the composer's reply.

sessionId
string<uuid>
required

The session to send follow-up messages to, and to create the agent from.

agent
object
required

The agent the composer would build. There is no id: this agent does not exist yet. Post this object to POST /agents to create it — it is accepted verbatim, with no ids or schemaVersion to strip first.

message
object
required
expiresAt
string<date-time>
required

When this session is deleted if you never create the agent. Sessions live 30 days.