document_create_upload

Reserve a file on a brand, and get a URL for its bytes. This is the first step of an upload.

Ask to add a file to a brand. This tool is the first of three steps: it reserves the file and gives the agent a URL for the bytes.

“Upload our brand book to Acme.”

The agent calls document_create_upload. Then it sends the file to that URL from its own runtime, and it finishes with document_finalize. You then see the brand book in the files of Acme.

The job guide Describe a brand shows each step of the job.

Reference

Reserve a document against a brand. The tool returns a short-lived upload URL on *.r2.cloudflarestorage.com. Uploading needs a client that can reach that host. If yours cannot, tell the user that you cannot complete the upload from here. Upload the file yourself with an HTTP PUT to that URL, then call document_finalize. The bytes never pass through this tool — only your runtime touches them.

Input

Argument	Type	Required	Description
`brand_name`	string	yes	The brand slug this document belongs to.
`content_type`	string	yes	The file’s content type. Accepted: application/pdf, image/gif, image/jpeg, image/png, image/webp.
`filename`	string	yes	The original filename, for display.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`documentId`	string	yes	The id of the reserved document (`doc_…`). Send it to `document_finalize`.
`expiresInSeconds`	number	yes	How long `uploadUrl` stays valid, in seconds. When it expires, reserve again.
`uploadUrl`	string	yes	A presigned URL. Send the bytes of the file to it with an HTTP `PUT`. Each person who has the URL can write the file until the URL expires.

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
unsupported_type
organization_unentitled
forbidden
invalid_request
internal_error

Scope

The token must hold brand: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.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "brand_name": "acme",
  "content_type": "application/pdf",
  "filename": "acme-brand-guidelines.pdf"
}

The result, in structuredContent:

{
  "documentId": "doc_5e2b41",
  "expiresInSeconds": 900,
  "uploadUrl": "https://3f9c2a7b1e0d4c6a8b5e2f1d9c7a4b60.r2.cloudflarestorage.com/documents/org_3a7f10/doc_5e2b41?X-Amz-Expires=900&X-Amz-Date=20260925T184612Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=5b2e7c1f9a0d4e3b8c6f2a1d7e9b4c05%2F20260925%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=e2ea52baf6fb964e4a650eb7aa0341ae656d1cdf36e8923a247576ec9273f2ca"
}