Upload photo for face search
POST/search/upload
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.
Request
Responses
- 200
- 400
- 401
- 402
- 403
- 409
- 413
- 429
- 500
- 503
File uploaded successfully, search task created
Bad request
Unauthorized
Account search limit reached. Please buy a subscription to run a new search. Existing account search-limit outcome unchanged. For a new guest attempt after the per-session limit (2 for ios_app, 10 for web_guest by default, server-configurable), GeneralError.message is guest_search_limit. With App Attest on, also returned to an ios_app guest session that has not passed the proof. Previously accepted same-key retries and reads of owned searches remain available. Upload never deducts credits.
Web guest captcha refusal; GeneralError.message is captcha_required (a check is needed and no verified token was presented, including when the server's re-check at reservation finds a check newly needed) or captcha_failed (the token is rejected or longer than 4096 bytes). No Search is created.
App-session guest pending outcome. GeneralError.message is guest_attempt_pending (retryable unfinished attempt) or session_transition_pending (retryable verified-account handoff). An unfinished attempt cannot create a second accepted Search. For authenticated multipart upload, 409 also covers an unfinished account attempt, a same-account/key collision between multipart and direct upload, or replay of a soft-deleted accepted Search. A deleted Search keeps its key consumed; the response discloses no deleted Search data and creates no new reservation. Pending attempts may be retried with the same key.
Response Headers
Seconds to wait before retrying a pending attempt or transition.
App-session guest whole-request cap exceeded, including when the canonical request validator is the first body reader. No search is accepted or enqueued.
App-session guest admission rejected before reading the body. GeneralError.message is guest_admission_busy (process capacity) or guest_ip_limit (shared IP window).
Response Headers
Seconds before retrying.
Internal server error
Canonical session identity, transaction or admission storage unavailable. Guest requests fail closed instead of receiving a new session or quota. For authenticated multipart upload, infrastructure failure or an uncertain admission outcome also returns 503. Retry with the same account and Idempotency-Key; uncertainty must not create a second accepted Search. For a web guest start, GeneralError.message captcha_unavailable means the captcha verification or the pass record is unavailable; no Search is created.