Search
Face search: upload a photo, poll status, retrieve matches and results
📄️ Upload photo for face search
Sends the photo in this one multipart request. First-party web and app clients prefer the direct upload (POST /search/upload-grant, then POST /search/{searchId}/upload-complete) and use this operation only as a fallback: when the grant answers 503 upload_grants_disabled, or when the client cannot compute the SHA-256 that a grant requires. Clients authenticated by a bearer token alone use this operation, because a grant also requires a persisted session. App-session guests require an enabled server gate, canonical session cookie, valid app selector and UUID attempt key. The first durable starts per session (2 for ios_app and 10 for web_guest by default, server-configurable) use the same search payload and processing as accounts; the first durably accepted request under the canonical session and key defines the Search. An accepted same-key retry returns the existing Search regardless of replacement body, before body read, gate or quota checks, without another upload, enqueue or debit, even if new starts are disabled or exhausted. A different image under an accepted key does not conflict. An unfinished attempt remains retryable or pending and cannot create a second accepted Search. The selector is spoofable and never supplies ownership or credits. A denied new start, IP/process admission or accepted replay does not consume request bytes. Authenticated accounts may optionally supply Idempotency-Key. The normalized UUID is scoped to the authenticated account; normal account authentication is sufficient, with no additional session, cookie or app-selector requirement. The first durably accepted multipart request for that account and key defines the Search. An accepted same-key multipart retry returns the original Search regardless of replacement body, before reading the body or checking new-start quota, without another upload, enqueue, debit or reservation. Requests without a key retain existing account upload behavior. Multipart and direct-upload attempts share the account/key namespace: using the same key across those two modes returns 409 and never starts another Search. A soft-deleted accepted Search retains its consumed key; retries return 409 without disclosing the deleted Search or creating a new reservation. Unfinished attempts cannot create a second accepted Search. Infrastructure failure or uncertain admission returns 503; retry with the same key to recover the original outcome.
📄️ Prepare a direct-upload Search attempt
Preferred upload path for first-party clients: the photo goes to the image server instead of through this API. Off by default; available only where the server enables it. With the gate enabled, unconfigured signing, limits or store fail closed before admission. Existing bearer account authentication or canonical app-guest cookie plus valid app selector is required; an upload token never authenticates this API. Account issuance additionally requires a persisted canonical session whose stored verified account agrees with the presented account identity; bearer-only, unrelated or new session is insufficient. Guests retain the app selector and canonical guest ownership checks. Malformed UUID key or body constraints return 400; invalid owner or session returns 401. The first request freezes sizeBytes, sha256, owner and destination for one Search attempt. A retry with the same key and owner returns the same Search and reservation without another quota/IP start or lifetime extension; changed input under that key returns 409. A pending retry can refresh the upload-only token; accepted retries return the existing Search outcome with no token or expiry. Closed attempts cannot be reopened. This operation never receives the image or debits credits. The backend must verify actual stored bytes and image-safety limits before internal acceptance. A pending response names the backend-selected uploadUrl; after the image server stores the bytes the client calls POST /search/{searchId}/upload-complete. There is no separate refresh endpoint. When disabled, 503 has GeneralError.message upload_grants_disabled and has no grant-related side effects; the client then uploads through POST /search/upload, whose authentication, upload and retry semantics are unchanged.
📄️ Accept a directly uploaded original and start the Search
Completes a pending direct-upload attempt created by POST /search/upload-grant, off by default together with that operation. The caller must be the attempt owner under the same authentication rules as the grant (persisted canonical account session, or app guest with the valid app selector). The request has no body: the backend reads the original from its own image-server location, verifies the frozen size and sha256 plus image decode limits, and only the committed winner starts processing. Repeating the call after acceptance returns the same outcome without another reservation, charge or processing start. 409 upload_original_missing means the image server has no stored original yet (retry briefly, then upload again); 409 upload_original_invalid means the stored bytes can never be accepted (start a new attempt with a new Idempotency-Key); 409 upload_attempt_closed means the attempt is rejected, expired or deleted. When disabled, 503 has GeneralError.message upload_grants_disabled.
📄️ Get matches grouped by social network
Returns all groups with first page of matches for each group.
📄️ Get matches for specific social network group with pagination
Guest access to already accepted owned searches requires the valid app selector
📄️ Select matches and deduct credit
A guest has zero account credits: at paymentStage=selection, payment is required
📄️ Get full search results with unblurred profile information
Guest results require a current owning session and remain unpaid/blurred;
📄️ Get Social Profiler data for search
Returns the Social Profiler report for the search's selected matches. The report is built
📄️ Get Social Profiler status updates via Server-Sent Events (SSE)
Returns a continuous stream of server-sent events with Social Profiler report generation status updates.
📄️ Get search history
Returns paginated list of user's search history using cursor-based pagination.
📄️ Get signed profile image URL
Returns a signed URL for a social profile image by source and profile ID.
📄️ Get current search status
Get current search status
📄️ Get search status updates via Server-Sent Events (SSE)
Returns a continuous stream of server-sent events with search status updates.
📄️ Confirm age restriction consent
Confirms that the user has read the Terms of Service and agrees not to use the service
📄️ Get search details
Get search details
📄️ Delete search from history
Delete search from history