> ## 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.

# Write workspace files

> Write files into a running session's workspace.



## OpenAPI

````yaml /openapi.json post /v1/sessions/{session_id}/files
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/{session_id}/files:
    post:
      summary: Write workspace files
      description: Write files into a running session's workspace.
      operationId: post_sessions_session_id_files
      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/FilesRequest'
      responses:
        '200':
          description: Write files into a running session's workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceFileList'
        '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 no such object under this token's organization.
            Another organization's id is indistinguishable from one that never
            existed, deliberately.
          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:
    FilesRequest:
      type: object
      example:
        files:
          - type: inline
            path: data/input.csv
            data: aWQsbmFtZQoxLGFjbWU=
      required:
        - files
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/SeedFile'
          description: >-
            Files to write into the running workspace. Same shape as
            `environment.files`, which seeds one before the first turn.
    WorkspaceFileList:
      type: object
      required:
        - object
        - data
      description: >-
        What was written into the workspace. A path that was already there has
        been overwritten — that is what the request asked for.
      properties:
        object:
          type: string
          const: list
          description: >-
            Always `list`. Names the shape, so a value can be identified without
            knowing which call returned it.
        data:
          type: array
          items:
            type: object
            required:
              - object
              - path
              - size_bytes
            properties:
              object:
                type: string
                const: workspace_file
                description: >-
                  Always `workspace_file`. Names the shape, so a value can be
                  identified without knowing which call returned it.
              path:
                type: string
              size_bytes:
                type: integer
    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.
    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.
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      description: >-
        A `gbr_pat_` access token. Scopes are recorded on the token when it is
        minted.

````