Suggency API

Overview

Quickstart: https://api.suggency.com/v1/api

1. 1. Create an API key in your dashboard.
2. 2. Send it as a Bearer token.
3. 3. Call an endpoint — start with /stats (no parameters).

curl https://api.suggency.com/v1/api/stats \
  -H "Authorization: Bearer sgy_your_key_here"

const res = await fetch("https://api.suggency.com/v1/api/stats", {
  headers: { Authorization: "Bearer sgy_your_key_here" },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.suggency.com/v1/api/stats",
    headers={"Authorization": "Bearer sgy_your_key_here"},
)
print(res.json())

Authentication

API access is granted on approval — request it from your dashboard and, once approved, create a key. Every request needs an API key sent as a Bearer token. Keys are shown only once at creation — store them securely and never embed a key in client-side code.

Rotating keys

Create a new key, deploy it, then revoke the old one. You can hold up to 5 active keys, which is enough to rotate without downtime.

Rate limits

Each key is limited to 60 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds). A fixed window can allow a brief 2x burst at the boundary. On 429, honor Retry-After.

async function withRetry(url, opts, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, opts);
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get("Retry-After") ?? 1);
    // Honor Retry-After, add jitter. Never retry a 401.
    await new Promise((r) => setTimeout(r, (retryAfter * 1000) + Math.random() * 250));
  }
  throw new Error("rate limited");
}

import time, random, requests

def with_retry(url, headers, tries=4):
    for _ in range(tries):
        res = requests.get(url, headers=headers)
        if res.status_code != 429:
            return res
        retry_after = int(res.headers.get("Retry-After", "1"))
        time.sleep(retry_after + random.uniform(0, 0.25))
    raise RuntimeError("rate limited")

Need a higher limit? Email developers@suggency.com. Note: creating extra keys does not raise your limit.

Errors

Every error returns the same envelope. Codes are a closed set — safe to switch on.

Endpoints

{
  "bridges": 128,
  "suggestors": 54,
  "passes": 9203,
  "avg_score": 78.4
}

{
  "data": [
    {
      "id": "br_9xQ2",
      "slug": "best-mirrorless-camera",
      "title": "Best mirrorless camera for travel",
      "category": "tech",
      "published_at": "2026-06-30T10:00:00Z",
      "passes": 342,
      "score": 82,
      "suggestor": { "username": "oguz", "verified": true }
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wNi0zMHwx"
}

{
  "id": "br_9xQ2",
  "title": "Best mirrorless camera for travel",
  "suggestion": "The Sony a6700 hits the sweet spot…",
  "category": "tech",
  "domain": "sony.com",
  "passes": 342,
  "suggestor": { "username": "oguz", "verified": true }
}

{
  "username": "oguz",
  "display_name": "Oğuz",
  "verified": true,
  "total_passes": 5210,
  "bridge_count": 24,
  "bridges": [ { "slug": "best-mirrorless-camera", "passes": 342 } ]
}

{
  "username": "oguz",
  "total_passes": 5210,
  "bridge_count": 24
}

Playground

Versioning

The API is v1 (beta). We add fields without notice, so tolerate unknown fields. Breaking changes are announced in the Changelog with 90 days notice via Deprecation and Sunset headers.

Changelog

• 2026-07 · v1 (beta)

  Initial release: read-only public API, key management, rate limits, status page.