Media

The Media API uploads files (images, documents, video, audio) for use in messages and templates. There are two upload paths to pick from:

Base path: /api/v1/public/media

Media object

POST /media/upload — Direct upload

multipart/form-data upload. Use for message media (header images, document attachments on outgoing messages, etc.). Stores the file in Lynkist's object storage and returns a public URL you can reference in POST /messages/template components.

curl -X POST https://lynkist.io/api/v1/public/media/upload \
  -H "Authorization: Bearer $LYNKIST_API_KEY" \
  -F "file=@/path/to/banner.jpg;type=image/jpeg"

201 Created

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "file_name": "banner.jpg",
  "file_type": "image/jpeg",
  "status": "UPLOADED",
  "public_url": "https://objectstorage.example.com/bucket/path/banner.jpg",
  "created_at": "2026-05-31T08:30:00Z"
}

Use public_url directly in a send:

{
  "components": [
    { "type": "header", "parameters": [
      { "type": "image", "image": { "link": "https://objectstorage.example.com/…/banner.jpg" } }
    ]}
  ]
}

GET /media — List media

curl https://lynkist.io/api/v1/public/media \
  -H "Authorization: Bearer $LYNKIST_API_KEY"

200 OK

{
  "data": [
    {
      "id": "f47ac10b-…",
      "file_name": "banner.jpg",
      "file_type": "image/jpeg",
      "status": "UPLOADED",
      "public_url": "https://…",
      "created_at": "2026-05-31T08:30:00Z"
    }
  ]
}

The response also has a pagination object. This list uses cursor pagination: send limit and cursor.

GET /media/{id} — Get media details

curl https://lynkist.io/api/v1/public/media/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $LYNKIST_API_KEY"

200 OK — the media object. 404 if not found.

DELETE /media/{id} — Delete media

Hard-delete: removes the row from Lynkist and (best-effort) the object from storage. Any template or message that references the public_url directly will break, so make sure nothing in flight still needs it.

curl -X DELETE https://lynkist.io/api/v1/public/media/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $LYNKIST_API_KEY"

200 OK — { "id": "<media id>", "deleted": true }. 404 if not found.

Resumable upload sessions (template media)

WhatsApp requires template header media (images, PDFs, videos used in template approval) to be uploaded through a Meta-managed resumable upload session. Even files small enough to fit in one HTTP request must use this two-step protocol.

Step 1 — POST /media/template-session — Create the session

curl -X POST https://lynkist.io/api/v1/public/media/template-session \
  -H "Authorization: Bearer $LYNKIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "header_banner.jpg",
    "file_length": 482104,
    "file_type": "image/jpeg"
  }'

Allowed file_type values (enforced by Lynkist):

Any other type returns 415 MEDIA_TYPE_NOT_SUPPORTED. A file over the limit returns 413 PAYLOAD_TOO_LARGE.

200 OK

{
  "upload_session_id": "upload:f9bd…"
}

Step 2 — POST /media/template-session/upload — Upload bytes

multipart/form-data. Send the whole file at once (one chunk) or in chunks by setting file_offset on each call.

curl -X POST https://lynkist.io/api/v1/public/media/template-session/upload \
  -H "Authorization: Bearer $LYNKIST_API_KEY" \
  -F "media_id=upload:f9bd…" \
  -F "file_offset=0" \
  -F "file=@/path/to/header_banner.jpg;type=image/jpeg"

200 OK

{
  "h": "4::aW1hZ2UvanBlZw==:ARZ…",
  "media_id": "0b9f6c1e-7d2a-4c55-9a43-2f1d8e6b7a90",
  "public_url": "https://…/header_banner.jpg",
  "header_handle": "https://…/header_banner.jpg"
}

Resuming a partial upload

If a chunk fails mid-flight, re-call POST /media/template-session/upload with the same media_id and the next file_offset. Meta tracks state on its side.

Errors

Lifecycle notes

• A direct-upload Media row lands in UPLOADED immediately if OCI succeeds, or FAILED if not. FAILED rows show in GET /media; clean them up manually.
• Template-session media rows are initially PENDING and flip to UPLOADED after the bytes arrive. FAILED if Meta rejects the chunk.
• Media is not deleted automatically when a template is rejected or a message is sent — call DELETE /media/{id} when you're done with it.