Katch Verified API

Overview

Getting started

Submit a creator handle for analysis, then retrieve brand-safety flags, traits, scores, sentiment, and stats. Analyses run asynchronously and complete typically within minutes; you are notified by a signed webhook and retrieve results by influencer_id.

Base URL

https://api.katchdata.com/v1/verified

Authentication

Partner credential in the Authorization header. No Bearer.

Versioning

Version in the path (/v1). Breaking changes ship a new version.

Authentication

Authorizing requests

Send the credential Katch supplies directly in the Authorization header:

Authorization: <partner credential>

Do not use Bearer

Send the raw credential — no Bearer prefix.

Do not use X-Api-Key

The credential goes in Authorization only.

Scoped to you

You can retrieve only influencers you submitted with this credential.

Status codes. A missing header returns 401; an invalid credential returns 403.

Endpoint

Start an analysis

POST/analyze

Start — or transparently reuse — an analysis for a handle on a platform.

Request body

Field	Req	Description
`handle`	yes	Account handle, with or without `@`. Max 255 chars.
`platform`	yes	`instagram`, `tiktok`, `youtube`, `facebook`, `linkedin`, or `x`.
`influencer_name`	opt	Display name. Defaults to the handle. Max 255.
`brand_name`	opt	Brand context. Max 255. Required to retrieve sentiment for that brand.
`limit`	opt	Post cap for the analysis. `1`–`5000`, default `50`. Controls how much history is analyzed (by post count, not date range).
`webhook_url`	opt	Public HTTPS completion endpoint. Max 2048. Must resolve to a public IP; no embedded credentials.

Request

curl --request POST \
  "https://api.katchdata.com/v1/verified/analyze" \
  --header "Authorization: $KATCH_VERIFIED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "handle": "creator_handle",
    "platform": "instagram",
    "brand_name": "Acme",
    "limit": 500,
    "webhook_url": "https://partner.example.com/hook"
  }'

Response · 200

{
  "influencer_id": 123,
  "influencer_name": "Creator Name",
  "parent_job_id": "123e4567-…-426614174000",
  "status": "queued"
}

Idempotent reuse. An equivalent active analysis is reused — status becomes already_queued with the existing parent_job_id. Persist influencer_id; it's how you retrieve results later.

Callback

Completion webhook

When an analysis completes, Katch sends a signed POST to your webhook_url.

Headers

Content-Type: application/json
X-Katch-Event: analysis_finished
X-Katch-Delivery: 123e4567-…-174000
X-Katch-Signature: sha256=<hex>

Body

{
  "type": "analysis_finished",
  "parent_job_id": "…174000",
  "influencer_id": 123,
  "has_errors": false,
  "count_total": 10,
  "count_success": 10,
  "count_fail": 0
}

Verify the signature (constant-time)

expected = "sha256=" + HMAC_SHA256( webhook_signing_secret, raw_body )

Acknowledge

Return 2xx. Failed deliveries retry up to 10 times.

Dedupe

The same event may arrive twice — dedupe on parent_job_id.

Partial results

If has_errors is true, fetch available results normally.

Endpoint

Retrieve results

GET/results

Retrieve results for an influencer you previously submitted. The view selects the projection.

flags

Flagged posts with red/yellow flag + explanation.

traits

Detected traits per post (flags without the flag).

score

Aggregate counts + ratios: safety, sales, quality.

sentiment

Per-brand sentiment (brands you submitted).

stats

Post totals, date span, platform count.

Query parameters

Parameter	Notes
`influencer_id`	ID returned by `/analyze`. Preferred. One identifier required.
`handle` + `platform`	Used when `influencer_id` is omitted. `platform` defaults to `instagram`.
`view`	`flags` · `traits` · `score` · `sentiment` · `stats`. Default `flags`.
`start_date` / `end_date`	Inclusive `YYYY-MM-DD` publication date filters.
`limit` / `offset`	Pagination for list views. `limit` 1–1000 (default 100); `offset` 0–1,000,000.

List views · flags/traits/sentiment

{
  "influencer_id": 123,
  "view": "flags",
  "count": 1,
  "rows": [ … ]
}

score

{
  "view": "score",
  "analyzed_posts": 50,
  "brand_safety": {"posts":4,"ratio":.08},
  "sales": {"posts":12,"ratio":.24},
  "video_quality": {"posts":39,"ratio":.78}
}

stats

{
  "view": "stats",
  "total_posts": 50,
  "earliest_post": "2025-01-15 09:30:00",
  "latest_post": "2026-07-01 18:22:10",
  "platform_count": 2,
  "sponsored_posts": 7
}

Field formats. ut_id is an integer; published, earliest_post, and latest_post are datetimes (YYYY-MM-DD HH:MM:SS); is_sponsored is a boolean.

Endpoint

List analyzed influencers

GET/influencers

List every influencer analyzed under your credential — the starting point for GET /results when you don't already hold an influencer_id. Credential-scoped: you see only your own.

Query parameters

Parameter	Notes
`limit`	Page size. Default `50`.
`offset`	Row offset for pagination. Default `0`.

Request

curl \
  --header "Authorization: $KATCH_VERIFIED_API_KEY" \
  "https://api.katchdata.com/v1/verified/influencers?limit=50&offset=0"

Response · 200

{
  "count": 2,
  "rows": [
    { "influencer_id": 298,
      "influencer_name": "Coco Lloyd",
      "created_at": "2026-07-30 04:12:08",
      "last_accessed_at": "2026-07-30 04:12:08" }
  ]
}

Auth behavior matches the rest of the API. A missing Authorization header returns 401; an invalid credential returns 403.

Reference

Errors & environments

Status codes

Code	Meaning
`400`	Invalid request.
`401`	Missing credential.
`403`	Invalid credential or access not allowed.
`404`	Influencer not found for your credential.
`429`	Rate limited — wait for `Retry-After`.
`500` / `502`	Transient — retry with backoff.

Handling & environments

Retries

Retry 500/502 with exponential backoff using the same body. Honor Retry-After on 429. Error bodies use {"error": "…"}.

Environment	Status
Production `api.katchdata.com/v1/verified`	Available
Sandbox	Planned

Getting started

Authorizing requests

The analysis lifecycle

Start an analysis

Request body

Completion webhook

Retrieve results

Query parameters

List analyzed influencers

Query parameters

Errors & environments

Status codes

Handling & environments