Ad

API operations

Relationships

Statuses

Ad formats

Display ads are banner images. Native ads pair an image with a headline, body, company name, and call-to-action so the ad blends with publisher content. TV ads are video spots uploaded directly as files. Billboard ads are pre-designed images for digital out-of-home placements. Audio ads are short audio spots for streaming inventory. Each format has a dedicated create endpoint under /v1/advertisers/{advertiserId}/ads that accepts multipart/form-data with a binary file field. Display, native, billboard, and TV uploads cap at 5MB; audio uploads accept MP3, WAV, and MP4/M4A.

Request format - multipart vs JSON

Operations marked with the orange UPLOAD badge are HTTP POSTs whose request body is encoded as multipart/form-data rather than JSON, so they can carry a binary file alongside the form fields. Sending a JSON body with a base64-encoded file or a URL in place of the binary will be rejected.

Each create endpoint expects a single file field containing the binary upload, plus the other form fields (campaignId, name, etc.) as part of the same multipart body. From the command line, use curl -F "file=@..."; from a browser or Node client, build a FormData object and pass it as the fetch body. Do not manually set the Content-Type header - the runtime sets it automatically with the correct multipart boundary, and overriding it strips the boundary and breaks the upload. The MIME type of the file itself is detected from the file's bytes, not from the filename.

const form = new FormData();
form.append("file", fileBlob, "banner.png");
form.append("campaignId", campaignId);
form.append("name", "Spring banner");
form.append("destinationUrl", "https://example.com");

await fetch(`https://api.adcritter.com/v1/advertisers/${advertiserId}/ads/display`, {
  method: "POST",
  headers: { "X-Api-Key": process.env.ADCRITTER_KEY },
  body: form,
});

The other ad operations - list, get, update, delete, and create-ad-from-media-asset - use a normal JSON request body (or no body at all), so the multipart concern only applies to the direct file uploads.

Reusing creatives via the media library

Any ad format can also be created from an existing media asset instead of a fresh upload. Upload the file once with the matching POST /v1/advertisers/{advertiserId}/media-assets/{type} endpoint, then call POST /v1/advertisers/{advertiserId}/media-assets/{mediaAssetId}/ads (create-ad-from-media-asset) with the destination campaignId to snapshot the asset onto the campaign. This is the right path when the same creative will run on multiple campaigns - the media asset stays in the library, and each ad is an independent snapshot of it. See the Media Asset entity for the upload and create-ad-from-media-asset operations.

When building apps