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.
| Group | Purpose | Allowed types | Max size | Default TTL |
|---|---|---|---|---|
LISTING_IMAGES | Images referenced by listing create/update Actions | PNG, JPG, TIFF | 32 MB | 12 hours |
APLUS_IMAGES | Images referenced by A+ Content and media Actions | PNG, JPG, TIFF | 32 MB | 12 hours |
AD_ASSETS | Images and videos uploaded by AMAZON_ADS_ASSETS_ADD | PNG, JPG, MP4, MOV | 500 MB | 12 hours |
ORDER_MESSAGE_FILES | Files attached to Amazon order messages | PDF, PNG, JPG | 32 MB | 12 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:
WAITING_FOR_UPLOAD: the file record exists, but the content has not been uploaded yet.UPLOADED: the file content is stored and the file can be referenced by other features.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 MCPuploadMode: UPLOAD_URLor the REST API.
The upload flow has two steps:
- Create a file record and receive an upload target.
- 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 incontentBase64.UPLOAD_URL: creates the file and returns{ file, uploadUrl }without content.PUTthe bytes touploadUrlwithin 30 minutes, the same as the REST API flow below. Use it for videos and any file over 500 KB. Do not sendcontentBase64in this mode.
Inline example:
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:
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:
| Tool | Purpose |
|---|---|
files_list | List files with filters and pagination |
files_get | Get metadata for one file by ID |
files_download_url_get | Get a download URL for an uploaded file |
files_delete | Delete 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.
1POST /api/v1/files
2Content-Type: application/json
3datadoe-api-key: YOUR_API_KEYPOST /api/v1/filesto create the file and receivefileanduploadUrl.PUTthe file bytes touploadUrl(presigned upload URL, valid for 30 minutes). Use the URL exactly as returned; do not add or change checksum headers.GET /api/v1/files/{fileId}to confirmstatusisUPLOADED. This usually succeeds within seconds after thePUTcompletes. 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.
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:
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.
- Wait 5 seconds, then call
GET /api/v1/files/FILE_UUID/importwith your API key. - If the status is
PENDINGorDOWNLOADING, double the delay between polls, up to 60 seconds. - When the import status is
READY, get the file metadata and check its expiry before supplying the file ID in your listing Action. - 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:
| Code | What to do |
|---|---|
FILE_IMPORT_INVALID_URL | Correct the HTTPS URL and submit again. |
FILE_IMPORT_DISALLOWED_URL | Use a final, public image URL without a redirect. |
FILE_IMPORT_SOURCE_UNAVAILABLE | Check public access and URL expiry. A pending retry can show this code. |
FILE_IMPORT_TIMEOUT | Use a responsive image host. A pending retry can show this code. |
FILE_IMPORT_TOO_LARGE | Reduce the image to 33,554,432 bytes or fewer. |
FILE_IMPORT_INVALID_IMAGE | Supply a JPG, PNG or TIFF that matches the requested type. |
FILE_IMPORT_RETRIES_EXHAUSTED | Check the source and submit a new request. |
FILE_IMPORT_ACCESS_REVOKED | Restore the required file and account access before submitting again. |
FILE_IMPORT_EXPIRED | Submit again with a source that remains available during processing. |
FILE_IMPORT_DISABLED | Retry 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:
| Method | Endpoint | Purpose |
|---|---|---|
GET | /api/v1/files | List files |
GET | /api/v1/files/{fileId} | Get file metadata |
GET | /api/v1/files/{fileId}/download | Download 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 forLISTING_IMAGES,APLUS_IMAGES, andORDER_MESSAGE_FILES, 500 MB forAD_ASSETS. - File type must be allowed for the selected group (
LISTING_IMAGESandAPLUS_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.
Related documentation
- Actions for DataDoe Actions overview.
- Actions: Listing images for setting listing images with
AMAZON_LISTINGS_CREATEandAMAZON_LISTINGS_UPDATE. - How to connect to the API for REST API setup.
- DataDoe MCP overview for connecting an AI agent to DataDoe.

