Skip to main content
POST
/
api
/
chat
Create Chat
curl --request POST \
  --url https://macaly.com/api/chat \
  --header 'Authorization: Bearer <token>'
Creates a new chat session and starts the AI workflow.

​
Request

POST /api/chat

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer macaly_...
Content-TypeYesapplication/json

​
Body Parameters

FieldTypeRequiredDefaultDescription
contentstringYes-The user’s message/prompt
streambooleanNotrueIf false, returns JSON instead of stream
backendstringNo"DEFAULT"Backend to use
executionMode"auto" | "planning" | "build"No-Controls how the AI approaches the task
model"sonnet-4-5" | "sonnet-4-6" | "opus-4-5" | "opus-4-6"No-AI model to use. Defaults to team’s configured model
reasoningEffort"medium" | "high"No-Controls how deeply the AI reasons about the task
experimental_attachmentsarrayNo[]File attachments (see format below)

​
Attachment Format

Each item in the experimental_attachments array has the following structure:
FieldTypeRequiredDescription
urlstringYesURL of the file to attach
namestringNoDisplay name for the attachment
contentTypestringNoMIME type of the file

​
Example Request

curl -X POST https://www.macaly.com/api/chat \
  -H "Authorization: Bearer macaly_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Create a landing page for a coffee shop",
    "stream": false
  }'

​
Response

​
JSON Response (when stream: false)

{
  "chatId": "abc123def456",
  "url": "https://www.macaly.com/chat/abc123def456",
  "streamId": "stream_xyz789",
  "assistantMessageId": "msg_123"
}
FieldTypeDescription
chatIdstringThe unique chat identifier
urlstringDirect URL to view the chat
streamIdstring | undefinedStream identifier for subscribing. Only present for workflow backends
assistantMessageIdstring | undefinedID of the assistant message being generated. Only present for workflow backends

​
Streaming Response (when stream: true, default)

When streaming is enabled, the response is a text stream: 
2:[{"chatId":"abc123def456"}]
0:"Starting to build..."
...
The first line contains the chat ID in the format 2:[{"chatId":"..."}].

​
Parsing the Chat ID from Stream

const text = await response.text();
const match = text.match(/2:\[{"chatId":"([^"]+)"/);
const chatId = match?.[1];

​
Status Codes

StatusDescription
200Success - Chat created
400Invalid request body
401Invalid or missing API key
402Insufficient credits
403Forbidden - No permission for the specified team
422Validation error
429Rate limited
500Server error

​
Next Steps

After creating a chat:
  1. Poll for completion using GET /api/chat/{chatId}/status
  2. Subscribe to stream using GET /api/chat/{chatId}/subscribe for real-time updates
  3. Send follow-up messages using POST /api/chat/{chatId}/publish