asset_create

Create an Asset from the public URL of an image or a video. AdCrunch fetches and checks the file in the background.

Ask to add a file to AdCrunch from its URL. AdCrunch creates an Asset at pending, fetches the file from the URL, and checks its type and its size.

“Add the image at https://example.com/spring-sale.jpg to AdCrunch.”

The agent calls this tool with a public https URL. AdCrunch does not import from an IP address, a local host, or an AdCrunch domain such as adcrunch.dev: for a file there, the agent uses asset_create_upload. The call returns at once. The agent then calls asset_get until the Asset is ready. When the file fails the check, the Asset is failed, and failureCode and failureReason say why. A ready Asset shows in the Assets of your organization. The agent then calls asset_register.

An agent that has a local file and no URL cannot use this tool. It uses the REST API with an API key.

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

Reference

Create an Asset from the URL of an image or a video.

AdCrunch fetches the file from source_url in the background, stores it, and checks its type and size. The URL must use https and must be public. AdCrunch does not import from an IP address, a local host, or an AdCrunch domain. The tool returns at once with the Asset at pending.

Poll asset_get until status is ready, then call asset_register to place the Asset in an advertiser library. When status is failed, failureCode and failureReason say why. Create a new Asset after a failure.

Input

Argument	Type	Required	Description
`name`	string	no	A name to show in place of the filename.
`source_url`	string	yes	The public `https` URL of the image or video.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`asset`	object	yes	The Asset, at `pending`. Poll asset_get until `status` is `ready` or `failed`.
`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.failureCode`	string or null	yes	Why AdCrunch refused the file, as a code. Branch on this field, never on `failureReason`. `unsupported_type`: the bytes are not an accepted image or video. `too_large`: the file is over the size limit. `unreadable`: AdCrunch could not read the header of the file. `source_unreachable`: an import could not fetch the file from its source URL. `source_length_unknown`: the source of an import sent no `Content-Length`. `null` unless `status` is `failed`.
`asset.failureReason`	string or null	yes	Why AdCrunch refused the file, as a sentence. `null` unless `status` is `failed`.
`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`. It selects how a provider takes the file.
`asset.mimeType`	string	yes	The type that finalize identified from the stored bytes. The `Content-Type` of the upload does not set it.
`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`, `failed`	yes	`ready` once AdCrunch has inspected the bytes. Only a `ready` Asset can be registered. `pending`: the bytes have not been inspected yet. `failed`: AdCrunch refused the file and deleted it. `failureCode` and `failureReason` say why. A read answers an Asset in every status. A list answers `ready` Assets only.
`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.

Failure codes

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

invalid_url
not_found
source_not_allowed
organization_unentitled
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.
Not destructive. The tool makes only additive changes.
Not idempotent. A second call with the same arguments can change more.
Open world. The tool reaches a system outside AdCrunch, such as an ad platform.

Example

The arguments:

{
  "name": "Spring sale 9:16",
  "source_url": "https://cdn.example.com/spring-sale.mp4"
}

The result, in structuredContent:

{
  "asset": {
    "contentHash": "",
    "createdAt": 1790000000000,
    "createdBy": "usr_2e5b84",
    "deletedAt": null,
    "durationMs": null,
    "failureCode": null,
    "failureReason": null,
    "filename": "spring-sale.mp4",
    "height": null,
    "id": "ast_7c1e9a",
    "key": "org_3a7f10/ast_7c1e9a",
    "kind": "image",
    "mimeType": "",
    "name": "Spring sale 9:16",
    "organizationId": "org_3a7f10",
    "sizeBytes": 0,
    "status": "pending",
    "updatedAt": 1790000120000,
    "width": null
  }
}