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

# Upload a video

`POST /media/uploads`

## Request

- Base URL: `https://api.deploy.social/v1`
- URL: `https://api.deploy.social/v1/media/uploads`
- Auth: HTTP bearer

Tells us a video is coming and gives you a URL to send it to. `PUT` the file to `upload.url` with `upload.headers`, then call complete. The URL works for 15 minutes; an upload that never finishes is cleared away after 6 hours.

## Headers

- `Idempotency-Key` string: Any unique string, like a UUID. Send the same request again with the same key within 24 hours and you get the first response back instead of a second post.

## Request body

- CreateUpload
  - `filename` string, required: The file's name.
  - `size_bytes` integer, required: The file's size in bytes. Up to 1 GB for a video, 30 MB for a photo.
  - `content_type` string, required: The file's type: a video (MP4, MOV, WebM, AVI or MTS) or a photo (JPEG, PNG or WebP).

## Response `201`

The new video and where to upload it.

- Upload
  - `media` Media, required: A video in your workspace.
    - `id` string, required: The video's id. Starts with `media_`.
    - `kind` 'video' | 'image', required: `video` or `image`. New kinds may be added.
    - `status` string, required: `uploading` until the file arrives, `processing` while we prepare it, then `ready` or `failed`. `expired` means its files were removed after a period of inactivity; upload it again to use it. New values may be added.
    - `filename` string, nullable, required
    - `content_type` string, nullable, required
    - `size_bytes` integer, nullable, required
    - `duration_sec` number, nullable, required
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `progress` object, nullable, required: How far processing has got, while it's running.
      - `phase` string, nullable, required
      - `percent` integer, nullable, required
    - `error` object, nullable, required: Why the video failed, when it did.
      - `code` string, required
      - `message` string, required
    - `created_at` string, date-time, required: When the video was added.
    - `updated_at` string, date-time, required: When the video last changed.
  - `upload` object, required
    - `url` string, required: Send the file here.
    - `method` 'PUT', required
    - `headers` object, required: Send these headers with the file, exactly.
    - `expires_at` string, date-time, required: The upload URL stops working after this.

## Other responses

- `400`: The request body isn't valid JSON, or a header is malformed.
- `401`: The API key is missing, wrong, revoked or expired: `missing_api_key`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`.
- `403`: The key can't do this: `insufficient_scope` (a read-only key), `plan_required`, `usage_limit_exceeded` (this month's videos are used up), `access_revoked` (its creator left the workspace), `workspace_archived`.
- `409`: The post or video isn't in a state that allows this right now: `invalid_state` (detail code `media_expired` when the video's files were removed; upload it again), `media_not_ready` (with `Retry-After`), `idempotency_key_in_progress`.
- `422`: Something in the request needs fixing. `details` lists each problem and where it is: `validation_failed`, or `idempotency_key_reused` when a key is sent again with a different request.
- `429`: Slow down and wait `Retry-After` seconds. Either this key has used its requests for the minute (Standard: 60 reads and 20 writes, Studio: 120 and 30), or, when publishing or scheduling, the plan's API posts for the day are used (detail code `daily_post_limit`; Standard: 30 a day across your account, Studio: 100 a day per workspace; `Retry-After` runs to midnight UTC). Posts made in the app never count.
- `500`: Something broke on our side. Retry, and contact us with the request id if it keeps happening.
- `503`: We can't take the request right now. Retry shortly.

---

[API](https://skmtc.dev/deploy/apis/deploy-social-api.md) · [All operations](https://skmtc.dev/deploy/apis/deploy-social-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deploy/apis/deploy-social-api/revisions/7ed97bdd207f?raw)