Skip to main content

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​

File uploaded successfully, search task created