---
title: "Upload media"
method: POST
path: "/media"
tags: ["Media"]
---

# Upload media

`POST /media`

## Request

- Base URL: `https://api.post-quest.com/v1`
- URL: `https://api.post-quest.com/v1/media`
- Auth: HTTP bearer

Requires `media:write`. Supply exactly one multipart file, public HTTPS
URL, or base64 value. URL redirects, credentials, non-standard ports,
IP literals, and private destinations are rejected. Decoded base64 is
limited to 3 MiB; all other uploads use the workspace transfer policy.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - MediaUrlInput
    - `url` string, uri, required
    - `filename` string
  - MediaBase64Input
    - `base64` string, byte, required: Raw base64 only, with a decoded maximum of 3 MiB.
    - `filename` string, required

## Response `201`

Media saved to the workspace library.

- MediaResponse
  - `data` Media, required
    - `id` string, uuid, required
    - `filename` string, required
    - `original_filename` string, required
    - `mime_type` string, nullable, required
    - `category` string, required
    - `type` string, required
    - `byte_size` integer, required
    - `size_mb` number, required
    - `dimensions` object, required
      - `width` integer, nullable, required
      - `height` integer, nullable, required
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `duration_seconds` number, nullable, required
    - `thumbnail_url` string, uri, nullable, required
    - `preview_url` string, uri, nullable, required
    - `original_url` string, uri, nullable, required
    - `url` string, uri, nullable, required
    - `conversion_state` 'ready' | 'pending' | 'not_applicable', required
    - `has_poster` boolean, required
    - `collection` string, required
    - `is_metered` boolean, required
    - `original_removed` boolean, required
    - `original_expires_at` string, date-time, nullable, required
    - `usage_count` integer, required
    - `metadata_status` string, required
    - `created_at` string, date-time, nullable, required
    - `urls_expire_at` string, date-time, required
    - `retention` string, required

## Other responses

- `400`: Malformed request, invalid idempotency key, or credential in the query string.
- `401`: Missing, invalid, expired, revoked, or unbound API key.
- `402`: The workspace does not have effective paid REST access.
- `403`: The key lacks an ability, onboarding is incomplete, or publish-now is disabled.
- `409`: Resource state, idempotency payload, or in-progress idempotency conflict.
- `422`: Request fields, platform capability, media, schedule, or quota validation failed.
- `429`: The per-key global or media-specific request limit was exceeded.
- `500`: Unexpected server failure. Internal details are never exposed.

---

[API](https://skmtc.dev/post-quest/apis/postquest-public-api.md) · [All operations](https://skmtc.dev/post-quest/apis/postquest-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/post-quest/apis/postquest-public-api/revisions/089d3c362f35?raw)