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

# Upload a file to the workspace root



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/workspaces/{id}/upload
openapi: 3.1.0
info:
  title: RunTools API
  version: 1.0.0
  description: |
    The RunTools platform API for cloud sandboxes, agents, workspaces, tools,
    threads, billing, and credentials. This document covers the customer-facing
    surface across six services:

      - api.runtools.ai        — orchestrator (control plane)
      - auth.runtools.ai       — auth service (API keys, SSH keys, OAuth, secrets)
      - tools.runtools.ai      — tool marketplace + execution
      - billing.runtools.ai    — credits, top-up, auto-top-up
      - storage.runtools.ai    — workspace file APIs

    Internal-only routes (`/internal/*`, admin routes, webhooks), as well as
    deferred/gated surfaces (workflows, snapshots, rollback, code-exec), are
    deliberately excluded.

    ## Authentication

    Two auth schemes are supported on the public surface:

      - **WorkOS session token** — Bearer token from interactive login, used by
        dashboard, mobile, CLI `login`, Mac app, and any browser-driven flow.
      - **API key** — `rt_live_*` or `rt_test_*` keys created via
        `POST /v1/api-keys`. Scope-checked at each handler.

    Either may be passed in `Authorization: Bearer <token>` or, for API keys, in
    `X-API-Key`.

    ## Response envelope

    Most successful JSON responses wrap data in `{ "data": ... }`. Paginated
    responses additionally carry `hasMore` and `nextCursor`. Error responses use
    `{ "error": { "code": "...", "message": "..." } }`.

    ## Versioning header

    Every public response includes an `X-API-Version: v1` header. This is the
    contract for clients that want to assert the surface version they were
    written against. A future `/v2/*` rollout will set `X-API-Version: v2` on
    matching responses while `/v1/*` continues to return `v1`.
  contact:
    name: RunTools
    url: https://runtools.ai
  license:
    name: Proprietary
servers:
  - url: https://api.runtools.ai
    description: Orchestrator (control plane)
  - url: https://auth.runtools.ai
    description: Auth service
  - url: https://tools.runtools.ai
    description: Tools service
  - url: https://billing.runtools.ai
    description: Billing service
  - url: https://storage.runtools.ai
    description: Storage service (workspace files)
security:
  - bearer: []
  - apiKey: []
tags:
  - name: Health
    description: Liveness and readiness probes.
  - name: Profile
    description: Current user profile.
  - name: Organizations
    description: Organization CRUD, members, tool-install policy.
  - name: Projects
    description: Org-scoped projects and resource pins.
  - name: Sandboxes
    description: Firecracker microVM lifecycle, exec, URLs, SSH/VNC.
  - name: Agents
    description: Agent definitions and CRUD.
  - name: Agent marketplace
    description: Public marketplace listing and install.
  - name: Agent runs
    description: Dispatch and observe agent runs.
  - name: Channels
    description: External messaging channels and channel privacy.
  - name: Threads
    description: Public thread storage (JSONL-backed).
  - name: Workspaces
    description: Workspace metadata and usage (control plane).
  - name: Workspace files
    description: NFS-backed workspace file APIs (storage service).
  - name: Installable agents
    description: Hermes catalog and install lifecycle.
  - name: Attachments
    description: Agent message attachments (uploaded files).
  - name: Tools (marketplace)
    description: Public tool marketplace and schemas.
  - name: Tools (installed)
    description: Org tool installs and credentials.
  - name: Tools (custom)
    description: Org-private custom tool CRUD and publishing.
  - name: Tool execution
    description: Server-side tool invocation.
  - name: Secrets
    description: Encrypted secrets (org-scoped).
  - name: SSH keys
    description: SSH key CRUD for sandbox access.
  - name: API keys
    description: API key issuance and revocation.
  - name: OAuth connections
    description: User OAuth connections to providers.
  - name: BYOA configs
    description: Bring-your-own-app OAuth client configuration.
  - name: LangTerm
    description: LangTerm SSH connection profiles.
  - name: Models
    description: Available model registry.
  - name: Model proxy
    description: Platform-tier model invocation.
  - name: Calendar
    description: Google Calendar connections.
  - name: RunMesh
    description: RunMesh device pairing and management.
  - name: Terminal
    description: Browser terminal session minting.
  - name: Activity
    description: Customer-facing activity event log.
  - name: Billing
    description: Credits, top-up, auto-top-up, usage pricing.
  - name: Auth
    description: Token verification and logout URLs.
paths:
  /v1/workspaces/{id}/upload:
    post:
      tags:
        - Workspace files
      summary: Upload a file to the workspace root
      operationId: uploadWorkspaceFile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: id
          in: query
          description: Optional target sub-path within the workspace.
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                name:
                  type: string
              required:
                - file
      responses:
        '200':
          description: Uploaded.
        '413':
          description: File exceeds upload limit.
      servers:
        - url: https://storage.runtools.ai
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        WorkOS session token or RunTools API key (`rt_live_*` / `rt_test_*`).
        Used in `Authorization: Bearer <token>` header.
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative location for a RunTools API key (`rt_live_*` / `rt_test_*`).

````