---
title: "Import media from a URL"
method: POST
path: "/v0/media/from-url"
tags: ["Media"]
---

# Import media from a URL

`POST /v0/media/from-url`

## Request

- Base URL: `https://api.schedulin.app`
- URL: `https://api.schedulin.app/v0/media/from-url`
- Auth: one of:
  - API key in header `x-api-key`
  - OAuth 2 (authorization code, authorization URL `https://api.schedulin.app/oauth/authorize`, token URL `https://api.schedulin.app/oauth/token`, scopes: `media:write`)

Downloads a publicly reachable image or video into the media library and returns the media record. Use the returned `url` in `media[].url` when creating a post. Prefer this over the presign flow whenever your client cannot issue a raw HTTP PUT (e.g. an AI agent). The source URL must be public (no auth), http(s), and at most the post upload limit (250 MB); SVG and other active content is rejected.

## Request body

- object
  - `url` string, uri, required
  - `name` string
  - `alt` string, nullable
  - `contentType` string

## Response `200`

OK

- Media
  - `id` string, required
  - `url` string, required
  - `name` string, required
  - `mimeType` string, required
  - `width` integer, nullable, required
  - `height` integer, nullable, required
  - `duration` integer, nullable, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `bucket` string, required
  - `key` string, required
  - `size` integer, nullable, required
  - `alt` string, nullable, required
  - `thumbnailUrl` string, nullable, required
  - `tags` Tag[]
    - `id` string, required
    - `name` string, required
    - `color` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Bad Request — the request isn't allowed in the resource's current state (e.g. editing a published post).
- `401`: Unauthorized — missing or invalid API key / access token.
- `403`: Forbidden — the credential lacks the required scope or access.
- `409`: Conflict
- `422`: Unprocessable request. Schema validation failures have `code: "INPUT_VALIDATION_FAILED"` and `data.fieldErrors` mapping each invalid field to its messages (nested issues name their full path, e.g. `media[0].url: ...`). Business-rule rejections (e.g. a `scheduledAt` in the past) have `code: "UNPROCESSABLE_CONTENT"` and carry the reason in `data.message` and `data.formErrors`.
- `429`: Rate limit exceeded. Wait `Retry-After` seconds before retrying.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/schedulin/apis/schedulin-api.md) · [All operations](https://skmtc.dev/schedulin/apis/schedulin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/schedulin/apis/schedulin-api/revisions/17e886f3bcf3?raw)