Public API

REST, JSON, read-only. For workspaces on the Pro plan only.

Authentication

1. Open Settings → API (a tab in the Settings menu; requires Manage API keys access) and click Create key. Keys start with smt_live_ and are shown only once; store yours in your system's secret manager.
2. Send it with every request: Authorization: Bearer smt_live_…
3. Keys can be revoked at any time; requests with a revoked key get 401.

export SOCIOMILE_API_KEY="smt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Limits

• 60 requests per minute per key. The X-RateLimit-Limit and X-RateLimit-Remaining headers are included in every response; going over the limit returns 429 with a Retry-After header.
• Lists are split into pages of 50 items (?page=2, etc.). Check meta.has_more.
• Times use ISO 8601 with offset +07:00. Durations are in seconds.
• Free workspaces, or Pro workspaces whose plan has ended, get 402 plan_required.

Endpoints

GET /api/v1/conversations

List of conversations, newest first. Optional filters: status (open, replied, solved, closed), channel (Threads account ID), type (reply, mention), from & to (creation date, YYYY-MM-DD), page.

curl -s "https://threads.sociomile.net/api/v1/conversations?status=open&page=1" \
  -H "Authorization: Bearer $SOCIOMILE_API_KEY"

{
  "data": [
    {
      "id": 1042,
      "channel": {"id": 3, "username": "tokobudi"},
      "type": "reply",
      "status": "open",
      "contact": {"username": "customer.one"},
      "category": "Stock question",
      "labels": ["Important"],
      "tags": ["promo"],
      "assignee": "Rina",
      "first_response_secs": null,
      "reopened_count": 0,
      "tickets": [],
      "created_at": "2026-10-07T10:00:00+07:00",
      "last_message_at": "2026-10-07T10:00:00+07:00",
      "solved_at": null,
      "closed_at": null
    }
  ],
  "meta": {"page": 1, "per_page": 50, "total": 1, "has_more": false}
}

GET /api/v1/conversations/{id}

One full conversation: messages (incoming/outgoing, send status, attachments), labels, tags, category, internal notes, tickets.

curl -s "https://threads.sociomile.net/api/v1/conversations/1042" \
  -H "Authorization: Bearer $SOCIOMILE_API_KEY"

{
  "data": {
    "id": 1042,
    "…": "same fields as the list",
    "context": {"text": "End-of-month promo…", "username": "tokobudi", "permalink": "https://www.threads.com/…"},
    "messages": [
      {"id": 1, "direction": "in", "author": "customer.one", "text": "Do you still have size L?", "media_type": "TEXT_POST",
       "attachments": [], "status": "received", "permalink": "https://www.threads.com/…", "posted_at": "2026-10-07T10:00:00+07:00"},
      {"id": 2, "direction": "out", "author": "Rina", "text": "Yes, still in stock.", "media_type": "TEXT_POST",
       "attachments": [], "status": "published", "permalink": "https://www.threads.com/…", "posted_at": "2026-10-07T10:05:00+07:00"}
    ],
    "notes": [{"body": "Ship today", "author": "Rina", "source": "manual", "ticket": null, "created_at": "…"}]
  }
}

GET /api/v1/tickets

List of tickets, highest number first. Optional filters: status (open, in_progress, waiting, resolved, closed), page.

curl -s "https://threads.sociomile.net/api/v1/tickets?status=open" \
  -H "Authorization: Bearer $SOCIOMILE_API_KEY"

{
  "data": [
    {"number": 12, "code": "TKT-000012", "subject": "Check stock", "status": "open", "priority": "high", "conversation_id": 1042,
     "assignees": ["Tari"], "due_at": null, "created_at": "…", "resolved_at": null, "closed_at": null}
  ],
  "meta": {"page": 1, "per_page": 50, "total": 1, "has_more": false}
}

GET /api/v1/tickets/{number}

One ticket with its description and discussion. {number} can be the number (12) or the full code (TKT-000012).

curl -s "https://threads.sociomile.net/api/v1/tickets/TKT-000012" \
  -H "Authorization: Bearer $SOCIOMILE_API_KEY"

GET /api/v1/reports/summary

Key numbers, using the same formulas as Dashboard & Reports (Report formulas). Optional filters: from, to (default: the last 7 days), channel (ID, several allowed: channel=1,2), type.

curl -s "https://threads.sociomile.net/api/v1/reports/summary?from=2026-10-01&to=2026-10-08" \
  -H "Authorization: Bearer $SOCIOMILE_API_KEY"

{
  "data": {
    "conversations": 5, "messages_in": 7, "replies_sent": 5, "replied": 3, "backlog": 3,
    "solved": 1, "closed": 1, "escalated": 1, "reopened": 1,
    "response_rate": 60, "solved_rate": 20, "escalation_rate": 20, "reopen_rate": 20,
    "avg_frt_seconds": 700, "median_frt_seconds": 600,
    "avg_resolution_seconds": 7200, "median_resolution_seconds": 7200,
    "tickets": {"total": 1, "open": 0, "done": 1, "avg_resolve_seconds": 7200}
  },
  "filters": {"from": "2026-10-01", "to": "2026-10-07", "channels": null, "type": null}
}

Error codes

All errors have the form {"error": {"code": "…", "message": "…"}}.