Skip to main content
POST
Create an upload

Authorizations

x-api-key
string
header
required

Your organisation's API key, supplied by Dizplai. Send it on every request. It isn't a secret, so it can ship in your app: what a fan does is protected by the fan's token.

Authorization
string
header
required

The fan's token from your own login, sent as Authorization: Bearer <token>: a signed-in fan's or a guest's. Dizplai checks it against your login's details, agreed when you're set up, and a guest's token carries the guest claim agreed at the same time. Needed to vote, upload, send a message, and read the fan's own vote or messages.

Headers

Idempotency-Key
string<uuid>
required

Required. A new UUID for each upload. Keys are kept for each fan for 5 minutes, as long as the link: the same key and body from the same fan within that time answers as the first time, with the same upload and link, so a retry never creates a second upload; with a different body, 409 (idempotency_conflict). After 5 minutes, the same key creates a new upload.

Path Parameters

fan_voice_id
string<uuid>
required

The Fan Voice's ID, from a list of experiences or Fan Voices. A Fan Voice's ID, a UUID.

Example:

"0192fa7b-a1a5-7ae6-8820-782ce84e0f49"

Body

application/json

What the fan wants to upload for a Fan Voice message: its kind, file type and size. Fixed limits: a voice note is audio/mp4 (AAC, what phones record) or audio/webm (Opus), up to 5 MB and 60 seconds; a photo is image/jpeg, image/png, image/heic or image/webp, up to 10 MB.

kind
enum<string>
required
Available options:
voice
content_type
enum<string>
required

The file's type. Upload it with the same Content-Type.

Available options:
audio/mp4,
audio/webm
bytes
integer
required

The file's size in bytes, up to 5 MB.

Required range: 1 <= x <= 5242880

Response

Upload the file to url, then send the message with this upload_id within an hour, or the upload is deleted. If the connection drops, ask again with the same Idempotency-Key and body within 5 minutes, while the link works: you get the same upload and link. After that the key is forgotten, and asking again creates a new upload. An upload that's never used is deleted, and only a message the fan sends counts towards their limit.

Where to upload the file, and the upload_id to send with the message. PUT the file to url before expires_at, with Content-Type set to the content_type and Content-Length to the bytes you asked for; anything else is rejected. Then send the message with this upload_id within an hour, or the upload is deleted. Nothing serves the file until a moderator approves it.

upload_id
string<uuid>
required

A fan's voice note or photo, uploaded for a Fan Voice message. Created when the fan asks to upload, used in one message only, and deleted if no message uses it within an hour.

Example:

"0192fa8a-9346-78b7-9664-3cb0e5caf78d"

url
string<uri>
required

Already signed. PUT the file here with only Content-Type and Content-Length, no x-api-key or Authorization. Don't log it.

expires_at
string<date-time>
required

5 minutes after the request.