asset_finalize

Complete an upload after the file arrives. AdCrunch checks the file and makes it a ready Asset, and it can start a Registration in the same call.

Ask to finish an upload, and to register the file with an advertiser in the same step. AdCrunch checks the stored file, and makes it a ready Asset of your organization.

“Finish the upload, and put the file in the Acme Meta account.”

The agent calls this tool after it sent the file. AdCrunch reads the header of the file, and checks its type and its size. When the file passes, you see it in the Assets of your organization. When it fails, AdCrunch deletes it, and the agent tells you why: for example, the file is over the limit for its kind, or ads cannot use its type.

When you name an advertiser, the agent also starts the Registration. That Registration works with the same providers as asset_register. If the Registration cannot start, the Asset stays with your organization. The agent then registers it again with asset_register, and does not upload it again.

This tool is part of the job Bring your own creative.

Reference

Complete an upload after the bytes have been PUT, and add the Asset to the library.

The file is checked here rather than earlier — nothing about it is known until it arrives — so this is where a wrong type or an oversized file is rejected.

Input

Argument	Type	Required	Description
`advertiser_id`	string	no	Optionally register the Asset to this advertiser (acc_…) in the same call.
`asset_id`	string	yes	The Asset id returned by asset_create_upload.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`asset`	object	yes	The Asset, now `ready`. It carries no Registrations: call asset_get for them.
`asset.contentHash`	string	yes	AdCrunch’s own hash of the stored bytes. A hint for de-duplication, never an identity, and never a provider’s hash. Empty when the store reports none.
`asset.createdAt`	number	yes	Milliseconds since the Unix epoch, UTC.
`asset.createdBy`	string	yes	The user who reserved the upload.
`asset.deletedAt`	number or null	yes	Always `null` here. A deleted Asset is not answered.
`asset.durationMs`	number or null	yes	How long the video runs, in milliseconds, read from the header of the file at finalize. `null` for an image. For a video, `null` when the file does not state it, or for an Asset uploaded before AdCrunch read it.
`asset.filename`	string	yes	The name the file was uploaded under. Never a lookup key.
`asset.height`	number or null	yes	The height in pixels as the file is displayed, with its rotation applied, read from the header of the file at finalize. `null` when the file does not state it, or for an Asset uploaded before AdCrunch read it.
`asset.id`	string	yes	The id of the Asset, `ast_…`.
`asset.key`	string	yes	Where the bytes are held. Read-only, and never sent by you.
`asset.kind`	one of `image`, `video`	yes	Follows from `mimeType`, so the stored bytes verify it at finalize. It selects how a provider takes the file.
`asset.mimeType`	string	yes	The `Content-Type` the file was uploaded with, verified against the stored bytes at finalize.
`asset.name`	string or null	yes	The name a person gave this Asset, and what a provider receives at a future registration. `null` until somebody renames it, and the filename is the fallback.
`asset.organizationId`	string	yes	The organization that owns the Asset.
`asset.sizeBytes`	number	yes	Read from the stored object at finalize.
`asset.status`	one of `pending`, `ready`	yes	`ready` once the bytes have been inspected. A `pending` Asset is a reservation whose bytes have not arrived, and no operation here answers one.
`asset.updatedAt`	number or null	yes	When the Asset last changed, in milliseconds since the Unix epoch, UTC: at finalize, or at the last rename.
`asset.width`	number or null	yes	The width in pixels as the file is displayed, with its rotation applied, read from the header of the file at finalize. `null` when the file does not state it, or for an Asset uploaded before AdCrunch read it.
`registration`	object	no	Present only when you send `advertiser_id`: whether the Registration started. AdCrunch keeps the Asset either way. When the Registration started, poll asset_get until it is `ready` or `failed`. When it did not start, call asset_register again, and do not upload the file again.
`registration.ok`	`true` or `false`	yes	`true`: The Registration started. `false`: The Registration did not start. AdCrunch keeps the Asset.
`registration.registration`	object	yes	Only when `ok` is `true`. The Registration, at `running`.
`registration.registration.advertiserId`	string	yes	The advertiser whose provider library gets the Asset.
`registration.registration.assetId`	string	yes	The Asset that the Registration places.
`registration.registration.createdAt`	number	yes	Milliseconds since the Unix epoch, UTC.
`registration.registration.deletedAt`	number or null	yes	Always `null` here. When a retry replaces a failed Registration, AdCrunch sets this time on the old one and answers it no more.
`registration.registration.failureReason`	string or null	yes	Why the Registration failed, as a sentence: the words of the provider, or the words of AdCrunch. `null` unless `status` is `failed`.
`registration.registration.id`	string	yes	The id of the Registration, `reg_…`.
`registration.registration.organizationId`	string	yes	The organization that owns the Asset.
`registration.registration.provider`	one of `meta`, `gads`, `tiktok`, `x`, `openai`, `snapchat`, `dv360`	yes	The provider that owns the advertiser.
`registration.registration.providerIdentifier`	string or null	yes	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.
`registration.registration.status`	one of `running`, `ready`, `failed`	yes	Video can stay `running` for several minutes while the provider processes it. That is normal, and not a failure.
`registration.registration.updatedAt`	number or null	yes	When the Registration last changed, in milliseconds since the Unix epoch, UTC. `null` until its first change.
`registration.registration.uploadSessionId`	string or null	yes	An in-flight provider upload session, where the protocol has one. `null` for every image.
`registration.registration.workflowId`	string	yes	The durable execution that runs the Registration.
`registration.error`	one of `not_found`, `already_registered`	yes	Only when `ok` is `false`. `not_found`: the advertiser is not in this organization. `already_registered`: the Asset already has a `running` or `ready` Registration with that advertiser.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

not_found
not_uploaded
too_large
type_mismatch
unreadable
unsupported_type
forbidden
invalid_request
internal_error

Scope

The token must hold asset:write. Auth & scopes lists each scope.

Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

Writes. The tool can change data.
Destructive. The tool can make a change that you cannot undo. A client can ask you to confirm before it calls the tool.
Idempotent. A second call with the same arguments changes nothing more.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "advertiser_id": "acc_1203456789012345",
  "asset_id": "ast_7c1e9a"
}

The result, in structuredContent:

{
  "asset": {
    "contentHash": "9d2f41b7c6e8a35014f7b2d9c3e6a810",
    "createdAt": 1790000000000,
    "createdBy": "usr_2e5b84",
    "deletedAt": null,
    "durationMs": 15000,
    "filename": "spring-sale.mp4",
    "height": 1920,
    "id": "ast_7c1e9a",
    "key": "org_3a7f10/ast_7c1e9a",
    "kind": "video",
    "mimeType": "video/mp4",
    "name": null,
    "organizationId": "org_3a7f10",
    "sizeBytes": 24117248,
    "status": "ready",
    "updatedAt": 1790000120000,
    "width": 1080
  },
  "registration": {
    "ok": true,
    "registration": {
      "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"
    }
  }
}