> ## 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. # Create a session > Create a session, optionally with an opening message. ## OpenAPI ````yaml /openapi.json post /v1/sessions openapi: 3.1.0 info: title: Gobare Agent API version: v1 description: >- Programmatic access to Gobare coding-agent sessions. Conceptually aligned with OpenAI's Agents API; deliberately not wire-compatible with it. See the divergence list in the product documentation. servers: - url: https://api.{domain} variables: domain: default: gobare.dev security: [] paths: /v1/sessions: post: summary: Create a session description: Create a session, optionally with an opening message. operationId: post_sessions parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Retrying with the same key replays the first answer instead of acting again. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionCreateRequest' responses: '201': description: Create a session, optionally with an opening message. content: application/json: schema: $ref: '#/components/schemas/Session' '400': description: >- `invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: The access token is missing, unrecognised, expired or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- The token is valid but may not perform this call. The message names the scope it wanted. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No such endpoint, or the public API is not enabled on this deployment. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- `rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: An unexpected error. Quote the request id. content: application/json: schema: $ref: '#/components/schemas/Error' security: - accessToken: [] components: schemas: SessionCreateRequest: type: object example: agent: model: MiniMax-M3 input: Write /workspace/outputs/report.md about this repo. description: Everything optional. A session with only a model is a complete session. properties: agent: $ref: '#/components/schemas/AgentConfig' description: >- What runs, and how freely. Omit every field and the organization's default connection runs it. environment: type: object description: What the workspace starts with. properties: template_id: type: string description: Deprecated name for an agent id. profiles: type: array items: type: string description: >- Environment-variable group ids. GET /v1/environment-profiles lists them. repo: type: string description: >- `owner/name`. A URL is refused; the branch is reported by the clone, not chosen. files: type: array description: Files to place in the workspace before the first turn. items: $ref: '#/components/schemas/SeedFile' metadata: type: object additionalProperties: type: string description: Your own labels. Returned unchanged; never interpreted. input: type: string description: >- An opening message. All or nothing — if it cannot be accepted the session is not created either. title: type: string description: A label for people. Session: type: object required: - object - id - status - created_at - updated_at - agent - environment - preview properties: object: type: string const: session description: >- Always `session`. Names the shape, so a value can be identified without knowing which call returned it. id: type: string description: Ours, not yours. Use `metadata` to carry your own identifier. title: type: - string - 'null' description: A label for people. Set it yourself; nothing derives one. status: type: string enum: - idle - working - requires_action - failed description: >- `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: type: integer description: Unix milliseconds. updated_at: type: integer description: >- Unix milliseconds. Moves on any change, including the workspace waking. source: type: - string - 'null' enum: - api - console - cli - null description: >- Which door created this session. Null on sessions predating the field. created_by_token: type: - string - 'null' description: The id of the access token that created it — never its secret. agent: type: object description: What is running, and how freely. properties: id: type: - string - 'null' description: >- The agent template this session was created from, or null when it was configured inline. Still here after that template is deleted — it is history, not a live reference, which is what makes it usable for answering "where did this session's settings come from" long after the fact. The response has carried it since the field existed; it was simply never described here. model: type: - string - 'null' description: The model this session is bound to. Fixed at creation. model_credential_id: type: - string - 'null' description: >- The connection it runs on. `GET /v1/model-credentials` lists them. approval_mode: type: - string - 'null' description: How much the agent may do without asking. instructions: type: - string - 'null' maxLength: 32000 permission_rules: type: array items: type: object tools: type: array items: type: object description: >- What this session can call, as you configured it, with any secrets removed. On the single-session read only — a page of sessions does not carry it. environment: type: object description: >- The workspace: its state, where the agent works, and the repository bound to it. properties: type: type: string const: sandbox state: type: string enum: - unknown - running - paused - destroyed - recovering - recovery_failed description: >- Where the workspace is. `unknown` until it first reports — a session is created before its sandbox exists, so this is what you see immediately after POST /v1/sessions. `running` is usable; `paused` is idle and woken by the next thing you send; `destroyed` is reclaimed and will be rebuilt on demand; `recovering` and `recovery_failed` are a rebuild in progress and one that gave up. A value outside this set is reported as null rather than passed through. workspace_directory: type: string repo: type: - object - 'null' description: >- The repository bound to this session, once one is. Null when none was asked for. properties: full_name: type: string description: owner/name, as given. branch: type: - string - 'null' description: >- Reported by the clone, not chosen. Null until the workspace comes up. clone_error: type: - string - 'null' description: Why the clone did not happen, when it did not. preview: type: object description: Addresses for whatever the agent is serving. See preview.md. properties: url: type: - string - 'null' port: type: - integer - 'null' published_url: type: - string - 'null' required_actions: type: array description: >- Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer. items: $ref: '#/components/schemas/RequiredAction' Error: type: object required: - error description: Every refusal this API makes, in one shape. properties: error: description: Always present on a failure, and the only thing present. type: object required: - code - message - request_id properties: code: type: string enum: - invalid_request - authentication_error - permission_denied - not_found - method_not_allowed - conflict - queue_full - rate_limit_exceeded - project_limit_exceeded - context_length_exceeded - provider_error - provider_unauthorized - sandbox_error - sandbox_unavailable - directory_unavailable - workspace_recovery_failed - bridge_incompatible - internal_error message: type: string request_id: type: string description: >- Also on the x-request-id header. Quote it when reporting a problem. AgentConfig: type: object description: What runs, and how freely. properties: id: type: string description: An agent to inherit from. Per-field overrides still apply. model: type: string description: Must be one the chosen credential runs. model_credential_id: type: string description: Omit to use the organization's default. instructions: type: - string - 'null' maxLength: 32000 description: >- Standing instructions for every turn. `null` clears an inherited one. approval_mode: type: string enum: - auto - per_step - read_only - plan description: How much the agent may do without asking. permission_rules: type: array items: type: object description: Path rules evaluated before a write. tools: type: array items: $ref: '#/components/schemas/ToolRequest' description: >- 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: $ref: '#/components/schemas/TextConfig' description: >- Shaping the final message: how much it says, and whether it must conform to a JSON Schema. SeedFile: type: object description: >- One file, inline. There is no Files API to reference and we do not fetch URLs on your behalf; for a large input use `environment.repo`. required: - path - data properties: type: type: string const: inline description: >- Optional, and `inline` is the only value. Named rather than defaulted: a caller sending `file_id` has a file we cannot reach, and treating it as inline would hand them an empty workspace with no reason why. path: type: string description: >- Where in the workspace to write it. Confined to the workspace directory. data: type: string description: >- The file's bytes, base64. Always base64, including for text — one encoding to get right rather than two. RequiredAction: type: object required: - type - turn_id - call_id description: >- Something this session is waiting for. Copy turn_id and call_id into the result you submit. properties: type: type: string enum: - function_call - approval - question description: >- 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: type: string description: Copy this back when answering. call_id: type: string description: >- Copy this back when answering. It identifies which call the result is for. name: type: - string - 'null' description: The function the agent wants to call, as you declared it. arguments: description: >- What it wants to call the function with. Shaped by your own parameter schema. created_at: type: integer description: Unix milliseconds, when the agent asked. expires_at: type: - integer - 'null' description: >- 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. ToolRequest: type: object description: >- One tool. `type` decides which shape applies; the fields of another are refused rather than ignored. `function` and `mcp` need a `name`; the sandbox's own networked tools are named by their `type` alone and take no other field. Naming any of the latter narrows the session to exactly the ones listed — it cannot enable one this deployment has turned off, and an empty list is a session with no way out to the network. required: - type properties: type: type: string enum: - function - mcp - web_search - web_fetch - image_search - browse - browser_act - screenshot name: type: string description: >- `function` and `mcp` only, and required for both. What the agent calls it. description: type: string description: '`function` only. Read by the model to decide when to call it.' parameters: type: object description: '`function` only. JSON Schema for the arguments.' timeout_seconds: type: integer description: '`function` only. How long a required action may stay unanswered.' url: type: string description: '`mcp` only. http or https endpoint of the server.' command: type: string description: >- `mcp` only. A server started inside the workspace instead of reached over the network. args: type: array items: type: string description: '`mcp` only. Arguments for `command`.' allowed_tools: type: array items: type: string description: '`mcp` only. Narrow the server to these tool names.' required: type: boolean description: >- `mcp` only. `true` fails the session loudly when the server will not connect; `false` lets the turn continue with fewer tools and an `mcp.unavailable` event. Must be a boolean — a string is refused rather than read as false. authorization: type: string description: >- `mcp` only. Sent to the server, never returned; a read-back names it under `redacted`. headers: type: object additionalProperties: type: string description: '`mcp` only. Also withheld from a read-back.' TextConfig: type: object description: Shaping the final message. properties: verbosity: type: string enum: - low - medium - high description: How much the agent says when it is done. format: type: object description: Asked for, not enforced — see design-decisions. properties: type: type: string const: json_schema schema: type: object description: JSON Schema the final message should conform to. securitySchemes: accessToken: type: http scheme: bearer description: >- A `gbr_pat_` access token. Scopes are recorded on the token when it is minted. ````