REST API

Authorization: Bearer sk_live_your_api_key_here

curl -X POST https://your-backend-url.onrender.com/v1/voices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -d '{
    "board": "my-product",
    "text": "The checkout flow is confusing and the confirmation email never arrives.",
    "sentiment": "problem",
    "context": { "source": "support_ticket", "ticket_id": "TK-4521" }
  }'

const response = await fetch('https://your-backend-url.onrender.com/v1/voices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_live_a1b2c3d4...'
  },
  body: JSON.stringify({
    board: 'my-product',
    text: 'The checkout flow is confusing and the confirmation email never arrives.',
    context: { page: window.location.href }
  })
});

const data = await response.json();
if (data.ok) {
  console.log('Submitted:', data.topicTitle);
}

{
  "ok": true,
  "board": "my-product",
  "voiceId": "a1b2c3d4-...",
  "topicId": "e5f6g7h8-...",
  "topicTitle": "Checkout flow is confusing",
  "topicSummary": "Users report the checkout process is unclear...",
  "topicSlug": "checkout-flow-is-confusing",
  "topicScore": 12,
  "isNewTopic": false,
  "voiceCount": 5,
  "topics": [ ... ]
}

{
  "board": "my-product",
  "text": "Checkout keeps failing when I try to use Apple Pay",
  "sentiment": "problem",
  "context": {
    "source": "error_monitoring",
    "error_code": "PAYMENT_TIMEOUT",
    "platform": "iOS",
    "app_version": "3.2.1",
    "error_rate": 0.124
  }
}

import requests

response = requests.post(
    'https://your-backend-url.onrender.com/v1/voices',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk_live_a1b2c3d4...'
    },
    json={
        'board': 'my-product',
        'text': 'Love the new dashboard redesign!',
        'sentiment': 'win',
        'context': {'source': 'app_store', 'rating': 5}
    }
)

data = response.json()
print(f"Topic: {data['topicTitle']} (score: {data['topicScore']})")

const response = await fetch('https://your-backend-url.onrender.com/v1/voices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_live_a1b2c3d4...'
  },
  body: JSON.stringify({
    board: 'my-product',
    text: 'The mobile app keeps crashing when I try to upload photos.',
    context: { source: 'zendesk', ticket_id: 'ZD-8842' }
  })
});

const { ok, topicTitle, isNewTopic, voiceCount } = await response.json();
console.log(`${isNewTopic ? 'New' : 'Existing'} topic: ${topicTitle} (${voiceCount} voices)`);

const reviews = [
  { text: 'Great app, love the speed!', rating: 5 },
  { text: 'Crashes every time I open settings', rating: 1 },
  { text: 'Decent but needs dark mode', rating: 3 },
];

for (const review of reviews) {
  const sentiment = review.rating >= 4 ? 'win'
    : review.rating <= 2 ? 'problem' : undefined;

  await fetch('https://your-backend-url.onrender.com/v1/voices', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer sk_live_a1b2c3d4...'
    },
    body: JSON.stringify({
      board: 'my-product',
      text: review.text,
      ...(sentiment && { sentiment }),
      context: { source: 'app_store', rating: review.rating }
    })
  });

  // Respect rate limits — space out bulk imports
  await new Promise(r => setTimeout(r, 2000));
}