Alert attachments

A screenshot of the dashboard, the tail of the log, the heap dump — the evidence that explains an alert usually exists as a file, and it usually lives somewhere else by the time someone else looks. Attachments pin those files to the alert itself, so the next responder sees what you saw.

Before you start
  • Alerts flowing in, per Getting started.
  • Attachments enabled on your deployment — an S3 bucket configured by the admin (step 1 below). Until then every attachment endpoint returns 503.
  1. Enable attachments (admin)

    Attachments are stored in your own S3 bucket — OpsPing never keeps the files itself. An admin sets the ATTACHMENTS_BUCKET environment variable on the backend to the bucket name, and the backend handles the rest: presigned PUT URLs for upload, presigned GET URLs for download. On AWS deployments the backend uses the instance's own IAM role, so there are no extra keys to manage — just make sure that role can read, write, and delete objects in the bucket.

    If ATTACHMENTS_BUCKET is unset, every attachment endpoint returns 503 ATTACHMENTS_DISABLED. Self-hosted deployments need to provide their own bucket — the feature is off until you do.

    Note

    Files use a per-tenant, per-alert S3 prefix. Removing an attachment removes its listing and attempts to delete the object; upload activity metadata remains in the alert timeline.

  2. Upload from the alert detail page

    Open any alert in the admin console and use the Attach file action in the attachments section. Pick a file and it uploads straight to your S3 bucket via a presigned URL — the file never passes through the OpsPing API. Limits: 10 MB per file, 10 attachments per alert. Filenames are sanitized to a safe character set, so unusual names may come out slightly flattened.

    Every completed upload lands in the alert's activity timeline with the filename, size, and who uploaded it — which is often half the value: "the dashboard screenshot Sarah attached at 03:14" is a timeline entry you can navigate.

    Tip

    Compress files larger than 10 MiB (10,485,760 bytes) before attaching them.

  3. Download on web and mobile

    Attachments appear in admin and mobile alert detail. Web shows filename, size, uploader, and upload time; mobile shows filename and size. Download URLs are issued when the list loads and expire after one hour, so refresh or reopen an old detail view to obtain a new link. Mobile remains read-only.

    Note

    Attachment listing follows alert tenant/team access. A presigned download URL is a bearer link until it expires; treat it as sensitive.

  4. Delete attachments and how quota behaves

    Removing an attachment deletes its row and makes a best-effort S3 object deletion; upload activity remains in the timeline. The 10-per-alert cap counts only live attachments. An incomplete 15-minute upload reservation stops counting when it expires.

  5. Upload via the API

    Attachment upload is a three-step dance: mint a presigned URL, PUT the file to S3, then mark the attachment complete. The complete call verifies the object exists and enforces the size cap server-side.

    # 1. Mint a presigned upload URL (15 min lifetime)
    curl -X POST https://api.opsping.com/v2/alerts/ALERT_ID/attachments \
      -H "Authorization: OpsPingKey YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"fileName": "dashboard.png", "contentType": "image/png", "size": 245760}'
    
    # → { "data": { "id": "ATTACHMENT_ID", "uploadUrl": "https://…", "expiresIn": 900 } }
    
    # 2. PUT the file to the presigned URL (Content-Type must match)
    curl -X PUT "UPLOAD_URL" \
      -H "Content-Type: image/png" \
      --data-binary @dashboard.png
    
    # 3. Verify and mark complete — this is when it appears on the alert
    curl -X POST https://api.opsping.com/v2/alerts/ALERT_ID/attachments/ATTACHMENT_ID/complete \
      -H "Authorization: OpsPingKey YOUR_API_KEY"

    GET /v2/alerts/:id/attachments lists uploaded attachments with fresh download URLs; DELETE /v2/alerts/:id/attachments/:attachmentId removes one.