> ## Documentation Index > Fetch the complete documentation index at: https://docs.gobare.dev/llms.txt > Use this file to discover all available pages before exploring further. # Objects > What each response and request shape contains Every field a response can carry, and what an object means before you have made a call to see one. **Bold** names are required. ## The session object A cloud computer with an agent on it. Everything else hangs off one. | Field | Type | Description | | ------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `session`. Names the shape, so a value can be identified without knowing which call returned it. | | **`id`** | string | Ours, not yours. Use `metadata` to carry your own identifier. | | `title` | string or null | A label for people. Set it yourself; nothing derives one. | | **`status`** | `idle` · `working` · `requires_action` · `failed` | `idle` accepts input. `working` is running a turn. `requires_action` is waiting on you — see `required_actions`. `failed` is the last turn's outcome, not a dead session. | | **`created_at`** | integer | Unix milliseconds. | | **`updated_at`** | integer | Unix milliseconds. Moves on any change, including the workspace waking. | | `source` | `api` · `console` · `cli` · `null` | Which door created this session. Null on sessions predating the field. | | `created_by_token` | string or null | The id of the access token that created it — never its secret. | | `parent_session_id` | string or null | The session this one was branched from, or `null` when it was created directly. Recorded at creation and never cleared: the source may be edited or deleted afterwards and this still answers "where did this session come from", which is the first question asked when two sessions behave differently. The column has existed since the fork endpoint shipped; only the fork response could see it, so a session read back later had no way to say it was a branch. | | **`agent`** | object | What is running, and how freely. | | **`environment`** | object | The workspace: its state, where the agent works, and the repository bound to it. | | **`preview`** | object | Addresses for whatever the agent is serving. See preview\.md. | | `required_actions` | RequiredAction\[] | Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer. | ## The turn object One piece of work, from the message that started it to the moment it settles. | Field | Type | Description | | ------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `turn`. Names the shape, so a value can be identified without knowing which call returned it. | | **`id`** | string | Ours. Quote it when reporting a problem with this turn. | | **`session_id`** | string | The session this turn belongs to. | | **`status`** | `working` · `completed` · `failed` · `cancelled` | `working` covers everything before it settles, including a turn parked on a tool result from you — watch the session's `requires_action` for that, not this field. `completed`, `failed` and `cancelled` are settled; a settled turn never moves again. | | **`created_at`** | integer | Unix milliseconds, when the input was accepted. | | `started_at` | integer or null | When the agent began. Null until it does — a turn is `working` from the moment it is accepted, including while it waits behind another one, so this is the only field that tells the two apart. `queued` was removed from `status`; this description still named it. | | `completed_at` | integer or null | When it settled. Null until it has. | | `artifacts` | `pending` · `ready` · `partial` · `failed` · `null` | Whether this turn's artifacts can be fetched yet. Publication runs after the turn settles, so an empty artifact list under `pending` means not yet, and under `ready` means the turn produced nothing. `partial` means publishing finished and left something behind — read `artifacts_skipped` for what and why. | | `artifacts_skipped` | object\[] | Files publishing did not take, and why. Empty unless `artifacts` is `partial`. A file past the per-file ceiling, or one that did not fit in what the turn had left, is reported here rather than disappearing. | | `subagent_id` | string or null | Always null today; reserved for delegation. | | `error` | object or null | Why it failed, when it did. Null otherwise. | ## The item object One thing that happened inside a turn — a message, a tool call, a file change. | Field | Type | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `item`. Names the shape, so a value can be identified without knowing which call returned it. | | **`id`** | string | Ours. Stable; use it as a paging cursor. | | **`session_id`** | string | The session this item belongs to. | | **`type`** | `message` · `tool_call` · `command_execution` · `file_change` · `approval` · `question` · `mcp_unavailable` · `error` · `context` | What kind of thing happened. Decides which of `content` and `detail` carries the substance. `error` says a run could not start or could not continue, and `detail.message` says why. | | **`created_at`** | integer | Unix milliseconds. | | `role` | `user` · `assistant` | On `message` items only: who said it. | | `content` | string | The text of a `message`. Empty on other kinds. | | `detail` | object | Everything kind-specific: the command run, the path changed, the arguments passed. `examples` carries a real one per item type. `detail.event` is the *event* name — items and events share one vocabulary, and that field is the join between them. It is also how the two halves of `tool_call` are told apart: a call and its result are both `type: "tool_call"`, and only `detail.event` says which. There is no `tool_result` item type; code written from the enum alone renders every tool call twice. | ## The required action object Something the session is waiting on you for. | Field | Type | Description | | ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`type`** | `function_call` · `approval` · `question` | What is being asked of you. `function_call` you answer through the API; `approval` and `question` are answered by a person in the Console. | | **`turn_id`** | string | Copy this back when answering. | | **`call_id`** | string | Copy this back when answering. It identifies which call the result is for. | | `name` | string or null | The function the agent wants to call, as you declared it. | | `arguments` | object | What it wants to call the function with. Shaped by your own parameter schema. | | `created_at` | integer | Unix milliseconds, when the agent asked. | | `expires_at` | integer or null | Unix milliseconds, when this stops being waited for — set from the tool's own `timeout_seconds`. Null, the default, means it waits indefinitely. Past this the call is answered as failed and the turn continues; the turn itself does not fail. | ## The artifact object A file a turn published. Outlives the workspace that made it. | Field | Type | Description | | ---------------- | ------- | -------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `artifact`. Names the shape, so a value can be identified without knowing which call returned it. | | **`id`** | string | Ours. Use it to fetch the bytes. | | **`session_id`** | string | The session that produced it. | | **`turn_id`** | string | The turn that published it. | | **`path`** | string | Where it was in the workspace when it was published. | | **`size_bytes`** | integer | Of the stored copy. | | `content_type` | string | Guessed from the path. `application/octet-stream` when unrecognised. | | `created_at` | integer | Unix milliseconds, when it was published. | ## The agent object A reusable definition to start sessions from. | Field | Type | Description | | --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `agent`. Names the shape, so a value can be identified without knowing which call returned it. | | **`id`** | string | Ours. Pass it as `agent.id` when creating a session. | | **`name`** | string | Yours, for recognising it. Not an identifier. | | `model` | string or null | The model sessions from this agent run on, unless they override it. | | `model_credential_id` | string or null | The connection to run on. Null uses the organization's default. | | `instructions` | string or null | Standing instructions given to every session started from this agent. | | `tools` | Tool\[] | Tools every session started from this agent gets, unless it replaces them. Secrets are withheld — see `redacted` on an entry. | | `text` | object or null | Output shaping copied into every session started from this agent. | | `created_at` | integer | Unix milliseconds. | ## The model credential object A model connection this organization owns. | Field | Type | Description | | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `model_credential`. Names the shape, so a value can be identified without knowing which call returned it. | | **`id`** | string | Pass as agent.model\_credential\_id. | | `label` | string | Yours, from the Console. For recognising the connection. | | `connector` | string | Which provider integration it uses. | | **`model`** | string | agent.model must match this. | | `is_default` | boolean | Whether a session that names no credential gets this one. | | `last4` | string | The last four characters of the key. On create only; the key itself is never returned. | | `verified` | boolean | Whether the provider accepted a probe before this was stored. | ## The preview object A published address, and the port behind it. | Field | Type | Description | | ------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `preview`. Names the shape, so a value can be identified without knowing which call returned it. | | **`subdomain`** | string | The label the site is served under. | | **`url`** | string | The public address. A Gobare origin, never the sandbox provider's. | | **`published_url`** | string | The same address, under the name the session object uses for it. A session carries two — `preview.url` needs a token, `preview.published_url` does not — and this call returned only `url`, so nothing in the shape said which one you were holding. It is the public one; this field says so rather than leaving you to bet on it. | | **`port`** | integer or null | The workspace port being served. | ## The webhook subscription object Where deliveries go, and for which events. The secret appears once, on creation. | Field | Type | Description | | ------------ | --------- | -------------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `webhook.subscription`. Names the shape, so a value can be identified without knowing which call returned it. | | **`id`** | string | Ours. Use it to delete the subscription. | | **`url`** | string | Where deliveries go. Must be https. | | **`events`** | string\[] | Which events to deliver. An empty list means all of them. | | `active` | boolean | False once deliveries have been given up on. See webhooks.md on retries and dead letters. | | **`secret`** | string | Recompute x-gobare-signature as HMAC-SHA256 over `.`. | ## The event object One frame of the session's event stream. | Field | Type | Description | | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`object`** | string | Always `event`. Names the shape, so a value can be identified without knowing which call returned it. | | **`type`** | string | The event's name. See events.md for the vocabulary. | | `internal_type` | string | The control plane's own name for the event, for cross-referencing logs. | | **`session_id`** | string | The session it happened in. | | `seq` | integer or null | Cursor for Last-Event-ID. Null on a transient event, which does not advance it. | | **`created_at`** | integer | Unix milliseconds. | | `payload` | object | Everything specific to this event type. Not one shape — `examples` below carries a real payload for every type in the vocabulary, keyed by the type. Read the one you are handling rather than probing for fields: `agent.tool_call` carries `toolName` and `args`, not `name` and `arguments`, and guessing that pair wrong renders every tool call as an empty object. | ## The tool configuration object The functions and MCP servers a session may use. | Field | Type | Description | | ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`object`** | string | Always `session.tools`. Names the shape, so a value can be identified without knowing which call returned it. | | **`session_id`** | string | The session this configuration applies to. | | `tools` | Tool\[] | The configuration as sent, in the same vocabulary: one entry per tool, each with a `type` of `mcp` or `function`. Secret values are withheld — see `redacted`. | | `text` | object or null | Output shaping, or null when none was set. Asked of the model, not enforced. | ## The error object Every refusal, in one shape. | Field | Type | Description | | ----------- | ------ | -------------------------------------------------------- | | **`error`** | object | Always present on a failure, and the only thing present. |