---
title: "Create an upload URL"
method: POST
path: "/media/create-upload-url"
tags: ["Media"]
---

# Create an upload URL

`POST /media/create-upload-url`

## Request

- Base URL: `https://api.omnisocials.com/v1`
- URL: `https://api.omnisocials.com/v1/media/create-upload-url`
- Auth: HTTP bearer

Create a one-time upload URL, for code that cannot send the API key with the upload, such as an AI assistant's code sandbox. POST the file as multipart `file` to `upload_url` (POST /media/upload-by-token) within 10 minutes; the URL works once. The MCP server's upload tool uses this flow. Requires the `media:write` scope.

## Response `200`

The one-time upload URL and how to use it.

- object
  - `upload_url` string: POST the file here (POST /media/upload-by-token with the token in the query).
  - `upload_token` string: The one-time token (64 hex characters), also part of `upload_url`.
  - `expires_in_seconds` integer
  - `method` string
  - `content_type` string
  - `instructions` string: Upload commands (curl and Python) written for an AI assistant's code sandbox.
  - `hint` string: What an AI assistant should tell the user when its sandbox blocks the upload host.

## Other responses

- `401`: Missing or invalid API key
- `403`: The key lacks the `media:write` scope

## Changes

- **2026-10-21** `3aff2f2e3458`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omnisocials/apis/omnisocials-api/changes/media/create-upload-url/post.md)

---

[API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) - [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisocials/apis/omnisocials-api/revisions/46e479c09474?raw)