> ## 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 or replace an agent > Create or replace a named agent. ## OpenAPI ````yaml /openapi.json post /v1/agents 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/agents: post: summary: Create or replace an agent description: Create or replace a named agent. operationId: post_agents 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/AgentCreateRequest' responses: '201': description: Create or replace a named agent. content: application/json: schema: $ref: '#/components/schemas/Agent' '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: AgentCreateRequest: type: object example: name: reviewer model: MiniMax-M3 instructions: Review diffs. Never modify files. required: - name properties: name: type: string description: Yours, for recognising it. model: type: string description: >- Must be one the chosen credential runs. A session started from this agent may override it. model_credential_id: type: string description: Omit to use the organization's default. instructions: type: string maxLength: 32000 description: >- Standing instructions every session started from this agent begins with. 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. Agent: type: object required: - object - id - name properties: object: type: string const: agent description: >- Always `agent`. Names the shape, so a value can be identified without knowing which call returned it. id: type: string description: Ours. Pass it as `agent.id` when creating a session. name: type: string description: Yours, for recognising it. Not an identifier. model: type: - string - 'null' description: The model sessions from this agent run on, unless they override it. model_credential_id: type: - string - 'null' description: The connection to run on. Null uses the organization's default. instructions: type: - string - 'null' maxLength: 32000 description: >- Standing instructions given to every session started from this agent. tools: type: array items: $ref: '#/components/schemas/Tool' description: >- Tools every session started from this agent gets, unless it replaces them. Secrets are withheld — see `redacted` on an entry. text: type: - object - 'null' description: Output shaping copied into every session started from this agent. created_at: type: integer description: Unix milliseconds. 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. 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. Tool: type: object required: - type - name properties: type: type: string enum: - mcp - function name: type: string description: 'Unique across both types: the agent sees one list.' url: type: string description: 'mcp: the server''s address. Exclusive with `command`.' command: type: string description: 'mcp: a command run inside the sandbox. Exclusive with `url`.' args: type: array items: type: string description: 'mcp: arguments for `command`.' allowed_tools: type: array items: type: string description: >- mcp: restrict the agent to these tools from this server. Absent means all of them. required: type: boolean description: >- mcp: the session fails if this server will not connect. Absent means optional, which produces an `mcp.unavailable` event instead. redacted: type: array items: type: string description: >- Names of the secret values withheld from this response, such as `authorization` or `headers.x-api-key`. Not a request field: sending it back is refused, so an edited read-back cannot silently drop your credentials. description: type: string description: 'function: what the function is for. The model reads it.' parameters: type: object description: 'function: a JSON Schema for the arguments. Carried unexamined.' timeout_seconds: type: integer description: 'function: how long to wait for your process to answer this call.' securitySchemes: accessToken: type: http scheme: bearer description: >- A `gbr_pat_` access token. Scopes are recorded on the token when it is minted. ````