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

# Delete file

> Permanently delete a file from a workspace.

Permanently deletes a file from storage and removes its record from the workspace.

<Warning>
  This action cannot be undone. Signed download URLs issued for the file before
  deletion stop working.
</Warning>

## Query parameters

<ParamField query="id" type="string" required>
  File ID, as returned by the list or upload endpoints. Omitting it returns 400.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true`. Any failure is reported as an error status, not as `false`.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://www.orgo.ai/api/files/delete?id=$FILE_ID" \
    -H "Authorization: Bearer $ORGO_API_KEY"
  ```

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

  response = requests.delete(
      "https://www.orgo.ai/api/files/delete",
      headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
      params={"id": os.environ["FILE_ID"]},
  )

  if response.ok:
      print("File deleted")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://www.orgo.ai/api/files/delete?id=${process.env.FILE_ID}`,
    {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
    },
  );

  if (response.ok) console.log('File deleted');
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "success": true
}
```

<Info>
  The stored object is removed first, then the file record. If removing the
  object fails, the endpoint returns 500 and the record is left in place. The
  file still appears in the list endpoint. Retry the delete.
</Info>

Deleting a file does not remove any copy that was pushed onto a computer. A file synced to `/root/Desktop` stays on that computer.

## Errors

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

| Status | Body | Cause |
| - | - | - |
| `400` | `{"error": "Missing file id"}` | The `id` query parameter was absent. |
| `400` | `{"error": "id and fileId must identify the same file"}` | Both `id` and `fileId` were sent with different values. |
| `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 file exists, but the caller neither owns its 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 file's workspace. |
| `401` | `{"error": "This API key cannot access this workspace (workspace_scope_mismatch)."}` | A workspace-scoped key targeted a file in a different workspace. |
| `401` | `{"error": "Service temporarily unavailable. …"}` | Orgo could not verify the credential because of a server-side fault. Retry. |
| `404` | `{"error": "File not found"}` | No file has that ID. A second delete of the same file returns 404. |
| `500` | `{"error": "Delete failed"}` | The object or the record could not be removed, or the `id` is not a UUID. The message may instead carry the underlying error. |

## Compatibility parameter

Prefer `id`. The older `fileId` spelling is also accepted as an alias. If both are present with different values the request returns `400`. At least one is required.


## OpenAPI

````yaml DELETE /files/delete
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/delete:
    delete:
      tags:
        - Files
      summary: Delete file
      description: Permanently deletes a file from storage.
      operationId: deleteFile
      parameters:
        - name: id
          in: query
          required: false
          description: >-
            File ID. Supply id or its compatibility alias fileId. If both are
            supplied they must match.
          schema:
            type: string
        - name: fileId
          in: query
          description: Compatibility alias for id. Prefer id.
          schema:
            type: string
      responses:
        '200':
          description: File deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: No file id, or `id` and `fileId` name different files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing:
                  summary: No id
                  value:
                    error: Missing file id
                mismatch:
                  summary: Conflicting ids
                  value:
                    error: id and fileId must identify the same file
        '401':
          $ref: '#/components/responses/UnauthorizedWithAccess'
        '404':
          description: No file has that ID. A second delete of the same file returns `404`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: File not found
        '500':
          description: >-
            The object or the record could not be removed. The message may
            instead carry the underlying error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Delete failed
components:
  schemas:
    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.
  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.
  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.