Write a workspace file

October 12, 2026

Table of contents

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

Write a file of any type into the Muse workspace of an account, at the path you choose: a PDF, a spreadsheet, code, text or media. A file already at that path is replaced. Send the file as the raw request body.

To have the agent work on it, pass its path in files of POST /chats or POST /chats/chatId/messages, for example upload workspace/your_files/report.pdf and send "files": ["workspace/your_files/report.pdf"] with “Summarize file_1”.

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. For an image, video or audio file you want to use in jobs, POST /assets is the simpler choice.

Paths always start with workspace/. Write into your own folders, for example workspace/your_files/…. Media for jobs and chats goes in with POST /assets.

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

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/pdf   # the file's MIME type
Content-Length: 52               # most HTTP clients set it for you
  • API token is required, see Setup useapi.net for details.
  • Content-Type is optional, the file’s MIME type.
  • Content-Length is required, the file size in bytes.

The request body is the file’s raw bytes, from 1 byte to 52,428,800 bytes (50 MB).

Query Parameters
  • email is optional when the API token has one Muse account, and required when it has more. URL-encode it.
  • path is required, where to write the file, for example workspace/your_files/report.pdf. A file already there is replaced.
Responses

  • 200 OK — the written file.

    {
  "email": "[email protected]",
  "name": "report.pdf",
  "path": "workspace/your_files/report.pdf",
  "type": "file",
  "bytes": 52,
  "modified": "2026-10-13T01:54:06.788Z",
  "assetId": null
}

  • 400 Bad Request — path is a folder or not a path in the workspace, or the body is empty.

    {
  "error": "Path is a folder: give the file path, e.g. workspace/your_files/notes.pdf",
  "code": 400
}

  • 401 Unauthorized — Invalid API token.

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

  • 404 Not Found — the account named by email is not added.

    {
  "error": "Account [email protected] is not configured",
  "code": 404
}

  • 411 Length Required — the request has no Content-Length header, for example a streamed (chunked) body.

    {
  "error": "Content-Length is required (send the file as the raw request body)",
  "code": 411
}

  • 413 Content Too Large — the file is larger than 52,428,800 bytes (50 MB).

    {
  "error": "File must be at most 52428800 bytes",
  "code": 413
}

  • 409 Conflict — another request is writing the same file right now. Retry shortly.

    {
  "error": "This file is being written by another request, please retry shortly",
  "code": 409
}

  • 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
  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
}
Examples 
  • curl -X POST -H "Authorization: Bearer …" \
     -H "Content-Type: application/pdf" \
     --data-binary @report.pdf \
     "https://api.useapi.net/v1/muse/files?email=example%40gmail.com&path=workspace%2Fyour_files%2Freport.pdf"

  • import fs from "fs";
const token = "API token";
const params = new URLSearchParams({ email: "[email protected]", path: "workspace/your_files/report.pdf" });
const response = await fetch(`https://api.useapi.net/v1/muse/files?${params}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/pdf",
    "Authorization": `Bearer ${token}`,
  },
  body: fs.readFileSync("report.pdf")
});
console.log("response", response.status, await response.json());

  • import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/muse/files"
headers = {
    "Content-Type": "application/pdf",
    "Authorization" : f"Bearer {token}"
}
response = requests.post(apiUrl, headers=headers, params={"email": "[email protected]", "path": "workspace/your_files/report.pdf"}, data=open("report.pdf", "rb").read())
print(response, response.json())
Try It