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

# List files

> List the files stored in a workspace.

Lists the files stored in a workspace, newest first. Pass `desktopId` to filter to a single computer.

## Query parameters

<ParamField query="workspaceId" type="string" required>
  Workspace ID. Omitting it returns 400.
</ParamField>

<ParamField query="desktopId" type="string">
  Computer UUID to filter by. When omitted, every file in the workspace is returned, whichever computer it belongs to. A value that is not a UUID, such as an instance id, returns 500.
</ParamField>

## Response

<ResponseField name="files" type="array">
  File objects, ordered by `created_at` descending, newest first. An empty array when the workspace holds no files.
</ResponseField>

<ResponseField name="files[].id" type="string">
  File ID. Pass it as `id` to the download and delete endpoints.
</ResponseField>

<ResponseField name="files[].filename" type="string">
  Original file name.
</ResponseField>

<ResponseField name="files[].size_bytes" type="string | null">
  Size in bytes as a decimal string, such as `"1024"`, or `null` when no size was recorded. The value is a 64-bit integer, so it is serialized as a string. Parse it before doing arithmetic.
</ResponseField>

<ResponseField name="files[].content_type" type="string | null">
  MIME type, or `null` when none was recorded.
</ResponseField>

<ResponseField name="files[].source" type="string">
  How the file entered the workspace: `upload` or `export`.
</ResponseField>

<ResponseField name="files[].desktop_id" type="string | null">
  Computer the file is associated with, or `null` when it is not tied to one.
</ResponseField>

<ResponseField name="files[].created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  # Every file in the workspace
  curl "https://www.orgo.ai/api/files?workspaceId=$WORKSPACE_ID" \
    -H "Authorization: Bearer $ORGO_API_KEY"

  # Only the files tied to one computer
  curl "https://www.orgo.ai/api/files?workspaceId=$WORKSPACE_ID&desktopId=$COMPUTER_ID" \
    -H "Authorization: Bearer $ORGO_API_KEY"
  ```

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

  response = requests.get(
      "https://www.orgo.ai/api/files",
      headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
      params={
          "workspaceId": os.environ["WORKSPACE_ID"],
          "desktopId": os.environ["COMPUTER_ID"],  # optional
      },
  )

  files = response.json()["files"]
  for f in files:
      print(f"{f['filename']} ({f['size_bytes']} bytes, {f['source']})")
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    workspaceId: process.env.WORKSPACE_ID,
    desktopId: process.env.COMPUTER_ID, // optional
  });

  const response = await fetch(`https://www.orgo.ai/api/files?${params}`, {
    headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
  });

  const { files } = await response.json();
  files.forEach((f) => {
    console.log(`${f.filename} (${f.size_bytes} bytes, ${f.source})`);
  });
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "files": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "filename": "results.txt",
      "size_bytes": "1024",
      "created_at": "2024-01-15T11:00:00Z",
      "desktop_id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "content_type": "text/plain",
      "source": "export"
    },
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "filename": "document.pdf",
      "size_bytes": "102400",
      "created_at": "2024-01-15T10:30:00Z",
      "desktop_id": null,
      "content_type": "application/pdf",
      "source": "upload"
    }
  ]
}
```

## Errors

Every error carries the shape `{"error": "<message>"}`.

| Status | Body | Cause |
| - | - | - |
| `400` | `{"error": "workspaceId is required"}` | The `workspaceId` query parameter was absent. |
| `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 workspace nor belongs to it, or `desktopId` names a computer in such a workspace. A workspace ID that does not exist also returns this. This endpoint never returns 404. |
| `401` | `{"error": "This API key cannot access this workspace (workspace_scope_mismatch)."}` | A workspace-scoped key named a different workspace, or a computer in one. |
| `401` | `{"error": "Service temporarily unavailable. …"}` | Orgo could not verify the credential because of a server-side fault. Retry. |
| `500` | `{"error": "Failed to list files"}` | The lookup failed, for example because `desktopId` is not a UUID. The message may instead carry the underlying database error. |


## OpenAPI

````yaml GET /files
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:
    get:
      tags:
        - Files
      summary: List files
      description: Lists all files in a workspace, optionally filtered by computer.
      operationId: listFiles
      parameters:
        - name: workspaceId
          in: query
          required: true
          description: Workspace ID. Required; omitting it is a `400`.
          schema:
            type: string
        - name: desktopId
          in: query
          required: false
          description: >-
            Restrict the list to files attached to one computer. Omitted, every
            file in the workspace is returned.
          schema:
            type: string
      responses:
        '200':
          description: List of files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
        '400':
          description: The `workspaceId` query parameter was absent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: workspaceId is required
        '401':
          description: >-
            No usable credential, or an access check failed. You neither own nor
            belong to the workspace (a workspace ID that does not exist also
            returns this, and this endpoint never returns `404`), or the key is
            scoped to another workspace. These checks run during authentication,
            so they return `401`. A server-side fault while verifying the
            credential also returns `401`; retry that one.
          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.
                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.
        '500':
          description: >-
            The lookup failed. The message may instead carry the underlying
            database error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Failed to list files
components:
  schemas:
    FileListResponse:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/File'
    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
  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.