Site Media

Why this exists

Pages should illustrate with real files, never invented image URLs (made-up links 404 and render broken). Agents check the library first, reuse what's there, and upload only when a new image is genuinely needed. Files land in the same site media library the dashboard's upload dialog uses, so everything stays visible in the editor.

List site media

GET /api/v1/sites/{siteId}/media?cursor=0&limit=24
Authorization: Bearer av_live_…

Required scope: content:read 200 OK

Prepare an upload

POST /api/v1/sites/{siteId}/media/upload
Authorization: Bearer av_live_…
Content-Type: application/json

{ "contentType": "image/png", "size": 482133 }

Required scope: content:write 201 Created Then PUT the raw bytes with exactly the returned headers:

curl -X PUT -H 'Content-Type: image/png' \
  --data-binary @cover.png '…upload.url…'

Once the PUT succeeds, embed publicUrl in page MDX or metadata:

<Media src="https://…/site-media/SITE_ID/1754900000000-ab12cd.png" alt="Launch cover" />

Limits

• Image types: JPEG, PNG, WebP, GIF (no SVG — signed uploads bypass server-side sanitization)
• Max size 10MB; the signed URL is valid for 2 hours
• Uploads are capped per rolling day per site, and count against the organization's storage quota

Errors

Related

• Create a page
• Update a page
• Social media uploads

{
  "images": [
    {
      "name": "1754900000000-ab12cd.png",
      "url": "https://…/assets/site-media/SITE_ID/1754900000000-ab12cd.png",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "size": 482133
    }
  ],
  "nextCursor": null
}

{
  "upload": {
    "url": "https://…signed-upload-url…",
    "method": "PUT",
    "headers": { "Content-Type": "image/png" },
    "expiresInSeconds": 7200
  },
  "publicUrl": "https://…/assets/site-media/SITE_ID/1754900000000-ab12cd.png",
  "path": "site-media/SITE_ID/1754900000000-ab12cd.png",
  "name": "1754900000000-ab12cd.png",
  "mediaType": "image",
  "maxBytes": 10485760
}