CommentTap public API

A REST API for your campaigns, leads, analytics, conversions and publications — built for Zapier, Make and custom integrations. Available on the Business plan and up.

Authentication

Create an API key in Settings → API keys and send it as a Bearer token with every request.

curl https://api-production-694d.up.railway.app/v1/campaigns \
  -H "Authorization: Bearer ct_your_api_key"

Keys are scoped per resource and shown only once at creation. Revoking a key blocks its requests immediately.

Scopes

Each key carries an explicit list of scopes. Requests outside the key's scopes return 403 insufficient_scope.

campaigns:readcampaigns:writeleads:readanalytics:readconversions:writepublications:readpublications:write

Endpoints

All endpoints live under /v1 and accept/return JSON.

GET/v1/campaignscampaigns:read

List campaigns in your workspace.

curl https://api-production-694d.up.railway.app/v1/campaigns \
  -H "Authorization: Bearer ct_..."

POST/v1/campaignscampaigns:write

Create a campaign. The same validation and plan limits as in the app apply.

curl -X POST https://api-production-694d.up.railway.app/v1/campaigns \
  -H "Authorization: Bearer ct_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Lead magnet","type":"comment_to_dm", ...}'

GET/v1/leadsleads:read

List captured leads. Paginated with a keyset cursor (limit + cursor).

curl "https://api-production-694d.up.railway.app/v1/leads?limit=50" \
  -H "Authorization: Bearer ct_..."

GET/v1/analytics/funnelanalytics:read

Funnel metrics (comments → DMs → clicks → leads) plus revenue when conversion tracking is on.

curl "https://api-production-694d.up.railway.app/v1/analytics/funnel?days=30" \
  -H "Authorization: Bearer ct_..."

POST/v1/conversionsconversions:write

Record a conversion. Pass externalId (e.g. an order id) for idempotency.

curl -X POST https://api-production-694d.up.railway.app/v1/conversions \
  -H "Authorization: Bearer ct_..." \
  -H "Content-Type: application/json" \
  -d '{"amountCents":4999,"currency":"USD","externalId":"order-1042","email":"customer@example.com"}'

GET/v1/publicationspublications:read

List Instagram publications created via CommentTap.

curl https://api-production-694d.up.railway.app/v1/publications \
  -H "Authorization: Bearer ct_..."

POST/v1/publicationspublications:write

Publish or schedule an Instagram post. Media types and scheduling follow your plan.

curl -X POST https://api-production-694d.up.railway.app/v1/publications \
  -H "Authorization: Bearer ct_..." \
  -H "Content-Type: application/json" \
  -d '{"socialAccountId":"...","mediaType":"IMAGE","caption":"New drop 🎉", ...}'

Responses & errors

List responses return { data, nextCursor }; pass nextCursor back as ?cursor= to fetch the next page (null means no more pages). Single objects return { data }.

{ "data": [ ... ], "nextCursor": "2026-08-01T10:00:00.000Z|9f1c..." }

Errors have a stable shape with a machine-readable code:

{ "error": { "code": "insufficient_scope", "message": "Forbidden" } }

Code	HTTP	Description
`unauthorized`	401	Missing, malformed, unknown or revoked API key.
`insufficient_scope`	403	The key does not include the scope required by this endpoint.
`api_access_requires_upgrade`	402	The workspace plan does not include API access (Business and up).
`validation_failed`	400	Request body or query failed validation — details lists the offending fields.
`rate_limited`	429	Too many requests — slow down and retry after a minute.
`not_found`	404	The resource does not exist in this workspace.
`internal_error`	500	Unexpected server error — safe to retry with backoff.

Feature-gated endpoints can return additional 402/403 codes taken from the specific gate, e.g. conversion_tracking_requires_upgrade or scheduling_locked — treat any unrecognized code on those statuses as a plan restriction.

Idempotency

POST /v1/conversions deduplicates on externalId: sending the same externalId twice returns { id: null, duplicate: true } instead of creating a second conversion. Use your order or booking id.

Rate limits

Requests are limited per key: 300/min on Business and 1000/min on Scale. Exceeding the limit returns 429 rate_limited.

Ready to build?

Create your first API key in the app and make your first request in minutes.

Open API keys