Refine a Composed Agent
Applies one plain-language change to the session’s agent — “also ask about relocation”, “make it Slovak”, “drop the salary question” — and returns the updated preview. Still creates nothing.
agent preview, and a message saying what changed.
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: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 a422 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
404.
They are deliberately indistinguishable.Authorizations
API key for authentication using Bearer scheme
Path Parameters
The composer session id returned by POST /agents/composer.
Query Parameters
Required for ATS API keys to specify which company to access. Ignored for standard company API keys.
Body
What to change, in plain language.
4000"Also ask about relocation, and make the whole call Slovak."
Response
The updated preview and the composer's reply.
The session to send follow-up messages to, and to create the agent from.
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.
When this session is deleted if you never create the agent. Sessions live 30 days.