Skip to main content
Updated Jul 26, 2026

Uploading files (API & MCP)

What you'll learn
  • How to upload an image or file programmatically and get a reusable reference
  • The two-step REST upload flow (and the one-step MCP tool)
  • Where to use the resulting {bucket, fullPath} reference

Many AutoTalk features take media — a product image for a WhatsApp catalog, a media message, a profile picture. Instead of hosting those files yourself, upload them to AutoTalk once and get a first-party storage reference you can reuse everywhere:

{ "bucket": "autotalk-prod", "fullPath": "companies/<id>/api/images/storage_manual_upload/<id>.png" }

That {bucket, fullPath} reference is accepted by send_message, Dynadata document fields, and functions like createWhatsappWebEvoProduct (in its images array) — see Where to use the reference.

REST: the two-step upload​

Uploading over the REST API is a signed PUT so the bytes go straight to storage. Authenticate every call with your x-api-key.

1. Reserve a signed upload URL​

curl -X POST https://api.autotalk.io/v1/storage/upload-url \
  -H "x-api-key: sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mimeType": "image/png",
    "fileSize": 41161,
    "fileName": "product.png",
    "purpose": "whatsapp_catalog_product_image"
  }'

The response gives you a short-lived uploadUrl, the exact requiredHeaders, and an uploadIntentId:

{
  "success": true,
  "uploadIntentId": "...",
  "uploadUrl": "https://storage.autotalk.io/...&X-Amz-Signature=...",
  "uploadMode": "signed_put",
  "bucket": "autotalk-prod",
  "fullPath": "companies/<id>/api/images/whatsapp_catalog_product_image/<id>.png",
  "category": "images",
  "requiredHeaders": { "Content-Type": "image/png", "Content-Length": "41161", "x-amz-meta-...": "..." }
}

2. PUT the bytes​

Upload the file directly to uploadUrl, sending every requiredHeaders entry exactly as given. The body size must match fileSize.

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: image/png" \
  -H "Content-Length: 41161" \
  --data-binary @product.png

3. Finalize​

curl -X POST https://api.autotalk.io/v1/storage/upload-complete \
  -H "x-api-key: sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "uploadIntentId": "<uploadIntentId>" }'

The response is your reusable reference:

{ "success": true, "bucket": "autotalk-prod", "fullPath": "companies/<id>/api/images/whatsapp_catalog_product_image/<id>.png", "size": 41161, "contentType": "image/png", "category": "images", "fileName": "product.png" }

To read a stored object later, call GET /v1/storage/url?path=<fullPath> for a short-lived download URL.

MCP: begin/complete or one-step inline​

If you connect via the MCP server, use the file tools:

  • begin_file_upload({fileName, mimeType, fileSize}) → do the HTTP PUT to the returned uploadUrl → complete_file_upload({uploadIntentId}). Returns {bucket, fullPath}. Use for any size.
  • upload_file_inline({fileName, mimeType, data}) — pass the base64-encoded bytes directly and get {bucket, fullPath} in a single call. Convenient for small files (≤ ~1 MB); larger files must use the two-step flow.

Where to use the reference​

Pass {bucket, fullPath} (or, for images, either a public URL or the ref) wherever media is accepted:

  • Send a media message — send_message body.file = {bucket, fullPath}.
  • WhatsApp catalog — createWhatsappWebEvoProduct / updateWhatsappWebEvoProduct images: [{bucket, fullPath}, ...].
  • Profile / group picture — updateWhatsappWebEvoProfilePicture picture, updateWhatsappWebEvoGroupPicture image.
  • Dynadata document fields — any storage-object field (e.g. a document's image).

Purposes and limits​

  • purpose (optional, defaults to storage_manual_upload) tags what the file is for. Allowed values: storage_manual_upload, whatsapp_catalog_product_image, template_message_media, chat_media_upload, scheduled_message_media, contact_avatar, company_logo.
  • Uploaded bytes count toward your company storage quota; an upload that would exceed it returns 409.
  • Files live under your company prefix; you can only reference your own tenant's objects.

Next steps​

  • API Reference — authentication and the full endpoint list
  • MCP Servers — connect an AI client and use the file tools
Last updated on
On this page