Assets and Uploads

API Reference

Upload image/video assets and reuse them in pins or schedules.

Overview

Asset endpoints are the recommended media path for local files and repeatable workflows. Upload once, store asset IDs, and publish/schedule/import without depending on public media URLs.

What You Will Learn

How multipart image/video uploads map to reusable asset IDs.
How asset metadata and content endpoints support QA, previews, and debugging.
How to use uploaded image assets as video cover images for video publish flows.

Implementation Checklist

Upload media first and persist both `id` and `public_url` from the response.
Use `asset_id` for pin/schedule/import payloads instead of brittle external URLs.
Validate media type usage: video assets for video pins, image assets for image pins and cover images.
For video publishes, provide `cover_image_asset_id` or `cover_image_url` when you need a custom cover frame.
Use `GET /v1/assets/{asset_id}` for metadata checks and `GET /v1/assets/{asset_id}/content` for verification.

Relevant Endpoints

POST

/v1/assets/images

Upload an image file using multipart form-data.

POST

/v1/assets/videos

Upload a video file using multipart form-data.

GET

/v1/assets/{asset_id}

Retrieve asset metadata for one uploaded file.

GET

/v1/assets/{asset_id}/content

Retrieve the stored asset bytes/content endpoint.

Example

curl -X POST "$API_BASE_URL/v1/assets/images" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -F "file=@./creative-image.png"

curl -X POST "$API_BASE_URL/v1/pins" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "<ACCOUNT_ID>",
    "board_id": "<BOARD_ID>",
    "title": "Asset-based publish",
    "asset_id": "<IMAGE_ASSET_ID>",
    "idempotency_key": "asset-based-publish-001"
  }'

Related Guides

Pins Schedules