Prepare a direct-upload Search attempt
POST/search/upload-grant
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.
Request
Responses
- 200
- 400
- 401
- 402
- 403
- 409
- 429
- 500
- 503
Pending capability or already accepted Search outcome
Bad request
Unauthorized
Guest or account quota denied without another reservation. With App Attest on, also returned to an ios_app guest session that has not passed the proof.
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 reservation is made.
Frozen-input conflict or closed attempt; no authorization is issued.
Existing IP or process admission refusal; no Search is started.
Internal server error
Disabled (upload_grants_disabled), unconfigured enabled state or unavailable canonical store. For a web guest start, captcha_unavailable means the captcha verification or the pass record is unavailable; no reservation is made and the client must not fall back to POST /search/upload with the spent token.