Create media

post/v1/media
Any API key or signed-in userAbout roles

No specific role is required; any valid credential works.

Creates a new media upload document. This includes a temporary upload policy to allow a file upload through a POST request.

Media uploads

Media uploads require a multi-part POST request to the URL in the meta.upload.url property in the response object:

  • The request must include as standard form keys the key-value pairs located in the meta.upload.fields property.
  • The request must include the file as the last key under the name file.

Blocked extensions

The following file name extensions are blocked and cannot be used as attachments:

  • .bin
  • .bat
  • .chm
  • .com
  • .cpl
  • .crt
  • .exe
  • .hlp
  • .hta
  • .inf
  • .ins
  • .isp
  • .jse
  • .lnk
  • .mdb
  • .msc
  • .msi
  • .msp
  • .mst
  • .pcd
  • .pif
  • .ps1
  • .reg
  • .scr
  • .sct
  • .shs
  • .vbe
  • .vba
  • .vbs
  • .wsf
  • .wsh
  • .wsl
About this resource

Media

Media are files your org stores in Kustomer for content rather than for a conversation, such as images embedded in knowledge base articles. You create a media record, upload the file to the temporary URL it returns, then reference the media ID where the file is used.

Media and attachments use the same upload flow, but they are kept apart: attachments belong to messages, notes and drafts, while media hold files used in your org's content, such as the knowledge base editor's images. A media ID only works with the media endpoints, and an attachment ID only with the attachment endpoints.

Uploading takes two steps. First, POST /v1/media with the file's name, contentType and contentLength (in bytes, up to 10,048,576) creates the record, with uploaded: false, and returns a short-lived upload policy in meta.upload. Then send a multipart/form-data POST to meta.upload.url, including every key in meta.upload.fields as a form field exactly as returned, and the file last under the name file. Don't send your Kustomer Authorization header to the upload URL. Upload straight away, because the policy expires.

Key fields

Field Meaning
name The file name. Names with executable or script extensions, such as .exe, .bat, .msi or .ps1, are rejected.
contentType, contentLength The MIME type and size in bytes you declared. Upload a file of exactly that size.
uploaded Whether the file has been uploaded.
redacted Set to true to redact the file. A redacted file has no download URL.

Which endpoint to use

To Call
Create a media record and get an upload policy POST /v1/media
Read one or several media records, or download the file GET /v1/media/{id}
Rename or redact a file PUT /v1/media/{id}

GET /v1/media/{id} accepts a comma-separated list of IDs to read several records at once. Add redirect=true to get a 302 redirect to the file's URL. Unlike attachment URLs, a media file's URL doesn't expire, so you can use it as an image src in your content. A redacted file has no URL, so the request returns the record without redirecting. PUT changes only name and redacted, and returns 404 for an ID that doesn't exist. Pass the rev you last read to make sure you aren't overwriting someone else's change.

RelatedUpload attachmentsAttachmentsKnowledge base articles

Request body

application/jsonrequired
namestringrequired
contentTypestringrequired
contentLengthnumberrequired
≤ 10048576

Responses

Created

objectrequired
objectrequired