Complete media upload

POST /media/:id/complete

Signal that a file upload is finished. Call this after uploading your file to the presigned URL returned by POST /v1/media/upload. This is step 3 of the 3-step upload flow.

Processing by type:

Images — Marked as ready immediately (images are optimized automatically)
Videos — File verified in storage, thumbnail generated in background, marked as ready
Documents (PDF) — File verified in storage, marked as ready

Copy media_ids straight into your post

The response contains a media_ids array (plural, single-element) — you can copy it directly into the media_ids field of POST /v1/posts with no transformation. The next_step field contains a human-readable instruction pointing at the create-post endpoint.

Path Parameters

Parameter	Type	Required	Description
`media_id`	string (UUID)	Yes	UUID of the media upload to finalize (from step 1's response). Accepts `id` as a deprecated alias in the URL path.

Response Example

200 — Upload finalized

{
  "data": {
    "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "status": "ready",
    "type": "image",
    "width": 1920,
    "height": 1080,
    "duration": null,
    "size": 2048576,
    "content_type": "image/jpeg",
    "created_at": "2026-04-10T12:00:00.000Z",
    "next_step": "Media is ready. Attach it to a post by passing \"media_ids\": [\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"] to POST /v1/posts."
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Response fields

Field	Type	Description
`media_id`	string (UUID)	The single UUID for this media (same as the path parameter)
`media_ids`	string[] (UUID)	Convenience single-element array — copy straight into `POST /v1/posts`
`status`	string	`ready`, `processing`, or `failed`
`type`	string	`image`, `video`, or `document`
`width`	integer or null	Pixel width (images/videos)
`height`	integer or null	Pixel height (images/videos)
`duration`	number or null	Duration in seconds (videos only)
`size`	integer	File size in bytes
`content_type`	string	MIME type
`created_at`	string (ISO 8601)	UTC timestamp when the media record was created
`next_step`	string	Human-readable instruction for attaching to a post

Request

Responses

Media upload completed

Complete media upload

/media/:id/complete

Path Parameters​

Response Example​

200 — Upload finalized​

Response fields​

Request​

Responses​