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

# Get a direct download URL

> Returns a machine-scoped authenticated URL that downloads the requested
file directly from the machine with a plain `GET`. The URL contains a
short-lived file transfer token scoped to the target machine path.




## OpenAPI

````yaml /openapi.yaml post /v1/machines/{id}/files/download-url
openapi: 3.1.0
info:
  title: Nullspace API
  version: 0.1.0
  description: |
    Cloud machine platform for AI agents. Create on-demand microVMs,
    execute commands, manage files, automate desktop environments,
    and stream output over WebSocket.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.13-215-85-171.sslip.io
    description: Private beta
  - url: https://nullspace.example
    description: Self-hosted single-host owned-domain
  - url: http://localhost
    description: Self-hosted single-host localhost/no-domain via Caddy
  - url: http://localhost:3000
    description: Local development direct API
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Public process-liveness check (no auth required)
  - name: Machines
    description: Machine lifecycle, execution, and process management
  - name: Files
    description: Filesystem operations within a machine
  - name: Git
    description: First-class structured git operations within a machine
  - name: Desktop
    description: Desktop automation (mouse, keyboard, screenshots)
  - name: Recording
    description: Screen recording management
  - name: PTY
    description: Pseudo-terminal session management
  - name: Templates
    description: Machine template management
  - name: Agent Deployments
    description: Named, versioned agent deployment control plane
  - name: Volumes
    description: Persistent volume control plane and attached volume actions
  - name: WebSocket
    description: Streaming execution and PTY over WebSocket
  - name: Monitor
    description: In-repo WebSocket stream for machine health, metrics, and process updates
  - name: API Keys
    description: Runtime API key metadata and dormant self-serve key management
  - name: Account
    description: Dormant Supabase-session account profile, export, and deletion routes
  - name: Admin
    description: Supabase-session operator console APIs for account support
  - name: Auth
    description: Dormant self-serve Auth proxy routes gated by deployment config
  - name: Code
    description: Stateful code execution via Jupyter kernels (Code Interpreter)
  - name: Internal Operations
    description: Operator-only internal API surfaces; not part of the public SDK contract
paths:
  /v1/machines/{id}/files/download-url:
    parameters:
      - $ref: '#/components/parameters/MachineId'
    post:
      tags:
        - Files
      summary: Get a direct download URL
      description: |
        Returns a machine-scoped authenticated URL that downloads the requested
        file directly from the machine with a plain `GET`. The URL contains a
        short-lived file transfer token scoped to the target machine path.
      operationId: downloadUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PathRequest'
      responses:
        '200':
          description: Direct download URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedUrlResponse'
components:
  parameters:
    MachineId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Machine ID (e.g. mch_a1b2c3d4)
  schemas:
    PathRequest:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          description: >-
            Machine path to target. Absolute paths may target valid machine
            locations such as `/workspace`, `/data`, `/tmp`, or `/context` where
            present. Relative paths resolve from the machine cwd when set,
            otherwise from the selected user's home when `user` is provided,
            otherwise from `/workspace`.
        user:
          type: string
          description: Optional machine user for relative-path resolution and ownership.
    SignedUrlResponse:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: >-
            A machine-scoped URL for direct download with a short-lived file
            transfer token.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````