Skip to main content
POST
Create or replace an agent

Authorizations

Authorization
string
header
required

A gbr_pat_ access token. Scopes are recorded on the token when it is minted.

Headers

Idempotency-Key
string

Retrying with the same key replays the first answer instead of acting again.

Maximum string length: 255

Body

application/json
name
string
required

Yours, for recognising it.

model
string

Must be one the chosen credential runs. A session started from this agent may override it.

model_credential_id
string

Omit to use the organization's default.

instructions
string

Standing instructions every session started from this agent begins with.

Maximum string length: 32000
tools
object[]

What the agent may reach outside the workspace: your own functions, MCP servers, and which built-ins. Everything inside the workspace — shell, files, git — is always there and is not configured here.

text
object

Shaping the final message: how much it says, and whether it must conform to a JSON Schema.

Response

Create or replace a named agent.

object
string
required

Always agent. Names the shape, so a value can be identified without knowing which call returned it.

Allowed value: "agent"
id
string
required

Ours. Pass it as agent.id when creating a session.

name
string
required

Yours, for recognising it. Not an identifier.

model
string | null

The model sessions from this agent run on, unless they override it.

model_credential_id
string | null

The connection to run on. Null uses the organization's default.

instructions
string | null

Standing instructions given to every session started from this agent.

Maximum string length: 32000
tools
object[]

Tools every session started from this agent gets, unless it replaces them. Secrets are withheld — see redacted on an entry.

text
object | null

Output shaping copied into every session started from this agent.

created_at
integer

Unix milliseconds.