SnitchFeed API: endpoints, base URL, errors

The SnitchFeed REST API does two things:

• Reads your organization's data (your workspace): mentions, listeners, feeds, Brand Context and credit usage, and lets you mark mentions seen or engaged.
• Searches public posts on LinkedIn, X (Twitter) and Hacker News, and fetches LinkedIn company pages, person posts and comments, and post comment or reaction scrapes. These calls spend credits.

Endpoints

Your organization's data

These endpoints do not consume credits.

Public social search

Every POST /v1/data/* call costs credits, charged only when it succeeds. Costs per endpoint and what happens when you run out are on API credits. LinkedIn search, person posts and person comments always return the full page.

Mentions, listeners and feeds use prefixed public IDs (men_..., lis_..., svw_...) rather than sequential numbers.

The endpoint reference pages in this section list every parameter and response field. The machine-readable spec is at GET https://api.snitchfeed.com/v1/openapi.json.

Base URL

https://api.snitchfeed.com/v1

Paths above include /v1. For example: POST https://api.snitchfeed.com/v1/data/twitter/tweets/search.

Authentication

Send Authorization: Bearer <token> on every request. The token is either an API key (sf_api_...) for your own organization or an OAuth access token for an integration other customers install. See Authentication and OAuth.

Mention state

Every mention carries a state object: seen, lastSeenAt, firstSeenAt, engaged, engagedAt and archived. State is shared across the whole organization, like read and unread in an inbox. Filter GET /v1/mentions and GET /v1/mentions/count with seen=true|false and engaged=true|false.

PATCH /v1/mentions/{id}/state takes seen and/or engaged (booleans; at least one is required) and an optional occurredAt. Fields you leave out are unchanged. Setting engaged: true also marks the mention seen; engaged: false does not change whether it is seen.

{ "seen": true, "engaged": true, "occurredAt": "2026-01-15T10:30:00Z" }

This endpoint needs both the mentions:read and mentions:write scopes and does not consume credits. occurredAt is an ISO 8601 time for when the change happened. It defaults to now and must not be in the future.

The current value of each dimension (seen, engaged) comes from the event with the latest occurredAt. An event older than the current latest one is recorded but does not change the state. The response returns the mention with its resulting state.

Each change is attributed to your API key or OAuth app, acting for the user who owns it, and shows up that way in the app. Archiving and unarchiving are not available through the API. State changes are not pushed to you, so fetch a mention again to see changes made in the app.

Pagination

Each endpoint family paginates differently:

Response format

All responses are JSON and include a requestId. Successful responses use 2xx status codes. Errors use this envelope:

{
  "requestId": "01HXYZABCDEF",
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key."
  }
}

Validation errors add an issues array of { path, message }. Rate limit errors add error.retryAfter (seconds) and a matching Retry-After header.

Error codes

Failed requests are not charged credits. Out-of-credit responses differ by endpoint; API credits has the full list.

Rate limits

Limits apply per organization: 20 requests per minute per search surface (X, LinkedIn, Hacker News), 60 per minute shared by the organization data endpoints, and at most 2 in-flight requests across all v1 endpoints. See Rate limits.

Request history

Open Integrations → API in the app (app.snitchfeed.com/integrations/api) and select the Usage tab to see recent API requests from your organization: time, key, user, route, status, HTTP code and duration. Expand a row for details. The tab needs a plan that includes API access.

Related

• API authentication: create an API key and send it
• API scopes and permissions: which scope each endpoint needs
• API credits: what each search endpoint costs
• Webhook events, retries and delivery limits: get new mentions pushed to you
• SnitchFeed MCP server: use SnitchFeed from an AI client instead