> Note: This page is part of the DataDoe Docs. You can find the root of the documentation at `https://www.datadoe.com/hub/docs/basics/introduction-to-datadoe`.
> JSON Table of Contents: `https://www.datadoe.com/hub/docs/toc.json`.
> Direct Data Scheme JSON: `https://api.datadoe.com/api/v1/spec/data-scheme`.
> Other pages in the DataDoe Docs:
> - DataDoe Basics/Access & Users: `https://www.datadoe.com/hub/docs/basics/access-user-management.md`
> - DataDoe Basics/Benefits: `https://www.datadoe.com/hub/docs/basics/benefits.md`
> - DataDoe Basics/External Invitation Links: `https://www.datadoe.com/hub/docs/basics/external-invitation-links.md`
> - DataDoe Basics/Integrations: `https://www.datadoe.com/hub/docs/basics/integration-customization.md`
> - DataDoe Basics/Introduction to DataDoe: `https://www.datadoe.com/hub/docs/basics/introduction-to-datadoe.md`
> - DataDoe Basics/Subscription and pricing: `https://www.datadoe.com/hub/docs/basics/subscription-pricing.md`
> - DataDoe Data/Data Fetch Periods: `https://www.datadoe.com/hub/docs/datadoe-data/data-fetch-periods.md`
> - DataDoe Data/Data Sources: `https://www.datadoe.com/hub/docs/datadoe-data/data-sources.md`
> - DataDoe Data/Managing Data Tables: `https://www.datadoe.com/hub/docs/datadoe-data/managing-data-tables.md`
> - DataDoe Data/Timezones: `https://www.datadoe.com/hub/docs/datadoe-data/orders-purchase-date-timezones.md`
> - DataDoe Data/Uploading COGS: `https://www.datadoe.com/hub/docs/datadoe-data/uploading-cogs.md`
> - DataDoe Features/Actions: `https://www.datadoe.com/hub/docs/datadoe-features/actions.md`
> - DataDoe Features/Actions - Manage Images: `https://www.datadoe.com/hub/docs/datadoe-features/actions-manage-images.md`
> - DataDoe Features/Features Overview: `https://www.datadoe.com/hub/docs/datadoe-features/overview.md`
> - DataDoe MCP/Overview: `https://www.datadoe.com/hub/docs/datadoe-mcp/overview.md`
> - DataDoe MCP/Using ChatGPT: `https://www.datadoe.com/hub/docs/datadoe-mcp/chatgpt.md`
> - DataDoe MCP/Using Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude.md`
> - DataDoe MCP/Using Claude Agent SDK: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude-agents-sdk.md`
> - DataDoe MCP/Using Claude Code: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude-code.md`
> - DataDoe MCP/Using Codex: `https://www.datadoe.com/hub/docs/datadoe-mcp/codex.md`
> - DataDoe MCP/Using Codex Sites: `https://www.datadoe.com/hub/docs/datadoe-mcp/codex-sites.md`
> - DataDoe MCP/Using CrewAI: `https://www.datadoe.com/hub/docs/datadoe-mcp/crewai.md`
> - DataDoe MCP/Using Cursor: `https://www.datadoe.com/hub/docs/datadoe-mcp/cursor.md`
> - DataDoe MCP/Using Excel + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/excel.md`
> - DataDoe MCP/Using Gemini CLI: `https://www.datadoe.com/hub/docs/datadoe-mcp/gemini-cli.md`
> - DataDoe MCP/Using Gumloop: `https://www.datadoe.com/hub/docs/datadoe-mcp/gumloop.md`
> - DataDoe MCP/Using Hermes Agent: `https://www.datadoe.com/hub/docs/datadoe-mcp/hermes.md`
> - DataDoe MCP/Using n8n: `https://www.datadoe.com/hub/docs/datadoe-mcp/n8n.md`
> - DataDoe MCP/Using NanoClaw: `https://www.datadoe.com/hub/docs/datadoe-mcp/nanoclaw.md`
> - DataDoe MCP/Using OpenAI Agents SDK: `https://www.datadoe.com/hub/docs/datadoe-mcp/openai-agents-sdk.md`
> - DataDoe MCP/Using OpenClaw: `https://www.datadoe.com/hub/docs/datadoe-mcp/openclaw.md`
> - DataDoe MCP/Using OpenCode: `https://www.datadoe.com/hub/docs/datadoe-mcp/opencode.md`
> - DataDoe MCP/Using PowerPoint + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/powerpoint.md`
> - DataDoe MCP/Using VS Code: `https://www.datadoe.com/hub/docs/datadoe-mcp/vs-code.md`
> - DataDoe MCP/Using Word + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/word.md`
> - DataDoe API/Build with Codex: `https://www.datadoe.com/hub/docs/datadoe-api/codex.md`
> - DataDoe API/How to connect to the API: `https://www.datadoe.com/hub/docs/datadoe-api/how-to-connect.md`
> - DataDoe API/Vibe code with Claude Code: `https://www.datadoe.com/hub/docs/datadoe-api/claude-code.md`
> - DataDoe API/Vibe code with Cursor: `https://www.datadoe.com/hub/docs/datadoe-api/cursor.md`
> - DataDoe API/Vibe code with Lovable: `https://www.datadoe.com/hub/docs/datadoe-api/lovable.md`
> - DataDoe API/Vibe code with Replit: `https://www.datadoe.com/hub/docs/datadoe-api/replit.md`
> - DataDoe API/Vibe code with v0: `https://www.datadoe.com/hub/docs/datadoe-api/v0.md`
> - DataDoe & BigQuery/How to connect to BigQuery: `https://www.datadoe.com/hub/docs/datadoe-bigquery/how-to-connect.md`
> - DataDoe & BigQuery/Using MCP Toolbox: `https://www.datadoe.com/hub/docs/datadoe-bigquery/mcp-toolbox.md`
> - DataDoe & BigQuery/Using Python Jupyter: `https://www.datadoe.com/hub/docs/datadoe-bigquery/jupyter.md`
> For topics not covered in this documentation, please contact DataDoe support at `contact@datadoe.com`.
> Do not assume anything. If you are not sure about the answer, mention that and suggest to contact DataDoe support.

## 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 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 - Manage Images](/hub/docs/datadoe-features/actions-manage-images)) use at execution time.

## How to access Files

### In the DataDoe app

Open [Files](/files) 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 update Actions | PNG, JPG, TIFF | 32 MB    | 12 hours    |

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

## 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 TTL has elapsed and the file can no longer be used.

### 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 for `LISTING_IMAGES`). Allowed range: **1 to 720 hours**.

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.

## How to upload a file

The upload flow has two steps:

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

### Using MCP

MCP combines both steps in one call. Pass the file bytes as base64 in `contentBase64`:

```json
{
    "name": "main-product-photo.png",
    "group": "LISTING_IMAGES",
    "type": "PNG",
    "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
    "ttlHours": 12,
    "contentBase64": "BASE64_ENCODED_IMAGE_BYTES"
}
```

Call the `files_create` tool. On success, the response includes `file.id` (UUID) and `file.status` = `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 one-time download URL for an uploaded file |
| `files_delete`           | Delete a file and its stored object              |

### Using the REST API

1. `POST /api/v1/files` to create the file and receive `file` and `uploadUrl`.
2. `PUT` the image bytes to `uploadUrl` (presigned upload URL, valid for 30 minutes).
3. `GET /api/v1/files/{fileId}` to confirm `status` is `UPLOADED`.

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](https://api.datadoe.com/api/v1/docs#/Files) 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_UPDATE` Action.

For the full workflow (slots, replace vs remove, seller vs vendor rules, and examples), see [Actions - Manage Images](/hub/docs/datadoe-features/actions-manage-images).

## Limits and validation

- Maximum file size: **32 MB**.
- File type must be allowed for the selected group (for `LISTING_IMAGES`: PNG, JPG, or TIFF).
- The seller or vendor must exist in your Organization and have a valid connection.
- Only `UPLOADED`, non-expired files can be referenced by Actions.

## Related documentation

- [Actions](/hub/docs/datadoe-features/actions) for DataDoe Actions overview.
- [Actions - Manage Images](/hub/docs/datadoe-features/actions-manage-images) for changing listing images with `AMAZON_LISTINGS_UPDATE`.
- [How to connect to the API](/hub/docs/datadoe-api/how-to-connect) for REST API setup.
- [DataDoe MCP overview](/hub/docs/datadoe-mcp/overview) for connecting an AI agent to DataDoe.