Skip to main content

​
Overview

The Chat API enables programmatic interaction with Helix AI. Send messages, receive responses, and build conversational experiences powered by Google Gemini AI. Base Endpoint: /v1/chat Required Scopes:
  • read:chat - Retrieve chat history
  • write:chat - Send messages

​
Send Message

Send a message to Helix AI and receive a response.

​
POST /v1/chat

curl https://api.branddna.app/v1/chat \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Write a LinkedIn post about brand archetypes",
    "analysis_id": "anl_abc123",
    "context": "Tech SaaS brand, Sage archetype"
  }'

​
Request Parameters

ParameterTypeRequiredDescription
messagestringYesUser message (max 2,000 chars)
analysis_idstringNoReference a specific analysis for context
thread_idstringNoContinue existing conversation thread
contextstringNoAdditional context (max 500 chars)
modelstringNopro or flash (default: pro for Pro/Agency)
temperaturefloatNo0.0-1.0 (default: 0.7, higher = more creative)

​
Response

{
  "data": {
    "id": "msg_xyz789",
    "thread_id": "thr_def456",
    "role": "assistant",
    "content": "Here's a LinkedIn post about brand archetypes:\n\n**The 12 Brand Archetypes...**",
    "created_at": "2026-01-27T14:23:45Z",
    "model": "gemini-pro",
    "tokens_used": 342
  }
}

​
Get Conversation Thread

Retrieve chat history for a thread.

​
GET /v1/chat/threads/:thread_id

curl https://api.branddna.app/v1/chat/threads/thr_def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "thread_id": "thr_def456",
    "analysis_id": "anl_abc123",
    "created_at": "2026-01-27T14:20:00Z",
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Write a LinkedIn post about brand archetypes",
        "created_at": "2026-01-27T14:20:15Z"
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "Here's a LinkedIn post...",
        "created_at": "2026-01-27T14:20:18Z",
        "tokens_used": 342
      }
    ]
  }
}

​
List Threads

Get all conversation threads.

​
GET /v1/chat/threads

curl "https://api.branddna.app/v1/chat/threads?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger20Results per page (max: 100)
analysis_idstring—Filter by analysis
created_afterstring—ISO 8601 date

​
Response

{
  "data": [
    {
      "thread_id": "thr_def456",
      "analysis_id": "anl_abc123",
      "message_count": 12,
      "last_message_at": "2026-01-27T14:23:45Z",
      "created_at": "2026-01-27T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

​
Delete Thread

Delete conversation thread and all messages.

​
DELETE /v1/chat/threads/:thread_id

curl https://api.branddna.app/v1/chat/threads/thr_def456 \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "thread_id": "thr_def456",
    "deleted": true
  }
}

​
Streaming Responses

Get real-time streaming responses (SSE):

​
POST /v1/chat/stream

curl https://api.branddna.app/v1/chat/stream \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Write a long blog post about SWOT analysis",
    "analysis_id": "anl_abc123"
  }'

​
Response (Server-Sent Events)

data: {"delta": "The", "done": false}

data: {"delta": " SWOT", "done": false}

data: {"delta": " analysis", "done": false}

...

data: {"delta": "", "done": true, "id": "msg_xyz789", "thread_id": "thr_def456"}

​
JavaScript Example

const EventSource = require('eventsource');

const url = 'https://api.branddna.app/v1/chat/stream';
const options = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Write a blog post about SWOT analysis'
  })
};

const eventSource = new EventSource(url, options);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.done) {
    console.log('\nComplete!');
    eventSource.close();
  } else {
    process.stdout.write(data.delta);
  }
};

​
Context-Aware Chat

Helix AI can reference analysis data for better responses:

​
With Analysis Context

curl https://api.branddna.app/v1/chat \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Write a headline for my homepage",
    "analysis_id": "anl_abc123"
  }'
Response: 
{
  "data": {
    "content": "Based on your Sage archetype and tech SaaS positioning: 'Data-Driven Brand Strategy in 60 Seconds, Not 6 Weeks'"
  }
}
Including analysis_id allows Helix to reference brand archetype, personas, and SWOT for tailored responses.

​
Use Cases

Chatbot Integration

Embed Helix AI in your application for brand consulting

Content Generation

Automate blog posts, social media, email copy

Strategy Refinement

Programmatically refine SWOT, personas, strategies

Batch Processing

Generate content for multiple clients overnight

​
Rate Limits

Chat API has message quotas:
TierMessages/HourConcurrent Threads
Pro30010
Agency1,00050
Token Limits:
  • Pro: 50,000 tokens/day
  • Agency: 200,000 tokens/day

​
Error Handling

​
400 Bad Request

{
  "error": "Validation error",
  "message": "Message is required",
  "details": {
    "field": "message",
    "code": "REQUIRED_FIELD"
  }
}

​
429 Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "message": "Maximum 300 messages per hour. Resets at 2026-01-27T15:00:00Z",
  "retry_after": 3600
}
Next: Competitor Tracking →