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

# Export file

> Copy a file off a computer into workspace storage. Not currently available.

<Warning>
  **This endpoint is not currently available.** Every call fails with 404. The
  API accepts the request and forwards it to the computer. The software running
  on the computer implements no export handler, so the request has nowhere to
  land. No set of arguments makes it succeed. This page records the intended
  contract and the behaviour you will observe today. Do not build against it.
</Warning>

Intended to copy a file off a computer's filesystem into workspace storage and return a download URL.

## Request

Send a JSON body.

<ParamField body="desktopId" type="string" required>
  Computer ID to export from. Omitting it returns 400.
</ParamField>

<ParamField body="path" type="string" required>
  Path to the file on the computer. Omitting it returns 400. The value is forwarded to the computer unchanged. How it would be resolved is not defined, because no handler on the computer reads it.
</ParamField>

## Response

There is no success response. The request is rejected before any file is read.

Calls that get as far as the computer return:

```json theme={null}
{
  "error": "VM export failed: 404"
}
```

with HTTP status 404.

## Example

The call below is well-formed against a running computer and still returns 404.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.orgo.ai/api/files/export \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"desktopId\": \"$COMPUTER_ID\", \"path\": \"/root/Desktop/results.txt\"}"
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://www.orgo.ai/api/files/export",
      headers={
          "Authorization": f"Bearer {os.environ['ORGO_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "desktopId": os.environ["COMPUTER_ID"],
          "path": "/root/Desktop/results.txt",
      },
  )

  print(response.status_code, response.json())  # 404 {'error': 'VM export failed: 404'}
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://www.orgo.ai/api/files/export', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ORGO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      desktopId: process.env.COMPUTER_ID,
      path: '/root/Desktop/results.txt',
    }),
  });

  console.log(response.status, await response.json()); // 404 { error: 'VM export failed: 404' }
  ```
</CodeGroup>

## Getting a file off a computer today

Read the file over the computer's shell and write it where you want it. To send a file the other way, use the [upload endpoint](/api-reference/files/upload): its `destPath` field places a file at an exact path on a computer.

## Errors

Every error carries the shape `{"error": "<message>"}`. The checks below run in order, so the first one that fails is the status you get.

| Status | Body | Cause |
| - | - | - |
| `401` | `{"error": "Invalid API key"}` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{"error": "Authentication required"}` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `401` | `{"error": "You do not have access to this workspace."}` | The caller neither owns the computer's workspace nor belongs to it. |
| `401` | `{"error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)."}` | The caller has view-only access to the computer's workspace. |
| `401` | `{"error": "This API key cannot access this workspace (workspace_scope_mismatch)."}` | A workspace-scoped key named a computer in a different workspace. |
| `500` | `{"error": "…"}` | The body is not valid JSON. The message is the parser's. |
| `400` | `{"error": "Missing desktopId or path"}` | Either field was absent or empty. |
| `404` | `{"error": "Desktop not found"}` | No computer has that ID. A `desktopId` that is not a UUID returns `500` at this step instead. |
| `402` | `{"error": "Choose a plan to continue."}` | The computer is a free trial computer that can no longer run. |
| `402` | `{"error": "Manage this computer’s payment in Account → Usage."}` | The computer is paid for by its own subscription or dedicated purchase, and that payment has lapsed. |
| `400` | `{"error": "Desktop is not running"}` | The computer's status is anything other than `running`. |
| `400` | `{"error": "Desktop has no instance ID"}` | The computer record carries no instance ID. |
| `503` | `{"error": "Computer not ready"}` | The computer has no connection details recorded, so it cannot be addressed. |
| `404` | `{"error": "VM export failed: 404"}` | The computer has no export handler. Every request that reaches this point ends here. |
| `500` | `{"error": "Export failed"}` | Unexpected failure. The message may instead carry the underlying error. |

A failure reported by the computer is relayed with the computer's own status code and its own error message, so statuses outside this list are possible if the software on the computer changes.


## OpenAPI

````yaml POST /files/export
openapi: 3.1.0
info:
  title: Orgo API
  description: >-
    Launch cloud computers that AI agents can control and interact with. Create
    workspaces, provision computers, and control them programmatically.
  version: 2.0.0
  contact:
    name: Orgo Support
    email: spencer@orgo.ai
    url: https://orgo.ai
servers:
  - url: https://www.orgo.ai/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account capacity: how many computers an account may run, and adding or
      giving back more.
  - name: Clients
    description: >-
      Run Orgo for your clients from your own app: a workspace and scoped key
      each, billed to you or to them.
  - name: Workspaces
    description: Organize computers into named workspaces
  - name: Computers
    description: Provision and manage virtual computers
  - name: Computer Lifecycle
    description: Start, stop, and restart computers
  - name: Computer Actions
    description: Control mouse, keyboard, and execute commands
  - name: Screens
    description: >-
      More than one desktop on a single computer. Each screen is its own X
      server with its own cursor and window manager, so an agent working on one
      cannot disturb another.
  - name: Files
    description: Upload and download files
  - name: Templates
    description: Author, build, and launch reproducible computers from templates
paths:
  /files/export:
    post:
      tags:
        - Files
      summary: Export file (unavailable)
      description: >-
        Not currently available. The API accepts the request and forwards it to
        the computer, but the software running on the computer implements no
        export handler, so every call fails with `404`. No set of arguments
        makes it succeed. Documented to record the intended contract and the
        behaviour you will observe. Do not build against it. To move a file off
        a computer today, read it with `POST /computers/{id}/bash` or push it
        somewhere yourself from inside the computer.
      operationId: exportFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileExportRequest'
            example:
              desktopId: a3bb189e-8bf9-3888-9912-ace4e6543002
              path: Desktop/results.txt
      responses:
        '200':
          description: The intended success shape. Not returned today. See the description.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileExportResponse'
        '400':
          description: >-
            `desktopId` or `path` is missing, the computer is not `running`, or
            it has no instance ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing:
                  summary: Missing field
                  value:
                    error: Missing desktopId or path
                not-running:
                  summary: Not running
                  value:
                    error: Desktop is not running
                no-instance:
                  summary: No instance ID
                  value:
                    error: Desktop has no instance ID
        '401':
          $ref: '#/components/responses/UnauthorizedWithAccess'
        '402':
          $ref: '#/components/responses/TrialInactive'
        '404':
          description: >-
            No computer has that ID, or the computer has no export handler.
            Every request that gets that far ends here.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no-computer:
                  summary: Unknown computer
                  value:
                    error: Desktop not found
                no-handler:
                  summary: No export handler
                  value:
                    error: 'VM export failed: 404'
        '500':
          description: >-
            Unexpected failure. The message may instead carry the underlying
            error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Export failed
        '503':
          description: >-
            The computer has no connection details recorded, so it cannot be
            addressed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Computer not ready
      deprecated: true
components:
  schemas:
    FileExportRequest:
      type: object
      required:
        - desktopId
        - path
      properties:
        desktopId:
          type: string
          description: Computer ID
        path:
          type: string
          description: Path to file on computer (e.g., Desktop/results.txt)
    FileExportResponse:
      type: object
      properties:
        success:
          type: boolean
        file:
          $ref: '#/components/schemas/File'
        url:
          type: string
          description: Signed download URL (expires in 1 hour)
    Error:
      type: object
      description: >-
        The base error body. Every failure carries `error`; individual endpoints
        add the fields named in the schemas below.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable message.
          example: Access denied
        code:
          type: string
          description: >-
            Machine-readable reason. Present on the failures that define one,
            absent otherwise.
    File:
      type: object
      properties:
        id:
          type: string
          description: File ID
        desktop_id:
          type:
            - string
            - 'null'
          description: >-
            Computer the file is associated with, or `null` when it is not tied
            to one.
        filename:
          type: string
          description: Original filename
        size_bytes:
          type:
            - string
            - 'null'
          description: >-
            File size in bytes, as a decimal string such as `"102400"`. The
            value is a 64-bit integer, so it is serialized as a string. Parse it
            before doing arithmetic. `null` when no size was recorded.
          example: '102400'
        content_type:
          type:
            - string
            - 'null'
          description: MIME type
        source:
          type: string
          enum:
            - upload
            - export
          description: How the file entered the workspace.
        created_at:
          type: string
          format: date-time
  responses:
    UnauthorizedWithAccess:
      description: >-
        No usable credential, or an access check failed. This endpoint runs its
        workspace access checks during authentication, so it answers a missing
        membership, view-only access, or a key scoped to another workspace with
        `401`, not `403`. A server-side fault while verifying the credential
        also returns `401`, with a `Service temporarily unavailable` message.
        Retry that one; the key is fine.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid-key:
              summary: The key is not one of yours
              value:
                error: Invalid API key
            no-credential:
              summary: No key and no session
              value:
                error: Authentication required
            no-access:
              summary: Not the owner or a member of the workspace
              value:
                error: You do not have access to this workspace.
            view-only:
              summary: View-only member, and the request changes something
              value:
                error: >-
                  This workspace is view-only. Ask the owner for write access
                  (workspace_read_only).
            scope-mismatch:
              summary: The API key is scoped to another workspace
              value:
                error: >-
                  This API key cannot access this workspace
                  (workspace_scope_mismatch).
            service-unavailable:
              summary: Server-side fault while verifying the credential. Retry.
              value:
                error: >-
                  Service temporarily unavailable. The database is not accepting
                  requests. Retry shortly.
    TrialInactive:
      description: >-
        The computer is a free trial computer whose trial is no longer active,
        or it is paid for by its own subscription or dedicated purchase and that
        payment has lapsed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            trial:
              summary: Trial no longer active
              value:
                error: Choose a plan to continue.
            payment:
              summary: The computer's own payment has lapsed
              value:
                error: Manage this computer’s payment in Account → Usage.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key at orgo.ai/workspaces

````

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