Upload a file

Upload an image or a video as an Asset, or a file as a Brand Document, in three steps. Then register an Asset in the library of an advertiser.

The bytes of a file never go through the API. You reserve the file, send the bytes to a storage URL, and then finalize the file. Assets and Documents use the same three steps.

• An Asset is an image or a video that goes into an ad. You register it in the library of an advertiser.
• A Document is reference material on a Brand, such as a logo or a guidelines PDF. An agent reads it. It never leaves AdCrunch.

Upload an Asset

curl -X POST https://api.adcrunch.dev/assets/uploads \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "spring-sale.mp4" }'

{
  "assetId": "ast_7c1e9a",
  "uploadUrl": "https://…",
  "expiresAt": 1790000000000
}

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --upload-file spring-sale.mp4

curl -X POST https://api.adcrunch.dev/assets/ast_7c1e9a/finalize \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Upload a Document

The steps are the same, on the Brand:

1. POST /context/brands/{slug}/documents/ with filename and content_type. The answer holds documentId, uploadUrl, and expiresInSeconds.
2. PUT the bytes to uploadUrl, with the Content-Type of the file.
3. POST /context/brands/{slug}/documents/{documentId}/finalize.

The two flows use different names for some fields:

Finalize is the only check

The storage URL applies no rule. It accepts each file that you send to it. So AdCrunch checks the file at finalize, from what storage holds: the size of the stored file, and the Content-Type that your PUT sent. What you declared at step 1 controls nothing.

A file that fails the check answers 413 too_large or 415 unsupported_type, and AdCrunch deletes it. Reserve and upload again. When AdCrunch does not accept the declared content_type of a Document, step 1 also answers 415. That answer names the accepted types in allowed.

Register an Asset

A Registration puts an Asset in the library of one advertiser, at its provider. The creative that you create with the Mutations API takes the Asset from that library.

curl -X POST https://api.adcrunch.dev/assets/ast_7c1e9a/registrations \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "advertiserId": "acc_1203456789012345" }'

The answer is the Registration, with the status running. The provider does the work after the answer. To follow it, read Get one Asset: registrations holds each Registration of the Asset. Register an Asset to an advertiser shows each field of a Registration.

When a provider does not accept a Registration, the Registration ends failed, and failureReason says why. The Asset stays stored. What each provider supports lists the providers that accept a Registration.

An Asset can go in the library of many advertisers, with one Registration for each. For one Asset and one advertiser:

• A Registration that is failed can start again. Send the same request. AdCrunch replaces the failed Registration with a new one.
• A Registration that is running or ready blocks a second one. The second request answers 409 already_registered.

Delete an Asset

DELETE /assets/{id} deletes the Asset from AdCrunch. It does not remove the file from the library of an advertiser, because that file belongs to the advertiser now. The answer counts those copies in remainingRegistrations.