Start a build session

Hand a brief to the agent. Returns as soon as the session row exists; the agent starts in the background and its first turn — questions, or a plan to approve — lands in the transcript a few seconds later, so read the session back rather than waiting on this call. A session started from a ticket needs the caller to be the ticket’s assignee or a manager of its project, the ticket to be refined and still open, and the project to be the one Builder works; a session with no ticket behind it is an engineer’s to start. Refused with a 409 when the caller is at their active-session cap or has spent their usage window. The model is pinned for the session’s life.

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

Request Body

Property	Type	Required	Description
`description`	string	Required	The brief — what to build. Its first line becomes the session’s title.
`ticketId`	string	Optional	The ticket this builds. Required for everyone but an engineer; the ticket then shows the session and reopens it rather than starting a second one.
`model`	string	Optional	Which Claude runs it. Defaults to Sonnet.
`ticketAttachmentIds`	array	Optional	Ids of files already on the ticket to send with the brief, up to ten. Ignored without a `ticketId`.
`attachments`	array	Optional	Files to send with the brief, up to ten: `{ kind: "IMAGE" \| "FILE", url, filename?, mimeType?, sizeBytes? }`. The URL must be reachable by the agent.

POSTExample request

curl

curl -X POST "https://www.pxb.app/api/public/v1/build-sessions" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Expose builder session status over MCP: list, status, messages and the write actions.",
    "ticketId": "tkt_214",
    "model": "claude-sonnet-5-5"
  }'

200Example response

json

{
  "message": "Build session created 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 ticket.
Build this.
Or: Builder → New session.