Message the agent

Say something to the agent: approve or amend a plan, answer its questions, redirect it. Only the person who started the session may (an engineer may on a bot session), and the session’s owner must have usage left in their window. A finished session is not refused a message — it is revived by one, around a fresh pull request where the last one merged. Returns once the agent has taken the message; its reply streams into the transcript, so read it back after a moment. A 409 says the agent is still starting, or has been cleaned up upstream and the session archived with it.

Required scope

The access token must carry this scope. A token missing it gets 403 Forbidden. Grant them to an API client under Dev Tools → API, to an assistant or CLI sign-in when you approve or edit it under Dev Tools, and to a teammate under Employee → Permissions.

builder:write

Path Parameters

Name	Type	Required	Description
`sessionId`	string	Required	Build session ID.

Request Body

Property	Type	Required	Description
`content`	string	Required	The message, up to 8000 characters. May be empty when sending attachments only.
`attachments`	array	Optional	Files to send with it, up to ten: `{ kind: "IMAGE" \| "FILE", url, filename?, mimeType?, sizeBytes? }`.

POSTExample request

curl

curl -X POST "https://www.pxb.app/api/public/v1/build-sessions/{sessionId}/messages" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Approved — go ahead with the plan, but keep the console payload unchanged."
  }'

200Example response

json

{
  "message": "Message sent successfully!",
  "content": {
    "buildSessionId": "bse_a1b2c3"
  }
}

In the console

The same thing done by hand, for anyone comparing the API against the screen they already use.

Builder

/builder

Open a session.
Write in the composer.