Stoked API

A read-only JSON API for pulling your community’s Stoked data into your own database, data warehouse, or internal tools.

This section is written for developers. If you just need a spreadsheet, the CSV exports in the admin portal (Exporting Conversations) need no code.

Version 1 is in early access. It covers Conversations and their messages, Advocates, Prospects, Custom Fields, Waivers, the Message Log, and the Reply Speed report.

Getting an API key

API keys are created by a community admin. Each key belongs to one community and can only read that community’s data.

1. In the admin portal, go to Settings > API Keys
2. Click New API key
3. Enter a Name that describes the integration that will use it, for example “ERP sync”
4. Under Permissions, check only what the integration needs — every permission is off by default
5. Click Create API key
6. Copy the key from the Your new API key box and store it somewhere safe, like a password manager or your secrets store

The key is shown once. Stoked stores only a hash of it, so nobody — including Stoked support — can show it to you again. If you lose it, revoke it and create a new one.

Create one key per integration so you can revoke them independently. The API Keys list shows each key’s permissions, who created it, and when it was last used.

• Edit permissions changes what a key can read without changing the key itself, so a running integration keeps working. When new endpoints ship, you check a box rather than rotating the key.
• Revoke stops a key working immediately and can’t be undone.

Authentication

Send the key as a Bearer token on every request:

Authorization: Bearer YOUR_API_KEY

Keys start with stk_live_. Treat a key like a password: keep it on your server, never in a browser, mobile app, or public repository.

A missing, mistyped, or revoked key returns 401:

{
  "errors": [
    {
      "status": "401",
      "title": "Unauthorized",
      "detail": "Invalid or missing API key."
    }
  ]
}

Permissions

A key can read only what it has been granted. A request to an endpoint the key lacks permission for returns 403, and the error names the missing permission.

A :pii permission adds attributes to an endpoint; it doesn’t open one. advocates:pii without advocates still returns 403. Without the :pii permission, personal attributes are left out of the response rather than set to null.

Records point to each other with links.related URLs — a conversation links to its advocate and prospect, for example. A link is a pointer, not a grant: following it with a key that lacks that endpoint’s permission returns 403.

Making requests

The base URL is:

https://integrations.stokedhq.com/api/v1

• Every endpoint is a GET. The API is read-only.
• Responses follow the JSON:API format with the media type application/vnd.api+json. Each record has a type, an id, its attributes, and relationships that point to other records by type and id.
• IDs are opaque strings. Store them as text, not numbers. They are case-insensitive: the API returns them in lower case, while CSV exports and admin portal URLs show the same ID in upper case. Compare them case-insensitively, and either case works in a URL or filter.
• Timestamps are ISO 8601 in UTC, to the whole second: 2026-09-06T17:30:00Z.
• Attributes with no value are null rather than missing. The one exception is personal data your key isn’t permitted to read, which is left out.

curl -G "https://integrations.stokedhq.com/api/v1/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json" \
  --data-urlencode "page[size]=100"

require "net/http"
require "json"

uri = URI("https://integrations.stokedhq.com/api/v1/conversations")
uri.query = URI.encode_www_form("page[size]" => "100")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Accept"] = "application/vnd.api+json"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
raise "HTTP #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

puts JSON.parse(response.body)["data"]

import requests

response = requests.get(
    "https://integrations.stokedhq.com/api/v1/conversations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/vnd.api+json",
    },
    params={"page[size]": "100"},
)
response.raise_for_status()

print(response.json()["data"])

using System.Net.Http.Headers;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
client.DefaultRequestHeaders.Accept.ParseAdd("application/vnd.api+json");

using var response = await client.GetAsync("https://integrations.stokedhq.com/api/v1/conversations?page[size]=100");
response.EnsureSuccessStatusCode();

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine(document.RootElement.GetProperty("data"));

const url = new URL("https://integrations.stokedhq.com/api/v1/conversations");
url.searchParams.set("page[size]", "100");

const response = await fetch(url, {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    Accept: "application/vnd.api+json",
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

const { data } = await response.json();
console.log(data);

Pagination

List endpoints return one page at a time. Request the first page and keep following links.next until it is null:

# Requires jq. Writes one JSON object per line to conversations.jsonl.
url="https://integrations.stokedhq.com/api/v1/conversations?page[size]=200"

while [ "$url" != "null" ]; do
  page=$(curl -sg "$url" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/vnd.api+json")

  echo "$page" | jq -c '.data[]' >> conversations.jsonl
  url=$(echo "$page" | jq -r '.links.next')
done

require "net/http"
require "json"

url = "https://integrations.stokedhq.com/api/v1/conversations?page[size]=200"
conversations = []

while url
  uri = URI(url)
  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer YOUR_API_KEY"
  request["Accept"] = "application/vnd.api+json"

  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
  raise "HTTP #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

  page = JSON.parse(response.body)
  conversations.concat(page["data"])
  url = page.dig("links", "next")
end

puts "Fetched #{conversations.size} conversations"

import requests

url = "https://integrations.stokedhq.com/api/v1/conversations?page[size]=200"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/vnd.api+json",
}
conversations = []

while url:
    response = requests.get(url, headers=headers)
    response.raise_for_status()

    page = response.json()
    conversations.extend(page["data"])
    url = page["links"]["next"]

print(f"Fetched {len(conversations)} conversations")

using System.Net.Http.Headers;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
client.DefaultRequestHeaders.Accept.ParseAdd("application/vnd.api+json");

string? url = "https://integrations.stokedhq.com/api/v1/conversations?page[size]=200";
var conversations = new List<JsonElement>();

while (url is not null)
{
    using var response = await client.GetAsync(url);
    response.EnsureSuccessStatusCode();

    using var page = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
    foreach (var item in page.RootElement.GetProperty("data").EnumerateArray())
    {
        conversations.Add(item.Clone());
    }

    url = page.RootElement.GetProperty("links").GetProperty("next").GetString();
}

Console.WriteLine($"Fetched {conversations.Count} conversations");

let url = "https://integrations.stokedhq.com/api/v1/conversations?page[size]=200";
const conversations = [];

while (url) {
  const response = await fetch(url, {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      Accept: "application/vnd.api+json",
    },
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

  const page = await response.json();
  conversations.push(...page.data);
  url = page.links.next;
}

console.log(`Fetched ${conversations.length} conversations`);

links.next always carries a page[after] cursor, whichever way you asked for the page. A cursor names the exact record the page ended on, so a record that changes while you are reading moves to the end of the list and is delivered later in the same run: nothing is skipped, and the run ends when next is null.

page[number] is for jumping to a page you can count to, for example to sample the data. Counting pages yourself is not safe for a full read, because a record that changes mid-run shifts the ones behind it across a page boundary.

Each list response includes:

• links — self, first, prev, next, and last URLs. next is null on the last page. On a page requested with page[after], prev and last are null.
• meta — page, per_page, total_count, and total_pages when the page was requested with page[number]; only per_page when it was requested with page[after], since no count is made. Some endpoints add their own meta keys on top of these, such as meta.close_reasons on conversations or meta.custom_fields on advocates — see the endpoint’s own page.

Syncing incrementally

Lists are returned in a fixed order: least recently updated first (updated_at ascending). Sorting is not configurable. Records that change move to the end of the list, so new activity always arrives last.

To keep your own copy up to date:

1. On the first run, follow links.next through everything and save each record, keyed by its id
2. Remember the newest updated_at you received
3. On the next run, pass that value as filter[updated_since] and follow links.next through the results
4. Insert or update each record by id

filter[updated_since] is inclusive, so you will receive the record at the boundary a second time. Updating by id makes the repeat harmless.

Follow links.next rather than counting pages: a record that changes while you are reading is delivered later in the same run instead of slipping between pages. See Pagination.

Each endpoint’s page lists what causes a record’s updated_at to change.

Matching the CSV exports

The admin portal’s CSV exports and the API describe the same records with a few differences in spelling. If you are moving from one to the other:

Errors

Errors use standard HTTP status codes and a JSON:API errors array. Each error has a status, a title, and a human-readable detail.

Unknown parameters are rejected rather than ignored, so a typo in a filter name fails loudly instead of quietly returning unfiltered data.

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Unknown filter[status] value(s): archived"
    }
  ]
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "This API key does not have the `conversations` permission."
    }
  ]
}

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Resource not found."
    }
  ]
}

Rate limits

Each key can make 120 requests per minute. Every response authenticated with an API key — including a 403 from a missing permission — carries two headers so you can pace yourself before you hit the limit:

(A 401 for a missing or invalid key carries neither — the limit is per key, and no key was identified.)

Beyond the limit, requests return 429 with a Retry-After header giving the number of seconds left in the current window.

At the maximum page size, 120 requests is 24,000 records per minute, so a well-behaved sync rarely reaches the limit. If yours does, wait for the Retry-After period and continue from the same URL.

There is also a per-IP-address backstop of 600 requests per minute across all keys. A single key can’t reach it; several keys or workers sharing one outbound address can. That 429 carries only Retry-After — the per-IP backstop isn’t tied to a single key, so it has no X-RateLimit-* headers to report.

Versioning and stability

The version is part of the URL (/api/v1). While v1 is in early access we may add endpoints, attributes, and filters at any time, so write your integration to ignore fields it doesn’t recognize. We’ll announce breaking changes in What’s New.

In this section

• Conversations API
• Advocates API
• Prospects API
• Custom Fields API
• Waivers API
• Message Log API
• Reply Speed API