TrendWatch API

Beta limitations

Except for starting AI analysis, the published API v1 endpoints are read-only. There are currently no API endpoints for:

• Adding, editing, pausing or removing tracked Instagram and TikTok accounts.
• Submitting a new video by URL.
• Changing a video's production status or its position on the Kanban board.

Quickstart

Create a key on your Account page, then check that it works. /me costs nothing and returns your plan and credit balance.

export TWA_KEY="twa_..."

curl -s "https://server.trndwtch.com/api/v1/me" \
  -H "Authorization: Bearer $TWA_KEY"

Then list your ten most recently collected videos:

curl -s "https://server.trndwtch.com/api/v1/videos?sort_by=created_at&order=desc&limit=10" \
  -H "Authorization: Bearer $TWA_KEY"

The same call in JavaScript and Python:

const res = await fetch(
  "https://server.trndwtch.com/api/v1/videos?sort_by=created_at&order=desc&limit=10",
  { headers: { Authorization: `Bearer ${process.env.TWA_KEY}` } },
);
if (!res.ok) throw new Error((await res.json()).message);
const { data, total_count, has_more } = await res.json();

import os, requests

r = requests.get(
    "https://server.trndwtch.com/api/v1/videos",
    params={"sort_by": "created_at", "order": "desc", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['TWA_KEY']}"},
    timeout=30,
)
r.raise_for_status()
payload = r.json()

Starter prompt for Claude Code or Codex

After saving your API key in the TWA_KEY environment variable, paste this prompt into Claude Code or Codex:

Use the TrendWatch REST API at https://server.trndwtch.com/api/v1.

Read the API key from the TWA_KEY environment variable. Never print or expose the key.
1. Call GET /me with the Authorization: Bearer $TWA_KEY header to verify authentication.
2. Call GET /videos?sort_by=created_at&order=desc&limit=5 with the same header.
3. Show the five most recently collected videos in a compact table with account name, caption, platform_url, views, likes, comments, and posted_at.
If a request fails, show the HTTP status and API error message without exposing the key.

Authentication

Every request carries a bearer token: an API key created on the Account page. Keys start with twa_ and are shown exactly once at creation; only a SHA-256 hash is stored, so a lost key cannot be recovered, only replaced.

Authorization: Bearer twa_<your key>

You can hold up to five active keys and revoke any of them instantly. A key acts strictly as its owner: it reads that account's data and spends that account's credits, and it can never reach another user's workspace.

The key's owner must be on an active paid plan. The check runs on every request, so a key created while subscribed stops working — with 403 and data.code: PLAN_REQUIRED — if the subscription lapses, and starts working again after an upgrade. No key is revoked in the process.

Conventions

• Every successful response wraps its payload in data.
• Listing endpoints add page, limit, total_count and has_more next to data. /accounts is unpaginated and returns everything, so its total_count equals the array length.
• Timestamps are ISO 8601 in UTC. Date filters take YYYY-MM-DD.
• Fields the platform never reported come back as null rather than being omitted, except the long text fields on the video detail endpoint, which are absent unless requested with include.
• Videos come from two sources that share one id space: accounts (collected from a connected account) and submitted (added by URL). Detail and analysis endpoints accept an id from either and report which one it was in source.

Metrics

Two of the numbers on every collected video compare it against its own account's norm rather than against the platform. That is what makes a 5k-follower account and a 5M-follower account directly comparable.

The breakout videos of every account you track, best first:

curl -s "https://server.trndwtch.com/api/v1/videos?min_outlier_score=3&sort_by=outlier_score&order=desc" \
  -H "Authorization: Bearer $TWA_KEY"

All scores are null until the account has enough collected videos to have a norm.

Errors

Errors use standard HTTP status codes. The enumerated API failures below carry a stable data.code; match on that code because the human-readable message may be reworded. Validation failures return data.errors instead.

{
  "message": "This API key has been revoked.",
  "data": { "code": "REVOKED_API_KEY" }
}

The same envelope carries every other failure. Running out of credits while starting an analysis, for example, answers 402 with:

{
  "message": "No credits left for this billing period.",
  "data": { "code": "INSUFFICIENT_CREDITS" }
}

Status codes

Rate limits

200 requests per minute per API key, plus a 1000 per minute ceiling per IP address applied before the key is looked up. Both windows are one minute and report their state in the standard RateLimit response headers. Exceeding either returns 429.

OpenAPI spec

The full contract is published as OpenAPI 3.1 at https://server.trndwtch.com/api/v1/openapi.json. It needs no authentication, so you can import it into Postman, Insomnia or Bruno, or generate a typed client before you have a key.

npx @openapitools/openapi-generator-cli generate \
  -i https://server.trndwtch.com/api/v1/openapi.json \
  -g typescript-fetch -o ./trendwatch-client

Security

• An API key grants read access to your whole workspace and the ability to spend your credits on analysis. Treat it like a password: keep it in an environment variable or a secret manager, never in client-side code or a public repository.
• Revoke a key the moment you suspect it leaked; revocation takes effect immediately. Each key shows a last-used timestamp on the Account page, which is the only leak signal available.
• Captions, transcripts and scripts returned by the API are third-party or user-generated content. If you pass them to an LLM, treat them as data, never as instructions.
• No endpoint deletes anything, and no endpoint can reach another user's data; every query is scoped to the key's owner in the database.

MCP server

The same data is available to AI agents over MCP at POST https://server.trndwtch.com/mcp (streamable HTTP, stateless), using the same bearer token. Five tools: trendwatch_list_accounts, trendwatch_search_videos, trendwatch_get_video, trendwatch_run_ai_analysis (spends one credit, flagged destructive) and trendwatch_get_usage.

claude mcp add --transport http trendwatch https://server.trndwtch.com/mcp \
  --header "Authorization: Bearer twa_..."

ChatGPT developer mode: Settings → Connectors → Advanced → Developer mode, add https://server.trndwtch.com/mcp with auth type API key and the twa_… value.