Skip to main content

​
Catch The Good Ones API

The Catch The Good Ones API lets you programmatically manage your tracked accounts, trigger syncs, configure searches, and access the people who have recently followed, liked, or engaged with your tracked social media accounts. Use it to pipe your People of Interest into tools like Zapier, Make, n8n, or your own applications.

​
Base URL

https://www.catchthegoodones.com/api/v1

​
Quick start

  1. Generate an API key from your API Key page
  2. Make a request with your key in the Authorization header
curl https://www.catchthegoodones.com/api/v1/people-of-interest \
  -H "Authorization: Bearer ctgo_your_api_key_here"

​
Available endpoints

​
Account & Auth

MethodEndpointDescription
GET/api/v1/meTest your API key and get account info

​
Tracked Accounts

MethodEndpointDescription
GET/api/v1/tracked-accountsList all tracked X accounts
POST/api/v1/tracked-accountsAdd a new X account to track
PUT/api/v1/tracked-accounts/:idWake a sleeping account
DELETE/api/v1/tracked-accounts/:idPut an account to sleep
PATCH/api/v1/tracked-accounts/:idAssign a saved search to an account
POST/api/v1/tracked-accounts/:id/change-tierChange an account’s tier

​
Saved Searches

MethodEndpointDescription
GET/api/v1/saved-searchesList all saved searches
POST/api/v1/saved-searchesCreate a new saved search
GET/api/v1/saved-searches/:idGet a single saved search
PUT/api/v1/saved-searches/:idUpdate a saved search
DELETE/api/v1/saved-searches/:idDelete a saved search

​
Sync

MethodEndpointDescription
POST/api/v1/syncTrigger a discovery sync
GET/api/v1/sync-status?syncRunId=XCheck sync progress
GET/api/v1/sync-historyView past sync runs
GET/api/v1/sync-settingsGet per-tier sync schedules
PUT/api/v1/sync-settingsUpdate timezone and sync times

​
Explore

MethodEndpointDescription
POST/api/v1/exploreRun an explore pass against cached profiles
GET/api/v1/explore/budgetCheck remaining explore budget

​
People of Interest

MethodEndpointDescription
GET/api/v1/people-of-interestRetrieve discovered people of interest

​
Feedback

MethodEndpointDescription
GET/api/v1/feedbackList all feedback
POST/api/v1/feedbackSubmit Good One / Bad One feedback
DELETE/api/v1/feedbackRemove feedback (undo a rating)

​
DM Templates

MethodEndpointDescription
GET/api/v1/dm-templatesList all DM templates
POST/api/v1/dm-templatesCreate a new DM template
GET/api/v1/dm-templates/:idGet a single DM template
PUT/api/v1/dm-templates/:idUpdate a DM template
DELETE/api/v1/dm-templates/:idDelete a DM template

​
Notification Settings

MethodEndpointDescription
GET/api/v1/notification-settingsGet notification preferences
PUT/api/v1/notification-settingsUpdate notification preferences

​
Webhooks

MethodEndpointDescription
POST/api/v1/webhooks/subscribeRegister a webhook URL (for Zapier)
DELETE/api/v1/webhooks/subscribeUnregister a webhook URL

​
Async operations

Some operations run asynchronously and return a run ID for polling:
  • Sync (POST /api/v1/sync) returns { syncRunId } - poll with GET /api/v1/sync-status?syncRunId=X
  • Explore (POST /api/v1/explore) returns { runId } - poll with GET /api/v1/sync-status?syncRunId=X

​
Billing effects

Several endpoints affect your Stripe subscription:
  • Adding a tracked account (POST /api/v1/tracked-accounts) increments subscription quantity
  • Sleeping an account (DELETE /api/v1/tracked-accounts/:id) decrements subscription quantity
  • Waking an account (PUT /api/v1/tracked-accounts/:id) increments subscription quantity
  • Changing tier (POST /api/v1/tracked-accounts/:id/change-tier) adjusts subscription with proration (upgrades) or schedules a change (downgrades)

​
Zapier integration

Catch The Good Ones has a native Zapier app. Search for “Catch The Good Ones” in Zapier to set up automated workflows when new people of interest are discovered.

​
Rate limits

All API endpoints are rate limited to 60 requests per minute per API key. Rate limit status is returned in response headers:
HeaderDescription
X-RateLimit-LimitMaximum requests per window (60)
X-RateLimit-RemainingRequests remaining in current window
Retry-AfterSeconds until the window resets (only on 429)

​
Errors

The API returns standard HTTP status codes:
StatusDescription
200Success
201Created
400Invalid request (bad parameters or body)
401Missing, invalid, or revoked API key
403Forbidden (subscription required, limit reached, etc.)
404Resource not found
409Conflict (duplicate resource)
422Unprocessable (e.g. private account)
429Rate limit exceeded
502Upstream error (Stripe, etc.)
503Service temporarily unavailable