List workspace files

October 12, 2026

Table of contents

  1. Request Headers
  2. Query Parameters
  3. Responses
  4. Model
  5. Examples
  6. Try It

List a folder in the Muse workspace of an account: the files and folders in it, with their size and date. Given the path of a file, it answers that file’s entry.

Files and assets are two views of the same workspace. Assets are the images, videos and audio files, each with an assetId for jobs and chats. /files covers the whole workspace, including the code, documents and data the agent writes. A media file listed here also carries its assetId.

Paths always start with workspace/, for example workspace/your_files/report.pdf. Read a file with GET /files/content, find files with GET /files/search, write one with POST /files, and remove one with DELETE /files.

https://api.useapi.net/v1/muse/files?email=email&path=path

Request Headers 
Authorization: Bearer {API token}
Query Parameters
  • email is optional when the API token has one Muse account, and required when it has more. URL-encode it.
  • path is optional, a folder or a file in the workspace.
    Default: workspace.
Responses

  • 200 OK — a folder:

    {
  "email": "[email protected]",
  "path": "workspace/your_files",
  "entries": [
    {
      "name": "balalaika_etude.mp3",
      "path": "workspace/your_files/balalaika_etude.mp3",
      "type": "file",
      "bytes": 2321598,
      "modified": "2026-10-05T05:07:37.404Z",
      "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-audio:ws~your_files~balalaika_etude.mp3"
    },
    {
      "name": "sunkissed-lyrics.txt",
      "path": "workspace/your_files/sunkissed-lyrics.txt",
      "type": "file",
      "bytes": 769,
      "modified": "2026-10-05T05:02:00.385Z",
      "assetId": null
    }
  ]
}

    The top folder, workspace:

    {
  "email": "[email protected]",
  "path": "workspace",
  "entries": [
    {
      "name": "code",
      "path": "workspace/code",
      "type": "directory",
      "bytes": null,
      "modified": "2026-10-13T01:28:06.219Z"
    },
    {
      "name": "your_files",
      "path": "workspace/your_files",
      "type": "directory",
      "bytes": null,
      "modified": "2026-10-13T01:54:06.788Z"
    }
  ]
}

    A file path answers that file’s entry:

    {
  "email": "[email protected]",
  "name": "sunkissed-lyrics.txt",
  "path": "workspace/your_files/sunkissed-lyrics.txt",
  "type": "file",
  "bytes": 769,
  "modified": "2026-10-05T05:02:00.385Z",
  "assetId": null
}

  • 400 Bad Request — path is not a path in the workspace, or the token has more than one Muse account and email is missing.

    {
  "error": "Parameter path must be a path in the workspace, e.g. workspace/your_files/notes.txt",
  "code": 400
}

  • 401 Unauthorized — Invalid API token.

    {
  "error": "useapi.net ⁝ Unauthorized",
  "code": 401
}

  • 404 Not Found — the path is not in the workspace, or the account named by email is not added.

    {
  "error": "Path not found",
  "code": 404
}

  • 503 Service Unavailable — Muse could not be reached. Retry shortly.

    {
  "error": "Muse could not do it right now (…), please retry",
  "code": 503
}

  • 596 Account Error

    The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are two causes.

    Meta asks for a security check on the account. Sign in once at muse.ai in a browser, complete the check, then add the account again with POST /accounts using the same email and password. The API keeps using its session, so no new sign-in is needed.

    {
  "error": "Account [email protected]: Meta asks for a security check on account [email protected] (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts",
  "code": 596
}

    Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password.

    {
  "error": "Account [email protected]: Muse refused to sign in account [email protected] (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it",
  "code": 596
}
Model 
{ // TypeScript, all fields are optional
  email: string
  path: string                 // the folder listed
  entries: {
    name: string
    path: string                 // workspace/…
    type: 'file' | 'directory'
    bytes: number | null
    modified: string | null      // ISO 8601
    assetId?: string | null      // files only: the asset id of an image, video or audio file, else null
  }[]
  error?: string               // errors only
  code?: number                // errors only
}

For a file path, the response is email plus that file’s entry fields.

Examples 
  • curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/muse/files?email=example%40gmail.com&path=workspace%2Fyour_files"

  • const token = "API token";
const params = new URLSearchParams({ email: "[email protected]", path: "workspace/your_files" });
const response = await fetch(`https://api.useapi.net/v1/muse/files?${params}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`,
  }
});
console.log("response", response.status, await response.json());

  • import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/muse/files"
headers = {
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers, params={"email": "[email protected]", "path": "workspace/your_files"})
print(response, response.json())
Try It