Media library

The media library holds every image and video available to your workspace. Assets get there by upload in the dashboard or by generation in the content engine.

The public API is read-only: one list endpoint. There is no upload, retrieve-by-id, or delete endpoint on /api/v1.

List assets

GET /api/v1/media-library

Note the hyphen — the path is media-library, not media_assets.

Query parameters:

Name	Type	Notes
asset_type	string	Exact match on the asset’s type. In practice image or video.
limit	integer	1 to 100, default 25.
cursor	string	See Pagination.

There is no tag filter. tags come back on every asset, so filter client-side.

curl "https://app.nativpost.com/api/v1/media-library?asset_type=video&limit=50" \
  -H "Authorization: Bearer $NATIVPOST_API_KEY"

Response:

{
  "object": "list",
  "data": [
    {
      "id": "1e7b8a2c-9d3f-4c81-b0a5-6f2d7e4a9c13",
      "object": "media_asset",
      "url": "https://res.cloudinary.com/nativpost/video/upload/v1234/example.mp4",
      "thumbnail_url": "https://res.cloudinary.com/nativpost/image/upload/v1234/example.jpg",
      "asset_type": "video",
      "mime_type": "video/mp4",
      "width": 1080,
      "height": 1920,
      "aspect_ratio": "9:16",
      "duration_seconds": 12.5,
      "tags": ["office", "founder"],
      "created_at": "2026-07-14T08:22:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Assets are returned newest first by created_at. Ids are UUIDs.

Referencing an asset

Content attaches media by URL, not by asset id. Copy the url value into media_urls:

{
  "caption": "Behind the scenes at the new office.",
  "content_type": "reel",
  "target_platforms": ["instagram", "tiktok"],
  "media_urls": ["https://res.cloudinary.com/nativpost/video/upload/v1234/example.mp4"]
}

media_urls accepts up to 20 absolute URLs and preserves their order. Nothing checks that a URL came from the media library — any publicly reachable URL works — but library assets are the reliable choice because the publishing pipeline can already fetch them.

See Content for the full create and update contract.

Uploading

Uploads happen in the dashboard under Content → Media. The API cannot create or delete assets, so a fully headless workflow needs to host media itself and pass its own URLs in media_urls.