Quickstart

Five minutes from curl to a real intelligence_discover result. Pick any HTTP client you like; we use curl here.

Prerequisites

$
export API_BASE="https://api.kinetk.ai/graph"
$
export API_KEY="<paste your key here>"

If you don’t have a key yet, see Authentication. The production base URL is https://api.kinetk.ai/graph — see Introduction.

1. Health check

$
curl -H "x-api-key: $API_KEY" "$API_BASE/health"

Expected response (status 200, latency under 1 second):

1
{
2
  "ok": true,
3
  "lastSyncedAt": "2026-04-28T17:32:11.000Z",
4
  "syncFreshSeconds": 1432
5
}

syncFreshSeconds tells you how recently the ingestion pipeline ran. Under 3600 (one hour) means data is fresh. Much higher and the hourly sync is lagging — see Sync & Freshness.

If you get 403 { "message": "Forbidden" }, the API key isn’t being sent — check the header name and value.

2. Trending narratives (precomputed read)

$
curl -H "x-api-key: $API_KEY" \
>
  "$API_BASE/narratives/trending?window=7d&limit=10"

Sub-second response with the top 10 trending narrative clusters in the last 7 days:

1
{
2
  "window": "7d",
3
  "narratives": [
4
    {
5
      "id": "1234",
6
      "label": "Smartwatch fitness accountability",
7
      "summary": "Creators in the smartwatch + fitness space leaning into community accountability framing...",
8
      "window": "7d",
9
      "trendScore": 0.82,
10
      "momentumScore": 0.74,
11
      "topTags": ["smartwatch", "fitness"],
12
      "contentCount": 28,
13
      "creatorCount": 16,
14
      "totalEngagement": 1240501
15
    }
16
  ]
17
}

Windows: 24h | 7d | 30d. Limit: 1–50.

3. Submit an async intelligence job

The retrieval / discovery / brief / context kinds all run async because they can take 5–20 seconds. Submit returns immediately with a jobId:

$
curl -X POST "$API_BASE/intelligence/jobs" \
>
  -H "x-api-key: $API_KEY" \
>
  -H "content-type: application/json" \
>
  -d '{
>
    "kind": "intelligence_discover",
>
    "input": {
>
      "query": "smart watch launch",
>
      "platforms": ["TIKTOK", "INSTAGRAM"],
>
      "limit": 1000,
>
      "window": "7d"
>
    }
>
  }'

Three possible responses:

1
// Fresh submit — new work queued:
2
{ "jobId": "0190bd6f-...", "status": "queued", "statusUrl": "/intelligence/jobs/0190bd6f-..." }
3
4
// Cache hit — identical input within freshness window, inline result:
5
{ "jobId": "0190bd6f-...", "status": "succeeded", "result": { /* full payload */ }, "fromCache": true }
6
7
// Dedup — identical input already running, same jobId returned:
8
{ "jobId": "0190bd6f-...", "status": "queued", "dedup": true, "statusUrl": "/intelligence/jobs/0190bd6f-..." }

Save the jobId:

$
JOB="0190bd6f-..."

4. Poll for the result

$
curl -H "x-api-key: $API_KEY" "$API_BASE/intelligence/jobs/$JOB"

Poll every 2–5 seconds until status flips from queued → running → succeeded. Typical end-to-end time for intelligence_discover: 5–20 seconds.

1
// While running:
2
{ "jobId": "0190bd6f-...", "kind": "intelligence_discover", "status": "running", "submittedAt": 1745859300000, "startedAt": 1745859302100 }
3
4
// When done:
5
{
6
  "jobId": "0190bd6f-...",
7
  "kind": "intelligence_discover",
8
  "status": "succeeded",
9
  "submittedAt": 1745859300000,
10
  "startedAt":   1745859302100,
11
  "completedAt": 1745859315400,
12
  "result": { /* QueryNarrativeDiscoveryResponse — see API reference */ }
13
}

5. Skip the polling — use the MCP

If you’d rather have Claude or Cursor handle the submit/poll loop for you, install the kinetk MCP server — see MCP Installation. The MCP exposes the same intelligence_discover flow as a one-tool call with built-in polling and a slim, token-efficient response envelope.

Next steps

• Intelligence Jobs — the full async lifecycle, all four kind values, dedup + cache semantics.
• Narrative Intelligence — what intelligence_discover actually returns and how to read it.
• API Reference — every endpoint, every field, every error shape.