REST API Reference

Base URL

https://icecore.ai/api/v1

Authentication

All endpoints require an API key:

Authorization: Bearer sk_live_your_api_key_here

Conversations

List Conversations

GET /api/v1/conversations?page=1&limit=20&status=open
Authorization: Bearer sk_live_...

Query Parameters:

• page (optional): Page number, default 1

• limit (optional): Results per page, default 20, max 100

• status (optional): Filter by status - open, in_progress, closed

• channel (optional): Filter by channel - whatsapp, telegram, etc.

Response:

{
  "data": [
    {
      "_id": "conv_123",
      "status": "open",
      "channel": "whatsapp",
      "createdAt": "2025-10-30T10:00:00Z",
      "classification": {
        "category": "Support",
        "priority": "medium",
        "summary": "Customer needs help with order"
      },
      "user": "77001234567"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Messages

Send Message

POST /api/v1/messages/send
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "conversationId": "conv_123",
  "text": "Hello from API!"
}

Response:

{
  "success": true,
  "messageId": "msg_abc123",
  "sentAt": "2025-10-30T12:00:00Z"
}

Requirements:

• API key must have write or conversations permission

• Currently supports WhatsApp only

• Respects 24-hour messaging window

Analytics

Get Workspace Metrics

GET /api/v1/analytics?days=30&metric=total
Authorization: Bearer sk_live_...

Query Parameters:

• days (optional): Time period, default 30

• metric: Type of metrics - total, daily, by_category

Metric Types

1. Total Summary (Default)

When metric=total or no metric is specified, the response includes:

• Overall conversation count

• Breakdown by status

• Breakdown by channel

GET /api/v1/analytics?metric=total&days=30

Response:

{
  "period": {
    "days": 30,
    "start": "2025-10-01T00:00:00Z",
    "end": "2025-10-30T23:59:59Z"
  },
  "metrics": {
    "total": 1247,
    "by_status": [
      {"status": "open", "count": 89},
      {"status": "in_progress", "count": 156},
      {"status": "closed", "count": 1002}
    ],
    "by_channel": [
      {"channel": "whatsapp", "count": 850},
      {"channel": "telegram", "count": 397}
    ]
  }
}

Note: The by_status and by_channel arrays are always included in the total summary response.

2. Daily Breakdown

GET /api/v1/analytics?metric=daily&days=30

Response:

{
  "daily": [
    {"date": "2025-10-01", "count": 42},
    {"date": "2025-10-02", "count": 38},
    {"date": "2025-10-03", "count": 51}
  ]
}

3. By Category

GET /api/v1/analytics?metric=by_category&days=30

Response:

{
  "categories": [
    {"category": "Support", "count": 580},
    {"category": "Sales", "count": 320},
    {"category": "Complaint", "count": 150}
  ]
}

Rate Limits

Rate limits are per API key:

Headers in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1635724800

When exceeded:

HTTP 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "retry_after": 30
}

Error Responses

401 Unauthorized

{
  "error": "Invalid or expired API key"
}

403 Forbidden

{
  "error": "API key does not have permission to read conversations"
}

404 Not Found

{
  "error": "Conversation not found"
}

500 Server Error

{
  "error": "Internal server error"
}

Pagination

All list endpoints support pagination:

GET /api/v1/conversations?page=2&limit=50

Response includes:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 1247,
    "pages": 25
  }
}

Best Practices

1. Cache responses: Use ETag headers when available

2. Handle rate limits: Implement exponential backoff

3. Paginate efficiently: Don't fetch all data at once

4. Use webhooks: Better than polling for real-time data

5. Error handling: Retry 5xx errors, don't retry 4xx errors

SDK Examples

JavaScript/Node.js

const IceCore = require('icecore-api');

const client = new IceCore('sk_live_your_key');

// Get conversations
const conversations = await client.conversations.list({
  status: 'open',
  limit: 50
});

// Send message
await client.messages.send({
  conversationId: 'conv_123',
  text: 'Hello!'
});

// Get analytics
const metrics = await client.analytics.get({
  days: 30,
  metric: 'total'
});

Python

from icecore import IceCore

client = IceCore(api_key='sk_live_your_key')

# Get conversations
conversations = client.conversations.list(
    status='open',
    limit=50
)

# Send message
client.messages.send(
    conversation_id='conv_123',
    text='Hello!'
)

# Get analytics
metrics = client.analytics.get(
    days=30,
    metric='total'
)

See Also:

• Authentication Guide

• Webhooks