Input

Everything you can send a session, in one place. They all go to the same endpoint, one per request:

POST /v1/sessions/{session_id}/events

The body is always an array of exactly one event. Batching two would need a partial-failure result nothing could act on, so it is refused rather than half-supported.

{ "events": [ { "type": "input.message", "content": "…" } ] }

A success is 202, not 200 — the agent has the work, not the answer.

Type	What it does	When it is refused
`input.message`	Say something. Starts a turn, or queues behind the running one	`queue_full` at five queued
`input.context`	Tell it something without asking it to answer. No turn runs	`invalid_request` on empty text
`input.tool_result`	Answer a function the agent called	`not_found` if no such call is pending
`input.approval`	Allow or refuse something the agent asked to do	`invalid_request` without `call_id` and a boolean `approved`
`input.question_answer`	Answer a question the agent asked	`invalid_request` without `call_id` and a non-empty `answer`
`input.steer`	Change course mid-turn	`conflict` when no turn is running
`input.cancel`	Stop the running turn	Accepted even when nothing is running

Every refusal arrives in the shape described in errors.md, with the code above in error.code.

`input.message`

curl -s -X POST $GOBARE_API/v1/sessions/$SESSION/events \
  -H "Authorization: Bearer $GOBARE_TOKEN" \
  -H 'content-type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"events":[{"type":"input.message","content":"Summarise this repo."}]}'

content takes a string, or an array of parts if you prefer the longer form:

{ "type": "input.message", "content": [ { "type": "input_text", "text": "Summarise this repo." } ] }

Sent while a turn is running, it queues rather than interrupting — see design-decisions.md for why that is not steering. The reply tells you which happened:

{ "object": "input.accepted", "type": "input.message", "queued": true, "queue_position": 1 }

Send an Idempotency-Key. A retried send without one is a second message.

Finding the turn your message produced

The reply carries no turn_id, because at the moment it is written there is no turn yet — the agent starts one when it picks the message up, which is later even when nothing was queued. If you watch events or take a webhook, the turn id arrives with them and there is nothing to do. If you poll, there is one trap worth knowing:

# Wrong: on a session that has run before, this returns the PREVIOUS turn —
# which is already `completed`, so the wait ends immediately and you read the
# results of work you did not ask for.
curl -s "$GOBARE_API/v1/sessions/$SESSION/turns?limit=1"

Remember the latest turn id before you send, and wait for one that is different:

BEFORE=$(curl -s "$GOBARE_API/v1/sessions/$SESSION/turns?limit=1" \
  -H "Authorization: Bearer $GOBARE_TOKEN" | jq -r '.data[0].id // ""')
# … send …
until [ "$(curl -s "$GOBARE_API/v1/sessions/$SESSION/turns?limit=1" \
  -H "Authorization: Bearer $GOBARE_TOKEN" | jq -r '.data[0].id')" != "$BEFORE" ]; do sleep 1; done

A fresh session has no previous turn, so a first message needs none of this.

`input.context`

Something the session should know, without being asked to reply. It lands in the transcript and no turn runs.

curl -s -X POST $GOBARE_API/v1/sessions/$SESSION/events \
  -H "Authorization: Bearer $GOBARE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"events":[{"type":"input.context","content":"@reviewer said: the rollback is already merged."}]}'

Field
`content`	required	A string, or an array of `{type,text}` parts

The reply carries delivered:

true — a running agent took it there and then
false — the sandbox was not up

false does not mean it was lost. The text is in the transcript either way, and the next turn is built with it — so a room can hand an agent context before that agent has ever spoken, which is the usual case when someone joins a conversation already in progress. It appears afterwards as an item of type context, and on the stream as user.context. Deliberately not a message: nobody said it to this session, and rendering it as one would show the agent a conversation that never happened. If a turn is already running, the context lands after it finishes. That turn’s context is fixed, and inserting into it would make one turn’s behaviour depend on when a message happened to arrive. Without this, keeping several agents current means holding your own copy of the conversation and resending it — which makes every prompt grow with the length of the room. See agents that work together.

`input.tool_result`

The answer to a function the agent called. turn_id and call_id are copied from the required action verbatim.

curl -s -X POST $GOBARE_API/v1/sessions/$SESSION/events \
  -H "Authorization: Bearer $GOBARE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"events":[{"type":"input.tool_result","turn_id":"'$TURN'","call_id":"'$CALL'",
       "success":true,"output":"{\"status\":\"shipped\"}"}]}'

Field
`turn_id`	required	From the required action
`call_id`	required	From the required action
`success`	required	Whether your function worked
`output`	when `success` is true	A string. Serialise JSON yourself
`error`	when `success` is false	A string the model will read

The reply’s outcome is the thing to check:

accepted — the turn has it and continues
already_resolved — this call was answered before; the second answer is discarded rather than applied
not_delivered — nothing was waiting for it

Never put a thrown exception’s message in error. It goes to the model, and a stack trace is an efficient way to put your database host into a prompt. Send a fixed string; log the real one.

`input.steer`

Change course while a turn is running.

curl -s -X POST $GOBARE_API/v1/sessions/$SESSION/events \
  -H "Authorization: Bearer $GOBARE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"events":[{"type":"input.steer","content":"Stop — use Go instead."}]}'

This is the deliberate half of the divergence: a plain message waits its turn, and redirecting work in flight has to be asked for by name. Sent when no turn is running, it is a conflict — there is nothing to steer, and silently turning it into a message would be a different thing than you asked for.

`input.cancel`

Stop the running turn.

curl -s -X POST $GOBARE_API/v1/sessions/$SESSION/events \
  -H "Authorization: Bearer $GOBARE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"events":[{"type":"input.cancel"}]}'

No other fields. The turn settles as cancelled — not failed, because you asked for it, and a failure status would send you looking for a fault that is not there. Cancelling when nothing is running is accepted rather than refused: a caller racing a finishing turn should not have to care which of them won. Work already done stays. Items the turn produced remain readable, and anything published to /workspace/outputs before the stop is still collected.

required-actions.md — the calls you answer with input.tool_result
events.md — watching what the agent does with what you sent
idempotency.md — retrying a send without sending twice

Start here

Running a session

Guides

Integrations

Client libraries

When things go wrong

API reference

About this API

Endpoints

`input.message`

Finding the turn your message produced

`input.context`

`input.tool_result`

`input.steer`

`input.cancel`

Next

​input.message

​Finding the turn your message produced

​input.context

​input.tool_result

​input.steer

​input.cancel

​Next

`input.message`

Finding the turn your message produced

`input.context`

`input.tool_result`

`input.steer`

`input.cancel`

Next