Upload a file

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

The bytes of a large file never go through the API. You reserve the file and send the bytes to a storage URL. A Document then needs a finalize call. An Asset needs none: a read of the Asset completes it.

• 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 a small Asset in one call

Send the file as the raw body of POST /assets. The answer is the Asset, with the status ready.

curl --data-binary @ad.png \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY" \
  "https://api.adcrunch.dev/assets?filename=ad.png"

• filename is required. name is optional and replaces the filename in the display.
• Do not use multipart/form-data. The body is the file.
• The request needs a Content-Length. Without one, the answer is 411 length_required.
• The route takes a body up to 95 MB. Over that, the answer is 413 use_upload_url: use the two steps below. A body over the limit of the Cloudflare plan of the domain, 100 MB at the lowest, gets a 413 from Cloudflare with no error code.
• AdCrunch identifies the type from the bytes. A refused file leaves no object and no Asset. The answer is 413 too_large or 415 unsupported_type or unreadable.

Import an Asset from a URL

Send a JSON body to POST /assets. AdCrunch fetches the file from the URL. The answer is 202 with the Asset, with the status pending.

curl -X POST https://api.adcrunch.dev/assets \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sourceUrl": "https://example.com/ad.png" }'

• sourceUrl is required, and it must be an https URL. Another scheme answers 400 invalid_url, and AdCrunch creates nothing. name is optional.
• The host must be a public name. An IP address, a local or private host, or an AdCrunch domain (adcrunch.dev and its subdomains) answers 400 source_not_allowed. To store a file that is on an AdCrunch domain, send its bytes instead.
• The source must send a Content-Length. A source that declares a type AdCrunch does not accept, such as image/svg+xml or text/html, fails at once with unsupported_type. AdCrunch follows a redirect only to an https URL.
• Read the Asset with GET /assets/{id} until its status is ready or failed.
• A failure is on the Asset, not in the answer. failureCode is source_unreachable (the source did not answer, answered with an error, or sent the file in part), source_length_unknown (the source sent no Content-Length), too_large, unsupported_type or unreadable.
• The file takes its name from the Content-Disposition of the source, or else from the last segment of the URL.

Upload an Asset in two steps

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 "If-None-Match: *" \
  --upload-file spring-sale.mp4

curl https://api.adcrunch.dev/assets/ast_7c1e9a \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY"

Upload a Document

A Document has three steps, 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:

The stored file is the only check

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

For an Asset, AdCrunch also reads the header of the stored file. The bytes decide the type, and AdCrunch stores that type as mimeType. A PNG that your PUT sent as image/jpeg becomes a ready Asset of type image/png. The header gives width and height as the file is displayed, with its rotation applied, and durationMs for a video.

A file that fails the check is deleted. A Document finalize answers 413 too_large or 415 unsupported_type. For an Asset, the read answers the Asset with the status failed and a failureCode. The Asset stays. See The status of an Asset. For an Asset, unsupported_type means that the bytes are no accepted type. An Asset can also have the failureCode unreadable, when the file ends before its header does. 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.

The status of an Asset

GET /assets/{id} answers an Asset in every status. GET /assets lists ready Assets only.

failureCode is unsupported_type, too_large or unreadable. An import adds source_unreachable and source_length_unknown. It is null unless the status is failed. A failed Asset cannot recover. Create a new Asset.

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.

When AdCrunch refuses the advertiser before any provider call, failureCode holds one of three codes. Branch on failureCode, never on the sentence in failureReason:

failureCode is null when the provider refused the file.

Only a ready Asset can be registered. A request for another Asset answers 409:

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.