Media

POST /v1/media uploads a local file for use in a notification. The backend stores media in Azure Blob when media storage is configured and returns a kind-aware media object accepted by POST /v1/messages as attachment. It also returns blob_url, image_url, and content_type for older clients.

Rendering depends on the uploaded file type:

• Image content types (image/png, image/jpeg, image/gif, image/webp) return kind: "image". Send the returned attachment to /v1/messages; the backend also backfills legacy image_url for older clients. iOS feed cards render approved images inline and APNs can attach them as rich notification media when the URL passes the approved-host policy.
• Audio/video uploads return kind: "audio" or kind: "video"; callers may include duration_ms in the multipart form, and the hook runner probes it when local metadata is available.
• PDFs, Markdown files, logs, archives, and other documents return kind: "file". Send the returned attachment; optionally mirror blob_url into url + url_title for compatibility with older clients.
• file_paths on /v1/messages is metadata/context only. It does not upload file bytes.

The media API is intentionally blob-centric: it never needs to know the sender's local absolute path. Customer-facing wrappers should upload the bytes, use the returned attachment fields, and send local path strings only when the user explicitly opts into metadata context.

Production URL:

POST https://notifier.aicrew.in/api/v1/media

Required auth:

X-API-Key: an_key_REPLACE_WITH_YOUR_KEY

Upload example

curl -sS -X POST https://notifier.aicrew.in/api/v1/media \
  -H "X-API-Key: $AGENT_NOTIFIER_API_KEY" \
  -F "file=@screenshot.png"

Response

{
  "id": "media_000000000000",
  "blob_name": "uploads/project/screenshot.png",
  "blob_url": "https://example.blob.core.windows.net/...",
  "image_url": "https://example.blob.core.windows.net/...",
  "content_type": "image/png",
  "kind": "image",
  "mime_type": "image/png",
  "size_bytes": 123456
}

Use the returned structured attachment fields in a message:

{
  "type": "file",
  "title": "Screenshot ready",
  "message": "Tap to inspect the latest run output.",
  "attachment": {
    "id": "media_000000000000",
    "kind": "image",
    "url": "https://example.blob.core.windows.net/...",
    "mime_type": "image/png",
    "size_bytes": 123456,
    "file_name": "screenshot.png"
  }
}

For non-image files, use the returned attachment and optionally mirror the blob as a link for older clients:

{
  "type": "file",
  "title": "Report ready",
  "message": "Open the uploaded Markdown report.",
  "attachment": {
    "id": "media_000000000001",
    "kind": "file",
    "url": "https://example.blob.core.windows.net/...",
    "mime_type": "text/markdown",
    "size_bytes": 8192,
    "file_name": "report.md"
  },
  "url": "https://example.blob.core.windows.net/...",
  "url_title": "report.md"
}

Notes

• Multipart uploads have a hard 50 MiB request cap. Images, audio, and generic files are capped at 25 MiB; video uploads may use up to 50 MiB.
• APNs rich media display has tighter practical image limits; keep notification images small when possible.
• The current /v1/messages schema stores one primary structured attachment. Compatibility clients may also populate legacy image_url for the first image and url/url_title for the first non-image file. True multi-attachment rendering should be treated as a future API/client expansion.
• Local hook uploads are explicit opt-in via fields/env vars such as media_file_path, upload_file_path, attachment_path, AGENT_NOTIFIER_MEDIA_FILE_PATH(S), or AGENT_NOTIFIER_UPLOAD_FILE_PATH(S). Ordinary tool file_path values remain metadata-only to avoid accidental source-file uploads.
• If Azure Blob is not configured, the endpoint returns 503.
• Free-tier clients may use externally hosted image_url values; Pro unlocks server-side blob uploads per the product plan.