POST chats — Muse API v1

Start a chat

October 12, 2026

Request Headers
Request Body
Responses
Model
Examples
Try It

Start a chat with Muse, Meta’s AI agent, and get a chatId for it. The answer streams live from GET /chats/chatId/stream, and you can send more messages at any time with POST /chats/chatId/messages, even while Muse is still answering. The Chat Streaming Guide walks through the whole flow, and the Live Demo runs it in your browser.

A chat reaches the whole Muse agent, not only images and videos. It can talk, research the web, write and run code, and use the apps connected to the Muse account, the same as a chat in the muse.ai app. The chat is a normal Muse chat: it shows in the muse.ai app too.

Files go in and come out as the same asset ids the jobs use. Pass your files in files, as asset ids from POST /assets or from an earlier job or chat, or as workspace paths of documents and data written with POST /files. Every file Muse makes arrives as a file event on the stream, and downloads with GET /assets/assetId.

Chat does not use the account’s maxJobs, which limits jobs only. Chat uses the account’s weekly Muse allowance, like jobs do.

https://api.useapi.net/v1/muse/chats

Request Headers

Authorization: Bearer {API token}
Content-Type: application/json

API token is required, see Setup useapi.net for details.

Request Body

{
  "message": "Write a 300-word story about the sea, then make one image for it.",
  "files": [
    "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:3e788737ea18422b9809aeb06a453c072e15f1b3fb219d7a4fd7e8fffd733d4f.jpg"
  ],
  "email": "[email protected]"
}

message is required, what you say to Muse.
Maximum length: 5000 characters.
files is optional, an array of:
- asset ids from POST /assets, GET /assets, a job’s result.assets[] or a chat’s file event, up to 9 images, 3 videos and 3 audio files.
- workspace paths of any other file, such as a PDF, a spreadsheet or code, from POST /files or GET /files, up to 10, for example workspace/your_files/report.pdf.
Muse sees them as image_1, image_2… video_1… audio_1… file_1, file_2… in the order you list them, so the message can name them, for example put the person from image_1 into image_2 or summarize file_1.
All files must be on the same Muse account, and the chat runs on that account. When you send only workspace paths and the API token has more than one Muse account, email is required, so the chat runs on the account that holds them.
email is optional, the account to chat on. When omitted, the account that holds the files is used, or without files a healthy account with allowance left.

Responses

201 Created — the message was sent and Muse is answering. Open GET /chats/chatId/stream to read the answer.

{
  "chatId": "c-u12345-email:[email protected]:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse",
  "email": "[email protected]",
  "messageId": "389bfe1b-d8a0-47ed-9b11-d9269a8ed656"
}

400 Bad Request — a parameter is missing or invalid, the files are on different accounts, or no Muse account is added yet.

{
  "error": "Parameter message is required",
  "code": 400
}

{
  "error": "Please configure at least one account at https://useapi.net/docs/api-muse-v1/post-muse-accounts",
  "code": 400
}

401 Unauthorized

Invalid API token.

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

403 Forbidden — a file’s asset id belongs to another API token.

{
  "error": "This asset id does not belong to this API token",
  "code": 403
}

404 Not Found — the account named by email, or the account a file lives on, is not added.

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

412 Precondition Failed — the account’s weekly Muse allowance is used up (or every account’s, without email).

{
  "error": "All 2 healthy accounts have used up their Muse allowance. GET /accounts/{email} re-reads it",
  "code": 412
}

429 Too Many Requests — Muse is limiting requests on the account. Retry in about a minute.

{
  "error": "Muse is limiting requests on account [email protected] right now. Retry in about a minute",
  "code": 429
}

502 Bad Gateway — Muse did not accept the message. Retry.

{
  "error": "Muse did not accept the message (HTTP 400). Please retry",
  "code": 502
}

503 Service Unavailable — Muse could not be reached, and nothing was sent. Retry shortly.

{
  "error": "Muse did not accept the message (HTTP 500). Please retry",
  "code": 503
}

504 Gateway Timeout — the connection to Muse dropped while the message was being sent. It may have arrived: look at GET /chats before you send it again.

{
  "error": "The connection to Muse dropped while sending (…). The message may have arrived: check GET /chats/{chatId} before sending it again",
  "code": 504
}

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
  chatId: string        // c-u<id>-email:<email>-chat:<Muse chat id>-bot:muse
  email: string         // the account the chat runs on
  messageId: string | null  // Muse's id of your message, as the stream's `message` event shows it
  error?: string        // errors only
  code?: number         // errors only
}

Examples

curl -X POST "https://api.useapi.net/v1/muse/chats" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "message": "Write a 300-word story about the sea, then make one image for it."
   }'

const token = "API token";
const apiUrl = "https://api.useapi.net/v1/muse/chats";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({ message: "Write a 300-word story about the sea, then make one image for it." })
});
const result = await response.json();
console.log("response", response.status, result);
/* next: read the answer from GET /chats/{chatId}/stream, see the Chat Streaming Guide */

import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/muse/chats"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {"message": "Write a 300-word story about the sea, then make one image for it."}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())

Try It

The form starts the chat. Copy the chatId into GET /chats/chatId/stream to watch the answer, or try the Live Demo.