Skip to main content

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​

Pending capability or already accepted Search outcome