Uploads

Create an image upload URL

Returns a short-lived signed upload URL and upload token for an image. Use the returned storage_path — NOT public_url — for carousel_images and profile_picture_url; videos are the opposite, uploadVideo returns a public_url that goes straight into video_url. The stored object's extension comes from the declared content_type (image/png stores a .png), and only falls back to the extension in filename when the content type is unknown, so send the content type that matches the bytes you are about to PUT. storage_path on the response is the key the object is actually stored under — read it rather than rebuilding it from filename. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.

post/upload/image

Request

  • Base URL: https://app.tokportal.com/api/ext
  • URL: https://app.tokportal.com/api/ext/upload/image
  • Auth: API key in header X-API-Key

Headers

X-TokPortal-Dry-Run'true' | '1' | 'yes'

Send true (or 1/yes) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds dry_run: true, dry_run_notice, and — on credit-spending operations — credits_would_charge carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).

Request body

filenamestring required

Original file name. Used only as a fallback for the stored object's extension when content_type is not a recognised image type; content_type is what normally names the object. The response's storage_path is the authoritative key.

content_typestring required

Allowed image MIME types: image/jpeg, image/jpg, image/png, image/webp, image/gif. This value determines the stored object's extension (image/png stores a .png); filename is only the fallback when the type is unrecognised. Send the type that matches the bytes you are about to PUT, and use it as the Content-Type of that PUT. Read storage_path on the response for the key the object actually landed under.

bundle_idstring uuid required
purpose'carousel' | 'profile_picture'

Which bucket the image is stored in. Use the response's storage_path (not public_url) for carousel_images and profile_picture_url.

Example request

{
  "filename": "profile.png",
  "content_type": "image/png"
}

Response

Signed image upload URL.

object required

Changes

No recorded changes to this operation across all 1 revision of this API.