Skip to main content
POST
https://macaly.com/
/
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
executionModestringNo-"auto", "planning", or "build"

​
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://macaly.com/chat/abc123def456",
  "streamId": "stream_xyz789",
  "assistantMessageId": "msg_123"
}
FieldTypeDescription
chatIdstringThe unique chat identifier
urlstringDirect URL to view the chat
streamIdstringStream identifier for subscribing
assistantMessageIdstringID of the assistant message being generated

​
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
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