Chat with the campaign AI assistant and read past conversations. The assistant answers from the campaign's knowledge base (vector store) built during campaign generation.
Chat requires the agent:write scope; reading conversations requires agent:read. All operations are scoped to the API key's workspace.
Synchronous & free. The public chat endpoint returns a single JSON reply (no streaming). It consumes no credits — abuse is controlled by per-key rate limiting. Both the user and assistant messages are persisted server-side, so they appear in conversation history.
POST /api/v1/agent/chat · scope agent:write
Field Type Required Description messagestring Yes The user message (1–8000 chars, trimmed). campaign_idstring Yes The campaign whose knowledge base to use. Must belong to your workspace. conversation_idstring No Continue an existing conversation. Omit to start a new one.
curl -X POST "https://app.machfive.io/api/v1/agent/chat" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "What social proof should I use for SaaS founders?", "campaign_id": "campaign-uuid" }' { "conversation_id" : "conv_abc123" , "message" : { "role" : "assistant" , "content" : "For SaaS founders, lead with the Client X case study ..." }, "citations" : [ { "file_id" : "file_123" , "filename" : "Social Proof Ranker.pdf" } ] } Field Type Description conversation_idstring The conversation ID (reuse it to continue the thread). message.rolestring Always assistant. message.contentstring The assistant reply. citations[]array Knowledge-base sources referenced (may be empty). citations[].file_idstring | null Source file identifier (may be null). citations[].filenamestring | null Source file name (may be null).
Status Error Description 400 BAD_REQUEST Empty message or missing campaign_id. 401 UNAUTHORIZED Missing or invalid API key. 403 FORBIDDEN Key missing the agent:write scope. 404 NOT_FOUND Campaign (or supplied conversation_id) not found in this workspace. 409 NOT_READY The campaign has no knowledge base yet — generate the campaign first. 429 RATE_LIMITED Per-key rate limit exceeded.
GET /api/v1/conversations · scope agent:read
Workspace-scoped, newest activity first. Optional ?campaign_id filter.
Parameter Type Required Description campaign_idstring No Only conversations for this campaign. limitnumber No Max results (default 50, max 100). offsetnumber No Pagination offset (default 0).
{ "data" : [ { "id" : "conv_abc123" , "title" : "What social proof should I use ..." , "campaign_id" : "campaign-uuid" , "created_at" : "2026-06-14T12:00:00.000Z" , "last_message_at" : "2026-06-14T12:05:00.000Z" } ], "has_more" : false , "total" : 1 } Status Error Description 401 UNAUTHORIZED Missing or invalid API key. 403 FORBIDDEN Key missing the agent:read scope. 500 INTERNAL_ERROR Server error.
GET /api/v1/conversations/:id/messages · scope agent:read
Messages for a conversation, oldest first. The conversation must belong to your workspace.
Parameter Type Description idstring Conversation ID.
Parameter Type Required Description limitnumber No Max results (default 50, max 100). offsetnumber No Pagination offset (default 0).
{ "data" : [ { "role" : "user" , "content" : "What social proof should I use?" , "created_at" : "2026-06-14T12:00:00.000Z" }, { "role" : "assistant" , "content" : "For SaaS founders, lead with ..." , "created_at" : "2026-06-14T12:00:01.000Z" } ], "has_more" : false , "total" : 2 } Field Type Description data[].rolestring user or assistant.data[].contentstring Message text. data[].created_atstring | null Timestamp (ISO 8601).
Status Error Description 401 UNAUTHORIZED Missing or invalid API key. 403 FORBIDDEN Key missing the agent:read scope. 404 NOT_FOUND Conversation not found in this workspace.