Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview

Reserve an Asset and mint an upload URL

Reserves an Asset and returns a short-lived presigned PUT URL to upload the bytes to.

The client uploads directly to storage — the bytes never pass through this worker, because Cloudflare rejects over-limit request bodies at the proxy before any code runs. Call POST /assets/{id}/finalize once the upload completes.

The URL is the credential: anyone holding it can write that one key until it expires. Nothing is known about the file until finalize inspects what actually landed, so size and type cannot be enforced here.

POST/assets/uploads
Authorization
AuthorizationBearer token · headerrequired

Send Authorization: Bearer <credential>. Two credentials work.

An API key (acr_…) is what a server integration uses. Create one in the AdCrunch console under Settings → API keys — see https://docs.adcrunch.dev/account/api-keys. A key is bound to the organization that was active when you created it, and it keeps acting on that organization whatever you do later. It carries the permissions of the member who created it.

A session issued by the AdCrunch sign-in flow also works, which is how the console calls this service from the browser.

Either way the organization comes from the credential. There is no organization parameter.

Request body
requiredapplication/json
filenamestringrequired

The name of the file you are about to send. Shown until somebody renames the Asset, and never used to look one up.

min length 1 · max length 255
Responses
200

The reservation. Send the bytes to uploadUrl, then finalize assetId.

assetIdstringrequired

The Asset this reservation made. Finalize it with this id.

expiresAtnumberrequired

When the upload URL stops being accepted.

uploadUrlstringrequired

PUT the bytes here, directly. The URL is the credential: anybody holding it can write that one object until it expires.

401

No credential, or one that does not resolve. Send an API key or a session. See the security scheme. error is unauthorized.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:unauthorized
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

403

The caller does not hold asset:write. error is forbidden.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:forbidden
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

422

The request did not match this operation’s schema. This is the framework’s own shape, not the error/message one.

errorsobject[]required

One entry per failing field.

foundanyrequired

What was sent.

messagestringrequired
onstringrequired

Which part of the request failed: body, query or params.

propertystringrequired

The field that failed.

typestringrequired
Allowed:validation
500

AdCrunch could not write the reservation. error is reservation_failed. Nothing was reserved, so send the request again.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

Request
curl -X POST "https://api.adcrunch.dev/assets/uploads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "string"
}'
Response
{
  "assetId": "string",
  "expiresAt": 0,
  "uploadUrl": "string"
}