Skip to main content

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.