> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an upload URL for a sandbox file

> A short-lived signed URL the sandbox serves itself. PUT a file of any size to it.



## OpenAPI

````yaml openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/files/upload-url
openapi: 3.1.0
info:
  title: Boat Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    sandboxes from backend services, CI jobs, hosted workers, and Boat
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://boat.dev/api/v1
security:
  - BoatBearerAuth: []
tags:
  - name: Boat
    description: >-
      Unified Boat account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /sandboxes/{sandboxId}/files/upload-url:
    post:
      tags:
        - Boat
      summary: Get an upload URL for a sandbox file
      description: >-
        Returns a short-lived URL that the sandbox serves itself. PUT the file
        as the raw request body to write it, with no size limit and no
        Authorization header. Missing directories are created; an existing file
        is replaced only once the upload completes. The URL is bound to this
        path and expires after `ttlSeconds` (default 15 minutes, at most 1
        hour). Needs `file.write`. Treat the URL as a secret until it expires.
      operationId: createUploadUrl
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUrlRequest'
      responses:
        '200':
          description: Signed upload URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUrlResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
components:
  parameters:
    SandboxId:
      name: sandboxId
      in: path
      required: true
      schema:
        type: string
        pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$
      description: Public Sandbox id returned by create/list/get sandbox calls.
  schemas:
    FileUrlRequest:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          description: >-
            Absolute path, or path relative to the sandbox work directory
            (/home/user). It must resolve under /home/user or /tmp.
        ttlSeconds:
          type: integer
          minimum: 1
          maximum: 3600
          default: 900
          description: How long the URL stays valid.
    FileUrlResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - url
            - method
            - path
            - expiresAt
          properties:
            type:
              type: string
              enum:
                - file.download_url
                - file.upload_url
            url:
              type: string
              format: uri
              description: >-
                The signed URL. Send the request straight to it; it needs no
                Authorization header.
            method:
              type: string
              enum:
                - GET
                - PUT
              description: >-
                GET downloads the file. PUT uploads the request body as the
                file.
            path:
              type: string
              description: The canonical path the URL is bound to.
            expiresAt:
              type: string
              format: date-time
    SuccessBase:
      type: object
      required:
        - ok
        - type
      properties:
        ok:
          type: boolean
          examples:
            - true
        type:
          type: string
          description: Stable success envelope discriminator added by v1.
    ErrorEnvelope:
      type: object
      required:
        - ok
        - type
        - status
        - code
        - message
        - error
        - requestId
      properties:
        ok:
          type: boolean
          examples:
            - false
        type:
          type: string
          examples:
            - sandbox.error
        status:
          type: integer
          examples:
            - 409
        code:
          type: string
          examples:
            - provider_not_configured
        message:
          type: string
          examples:
            - Prompting is locked until Codex is configured on the Agents page.
        requestId:
          type: string
          examples:
            - req_01HX...
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            details:
              type: object
              additionalProperties: true
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            invalid:
              value:
                ok: false
                type: sandbox.error
                status: 400
                code: invalid_json
                message: Request body must be valid JSON.
                error:
                  code: invalid_json
                  message: Request body must be valid JSON.
                  status: 400
                requestId: req_01HX...
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            unauthorized:
              value:
                ok: false
                type: sandbox.error
                status: 401
                code: unauthorized
                message: Unauthorized
                error:
                  code: unauthorized
                  message: Unauthorized
                  status: 401
                requestId: req_01HX...
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Conflict:
      description: Request conflicts with current account or sandbox state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BoatBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sandbox_api_key
      description: >-
        Boat bearer token in the form `boat_...`. Service API keys authenticate
        sandbox operations.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.