Skip to main content

What are DataDoe Files?

Files are temporary utility files stored in your Organization's DataDoe storage. They let you upload binary content (such as images and videos) and reference it later from Actions, automations, or AI agents through a stable file ID.

Each file belongs to:

  • your Organization
  • a specific Seller or Vendor connection
  • a file group that defines allowed formats, default lifetime, and intended use

Files are not Amazon assets. They are staging objects inside DataDoe that other features (for example, Actions: Listing images) use at execution time.

How to access Files

In the DataDoe app

Open Files (opens in a new tab) from the side menu. The page lists files for the active group tab and shows status, seller or vendor, size, and expiry.

Via MCP or REST API

Files are available through DataDoe MCP tools and the REST API. This is the recommended path for AI agents and custom integrations.

File groups

A file group defines what a file can be used for. Each group has its own allowed file types, default TTL, and validation rules.

GroupPurposeAllowed typesMax sizeDefault TTL
LISTING_IMAGESImages referenced by listing create/update ActionsPNG, JPG, TIFF32 MB12 hours
APLUS_IMAGESImages referenced by A+ Content and media ActionsPNG, JPG, TIFF32 MB12 hours
AD_ASSETSImages and videos uploaded by AMAZON_ADS_ASSETS_ADDPNG, JPG, MP4, MOV500 MB12 hours
ORDER_MESSAGE_FILESFiles attached to Amazon order messagesPDF, PNG, JPG32 MB12 hours

More groups may be added over time. Always pass the correct group when creating a file.

Data row usage

Each uploaded file counts as 100 data rows toward your organization's data row usage for as long as it remains uploaded. Delete or let files expire when you no longer need them to free that usage. See Subscription & Pricing for how data rows affect your plan.

File lifecycle

Every file moves through these statuses:

  1. WAITING_FOR_UPLOAD: the file record exists, but the content has not been uploaded yet.
  2. UPLOADED: the file content is stored and the file can be referenced by other features.
  3. EXPIRED: the file is unavailable because its lifetime ended or its URL import failed.

After a successful REST upload, status usually changes to UPLOADED within seconds. A background reconcile job also runs periodically as a safety net.

TTL (time to live)

When you create a file, you set how long it remains valid (ttlHours). If omitted, the group default is used (12 hours). Allowed range: 1 to 720 hours. In the DataDoe app upload form, common presets are 1 hour, 12 hours, 24 hours, 7 days, and 30 days.

Start any Action that references a file before it expires. Validation rejects expired files.

Scoping

A file is always tied to the Seller or Vendor you pass at creation time (sellerOrVendorId). When you reference a file from an Action, the Action's seller or vendor and connection must match the file.

AD_ASSETS files only need an Amazon Ads or DSP connection, so you can create them for a Seller or Vendor that has no Seller Central or Vendor Central connection, or whose Seller Central or Vendor Central connection is not ready yet.

How to upload a file

Upload options: Upload files via MCP, the REST API, or the DataDoe upload page (opens in a new tab). Inline MCP uploads (contentBase64) are limited to 500 KB per file to stay within the request-size limits of popular AI agents. For larger files, such as videos, use MCP uploadMode: UPLOAD_URL or the REST API.

The upload flow has two steps:

  1. Create a file record and receive an upload target.
  2. Upload the binary content.

Using MCP

files_create has two upload modes, set with uploadMode:

  • INLINE (default): combines both steps in one call. Pass the file bytes as base64 in contentBase64.
  • UPLOAD_URL: creates the file and returns { file, uploadUrl } without content. PUT the bytes to uploadUrl within 30 minutes, the same as the REST API flow below. Use it for videos and any file over 500 KB. Do not send contentBase64 in this mode.

Inline example:

json
1{
2    "name": "main-product-photo.png",
3    "group": "LISTING_IMAGES",
4    "type": "PNG",
5    "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
6    "ttlHours": 12,
7    "contentBase64": "BASE64_ENCODED_IMAGE_BYTES"
8}

Call the files_create tool. On success, the response includes file.id (UUID) and file.status = UPLOADED.

Upload URL example for a video ad asset:

json
1{
2    "name": "brand-video.mp4",
3    "group": "AD_ASSETS",
4    "type": "MP4",
5    "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
6    "uploadMode": "UPLOAD_URL"
7}

The response includes file.status = WAITING_FOR_UPLOAD and uploadUrl. After the PUT, call files_get until status is UPLOADED.

Other MCP tools:

ToolPurpose
files_listList files with filters and pagination
files_getGet metadata for one file by ID
files_download_url_getGet a download URL for an uploaded file
files_deleteDelete a file and its stored object

Using the REST API

Send the datadoe-api-key header on every Files request. Do not use X-Api-Key or Authorization.

http
1POST /api/v1/files
2Content-Type: application/json
3datadoe-api-key: YOUR_API_KEY
  1. POST /api/v1/files to create the file and receive file and uploadUrl.
  2. PUT the file bytes to uploadUrl (presigned upload URL, valid for 30 minutes). Use the URL exactly as returned; do not add or change checksum headers.
  3. GET /api/v1/files/{fileId} to confirm status is UPLOADED. This usually succeeds within seconds after the PUT completes. You can poll this endpoint if needed.

Import a listing image from an HTTPS URL

Use sourceUrl when your REST client can send JSON but cannot upload binary bytes. This option is available to all Organizations for LISTING_IMAGES, with JPG, PNG and TIFF files up to 32 mebibytes, or 33,554,432 bytes. Each completed import becomes a DataDoe File and uses the same 100 data rows as a direct upload.

json
1{
2    "name": "main-product-photo.png",
3    "group": "LISTING_IMAGES",
4    "type": "PNG",
5    "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
6    "ttlHours": 12,
7    "sourceUrl": "https://images.example.com/products/photo.png"
8}

POST /api/v1/files returns HTTP 202 and an import record instead of an upload URL:

json
1{
2    "file": { "id": "FILE_UUID", "status": "WAITING_FOR_UPLOAD" },
3    "import": { "fileId": "FILE_UUID", "status": "PENDING", "errorCode": null, "attempts": 0 }
4}

The example shows the fields needed for polling. The response also includes the usual file metadata.

  1. Wait 5 seconds, then call GET /api/v1/files/FILE_UUID/import with your API key.
  2. If the status is PENDING or DOWNLOADING, double the delay between polls, up to 60 seconds.
  3. When the import status is READY, get the file metadata and check its expiry before supplying the file ID in your listing Action.
  4. If the import status is FAILED, fix the source or metadata and submit a new request to create a new file.

The polling response contains fileId, status, errorCode and attempts. Processing responses include Retry-After: 5. Import status is separate from file status: a pending import has file status WAITING_FOR_UPLOAD, a ready import has UPLOADED, and a failed import has EXPIRED. A failed import is unavailable even if its original processing deadline has not passed. A READY result does not extend the file's lifetime after it expires.

Your Organization can submit up to 5 imports in each 60-second submission window. An extra submission returns HTTP 429 with FILE_IMPORT_RATE_LIMITED; respect Retry-After before trying again. Deleting files does not reset this limit.

The source must be publicly reachable using HTTPS on port 443 with TLS 1.3. Credentials in the URL, fragments, IP addresses, private network destinations and redirects are rejected. Use the final image URL. DataDoe sends no cookies, origin authentication or custom headers. A signed public URL can work, but it must remain valid while the import waits and retries. Keep signed URLs out of support messages.

Imports can wait up to 15 minutes before failing. Each source download has a 30-second deadline. Transient failures are retried at most twice, with a delay between attempts. The requested file lifetime starts when the import completes, with a default of 12 hours. Delete the file to cancel an import you no longer need.

Stable error codes identify the recovery action:

CodeWhat to do
FILE_IMPORT_INVALID_URLCorrect the HTTPS URL and submit again.
FILE_IMPORT_DISALLOWED_URLUse a final, public image URL without a redirect.
FILE_IMPORT_SOURCE_UNAVAILABLECheck public access and URL expiry. A pending retry can show this code.
FILE_IMPORT_TIMEOUTUse a responsive image host. A pending retry can show this code.
FILE_IMPORT_TOO_LARGEReduce the image to 33,554,432 bytes or fewer.
FILE_IMPORT_INVALID_IMAGESupply a JPG, PNG or TIFF that matches the requested type.
FILE_IMPORT_RETRIES_EXHAUSTEDCheck the source and submit a new request.
FILE_IMPORT_ACCESS_REVOKEDRestore the required file and account access before submitting again.
FILE_IMPORT_EXPIREDSubmit again with a source that remains available during processing.
FILE_IMPORT_DISABLEDRetry when image imports are available again.

An import prepares a file for an Action. Amazon decides whether it accepts and displays the submitted image. You can continue using the direct-upload flow by omitting sourceUrl.

Other API endpoints:

MethodEndpointPurpose
GET/api/v1/filesList files
GET/api/v1/files/{fileId}Get file metadata
GET/api/v1/files/{fileId}/downloadDownload uploaded file
DELETE/api/v1/files/{fileId}Delete a file

See the DataDoe API docs (opens in a new tab) for request and response schemas.

Common use cases

Listing image updates

Upload product images to the LISTING_IMAGES group, then reference file UUIDs from an AMAZON_LISTINGS_CREATE or AMAZON_LISTINGS_UPDATE Action.

For the full workflow (slots, replace vs remove, seller vs vendor rules, and examples), see Actions: Listing images.

Creative assets for ads

Upload images or videos to the AD_ASSETS group, then reference file UUIDs from an AMAZON_ADS_ASSETS_ADD Action to add them to Amazon's Creative Asset Library. Image assets accept PNG and JPG; video assets accept MP4 and MOV. See Actions for the action details.

Limits and validation

  • Maximum file size via inline MCP upload (contentBase64): 500 KB per file.
  • Maximum file size via REST API, MCP uploadMode: UPLOAD_URL, and UI: the group's limit, 32 MB for LISTING_IMAGES, APLUS_IMAGES, and ORDER_MESSAGE_FILES, 500 MB for AD_ASSETS.
  • File type must be allowed for the selected group (LISTING_IMAGES and APLUS_IMAGES: PNG, JPG, or TIFF; AD_ASSETS: PNG, JPG, MP4, or MOV; ORDER_MESSAGE_FILES: PDF, PNG, or JPG). Invoice messages require PDF.
  • The seller or vendor must exist in your Organization and have a valid connection (for AD_ASSETS, an Amazon Ads or DSP connection is enough).
  • Only UPLOADED, non-expired files can be referenced by Actions.
  • Each uploaded file uses 100 data rows of storage usage.