Happenstance API

Process-liveness only — no DB or internal-api dependency. Used by the ECS/ALB health checks: blob ingest must keep accepting Meta deliveries even when a downstream dependency blips (a drained target pauses the Meta-side job).

Search for people within specified groups and/or within a user's connections. Use @mentions in your search query to filter results to a specific person's connections (e.g., "engineers @Jane Smith knows"). Use the /v1/groups/{group_id} endpoint to look up member names for @mentions. Requires sufficient credits. Returns 402 Payment Required if not enough credits. Returns 429 Too Many Requests if you have 10 or more search requests currently running.

Get search results. Returns the status and results of a search request. Optionally provide a page_id to retrieve a specific page of results.

Find more results for a search. Creates a new search that excludes all people from previous results in the search chain. Uses the same query and settings as the original search. Can only be called on the parent search (searches without a parent_search_id). Requires sufficient credits. Returns 402 Payment Required if not enough credits. Returns 429 Too Many Requests if you have 10 or more search requests currently running.

Start a new person research request. Include as many details as possible about the person in the description field (full name, company, title, location, social media handles, etc.) for best results. Requires sufficient credits. Returns 402 Payment Required if not enough credits. Returns 429 Too Many Requests if you have 10 or more research requests currently running.

Get the status of a research request.

Get the current user's profile.

Get details of a specific group including its members. Member names can be used as @mentions in search queries to filter results to that person's connections (e.g., "engineers @Jane Smith knows").

Get credit balance, purchase history, usage history, and Auto Reload settings for the authenticated user.

OAuth 2.0 Authorization endpoint. Meta redirects the user here. We validate the request, then redirect to a consent page where the user authenticates (via Clerk) and grants access.

Complete the authorization flow after user consent. Called by the frontend after Clerk authentication + user consent. The user_id is derived from the authenticated session, not the request body.

OAuth 2.0 Token endpoint. Supports two grant types: - authorization_code: exchange an auth code for access + refresh tokens - refresh_token: exchange a refresh token for a new access token

OAuth 2.0 Token Revocation endpoint. Meta calls this (POST with Authorization: Bearer <token>) when all transfers for a user are complete. Revokes the token's whole grant: the refresh token and every access token issued under it.

Import Calendar or CalendarEvent items from Meta DTP.

Import Folder or File (archive) items from Meta DTP.

Import Album, Photo, or Video items from Meta DTP.

Import SocialActivity items from Meta DTP.