Register an Asset to an advertiser

Available on:

Places an Asset in one advertiser’s provider-side library. Not a provider — an organization has several advertisers, and the bytes land in exactly one of them.

Returns immediately with a running Registration; poll GET /assets/{id} for its state. Video can take several minutes to process at the provider, which is normal rather than a failure.

A Registration that is running or ready refuses a second one for the same pair. A failed one starts again: send this request, and AdCrunch replaces it.

POST/assets/{id}/registrations

Authorization

AuthorizationBearer token · headerrequired

Send Authorization: Bearer <credential>.

Use an API key (acr_…), from the AdCrunch console under Settings → API keys.

The credential names the organization, and no operation takes an organization parameter.

See https://docs.adcrunch.dev/api/authentication.

Path parameters

idstringrequired

matches ^(ast_)[\s\S]{0,}$

Request body

requiredapplication/json

advertiserIdstringrequired

The advertiser whose library the bytes land in. Its provider decides how they get there.

matches ^(acc_)[\s\S]{0,}$

Responses

200

The Registration, at running. providerIdentifier is null until the provider has the bytes — read the Asset to see it settle.

advertiserIdstringrequired

The advertiser whose provider library gets the Asset.

assetIdstringrequired

The Asset that the Registration places.

createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

deletedAtnumber | nullrequired

Always null here. When a retry replaces a failed Registration, AdCrunch sets this time on the old one and answers it no more.

failureReasonstring | nullrequired

Why the Registration failed, as a sentence: the words of the provider, or the words of AdCrunch. null unless status is failed.

idstringrequired

The id of the Registration, reg_….

organizationIdstringrequired

The organization that owns the Asset.

providerstringrequired

The provider that owns the advertiser.

Allowed:metagadstiktokxopenaisnapchatdv360

providerIdentifierstring | nullrequired

The id that the provider gave the file: a Meta image hash, or the id of the image or the video at the provider. null until the provider gives it, and null on a failed Registration. An image gets its id when the Registration becomes ready. A video gets its id earlier, while the Registration is running, because the provider gives the id before it has processed the file. Build a creative from a ready Registration only.

statusstringrequired

Video can stay running for several minutes while the provider processes it. That is normal, and not a failure.

Allowed:runningreadyfailed

updatedAtnumber | nullrequired

When the Registration last changed, in milliseconds since the Unix epoch, UTC. null until its first change.

uploadSessionIdstring | nullrequired

An in-flight provider upload session, where the protocol has one. null for every image.

workflowIdstringrequired

The durable execution that runs the Registration.

400

The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. error is invalid_request, and issues names each field. Nothing was changed.

issuesobject[]required

One entry for each field that does not match.

Show properties

Array of object

instringrequired

The part of the request that holds the field.

Allowed:bodycookieheadersparamsquery

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.

pathstringrequired

A JSON Pointer into that part of the request, such as /filename. An empty string is the whole part.

errorstringrequired

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

Allowed:invalid_request

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.

401

No API key, or one that does not resolve. 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.

404

No stored Asset with that id, or no such advertiser in this organization. The two are one answer, so the surface cannot be used to discover that an id is real. error is not_found.

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.

409

This Asset is already in that advertiser’s library. error is already_registered.

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.pr-734.adcrunch.dev/assets/string/registrations' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "advertiserId": "acc_1203456789012345"
}'

const response = await fetch("https://api.pr-734.adcrunch.dev/assets/string/registrations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"advertiserId\": \"acc_1203456789012345\"\n}"
});

import requests

response = requests.post(
    "https://api.pr-734.adcrunch.dev/assets/string/registrations",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"advertiserId\": \"acc_1203456789012345\"\n}",
)

Response

{
  "advertiserId": "acc_1203456789012345",
  "assetId": "ast_7c1e9a",
  "createdAt": 1790000121000,
  "deletedAt": null,
  "failureReason": null,
  "id": "reg_4b81d2",
  "organizationId": "org_3a7f10",
  "provider": "meta",
  "providerIdentifier": null,
  "status": "running",
  "updatedAt": null,
  "uploadSessionId": null,
  "workflowId": "reg_4b81d2"
}

{
  "issues": [
    {
      "in": "body",
      "message": "string",
      "path": "string"
    }
  ],
  "error": "invalid_request",
  "message": "string"
}

{
  "error": "unauthorized",
  "message": "string"
}

{
  "error": "forbidden",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}