> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trypost.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach media from URLs

> Download images, videos, or PDF documents from public URLs and attach them to a post.

For uploading a file directly from your machine instead of fetching a URL, use [`POST /posts/{post}/media`](/api-reference/endpoint/upload-media). To reuse a file already in the Asset Library, use [`POST /posts/{post}/media/from-asset`](/api-reference/endpoint/attach-existing-asset). MCP agents use the same contract via [`attach-media-from-url-tool`](/ai/tools-reference#posts).

## Path parameters

<ParamField path="post" type="string" required>
  The UUID of the post to attach media to.
</ParamField>

## Request

<ParamField body="urls" type="array" required>
  Media to download. **Max 10 items per call.** Each item is an object (not a bare string):

  <Expandable>
    <ParamField body="url" type="string" required>
      Public `http`/`https` URL. Validated with `active_url` (must resolve).
    </ParamField>

    <ParamField body="alt" type="string">
      Optional accessibility alt text (max 2000 characters). Applied to **images** only — ignored for video/PDF.
    </ParamField>
  </Expandable>

  Per-type size caps (from `trypost.media.max_size_mb` / env):

  | Type | Default max | MIME allow-list |
  | - | - | - |
  | **image** | **10 MB** | `image/jpeg`, `image/png`, `image/gif`, `image/webp` |
  | **video** | **1 GB** | `video/mp4`, `video/quicktime` (MOV) |
  | **document** | **100 MB** | `application/pdf` |

  URLs are downloaded server-side and stored as Media records on the workspace.
</ParamField>

## Behaviour

* The post must belong to the caller's current workspace; otherwise the response is `404`.
* Allowed media types are **intersected with the platforms enabled on the post**. If an enabled platform doesn't support the file type (e.g. video on a platform that's image-only), that file is rejected and listed in `failed_urls`.
* Successful attachments are appended to the post's `media[]` array with `size` and `meta` (image `alt` becomes `media[].meta.alt_text`; videos carry `meta.duration` read from the file). Per-network size, duration, GIF and MOV caps are enforced when the post is scheduled or published — see [Media → Enforced on the server](/knowledge-base/media#enforced-on-the-server-not-just-in-the-editor).

## Response

Returns an object with three fields:

<ResponseField name="post" type="object">
  The updated post — same shape as [`GET /posts/{post}`](/api-reference/endpoint/get-post), with newly-attached items now in the `media[]` array.
</ResponseField>

<ResponseField name="attached_count" type="integer">
  Number of URLs that were successfully downloaded and attached.
</ResponseField>

<ResponseField name="failed_urls" type="array">
  URLs that were rejected (unreachable, wrong MIME type, too large, or not allowed by any enabled platform). Each entry is the original URL string.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://app.trypost.it/api/posts/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/media/from-url \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": [
        { "url": "https://cdn.example.com/photo.jpg", "alt": "Product hero shot" },
        { "url": "https://cdn.example.com/deck.pdf" }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "post": {
      "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "content": "Launch day!",
      "media": [
        {
          "id": "01HX1A2B3C4D5E6F7G8H9I0J1K",
          "path": "medias/2681a1bf-131f-41b1-9866-755c1cb51f97.jpg",
          "url": "https://media.trypost.it/medias/2681a1bf-131f-41b1-9866-755c1cb51f97.jpg",
          "type": "image",
          "mime_type": "image/jpeg",
          "original_filename": "photo.jpg",
          "meta": { "alt_text": "Product hero shot" }
        }
      ],
      "status": "draft",
      "scheduled_at": null,
      "published_at": null,
      "platforms": [],
      "labels": [],
      "created_at": "2025-01-14 09:00:00",
      "updated_at": "2025-01-14 09:30:00"
    },
    "attached_count": 1,
    "failed_urls": [
      "https://cdn.example.com/deck.pdf"
    ]
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.