Samva
DashboardAPI
ChannelsPlatformMailboxesDevelopersEmail templatesIntegrationsAPI Reference
Media

Create a media object

Creates the media object in the pending state and returns it with the upload instruction; URL, method, and headers; for putting its bytes into storage.

POST
/v1/media

Creates the media object in the pending state and returns it with the upload instruction — URL, method, and headers — for putting its bytes into storage. Requires messages:create, or email:send for attachment media.

Authorization

apiKey
headerx-api-key<token>

Request Body

application/json
  1. body
filename*string
Length1 <= length <= 255
contentType*string
Length1 <= length <= 127
sizeBytes*integer
Range0 < value <= 26214400
purpose*string
Value in"attachment""avatar""whatsapp_media""review_evidence"
checksumSha256?string|null

Response Body

CreatedMedia

application/json
  1. response
id*MediaId
Match^media_[0-9a-hjkmnp-tv-z]{16,24}$
organizationId*OrganizationId
Match^org_[0-9a-hjkmnp-tv-z]{16,24}$
status*string
Value in"pending""uploading""processing""ready""failed""deleted"
filename*string
contentType*string
sizeBytes*number
Range0 <= value
width*|null
height*|null
durationMs*|null
purpose*string
Value in"attachment""avatar""whatsapp_media""review_evidence"
checksumSha256*string|null
expiresAt*string|null
createdAt*string
confirmedAt*string|null
upload*
Example Request
import { createClient } from "samva";const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });const result = await samva.media.create({  "filename": "example",  "contentType": "example",  "sizeBytes": 1,  "purpose": "attachment"});
Example Response
{  "id": "string",  "organizationId": "string",  "status": "pending",  "filename": "string",  "contentType": "string",  "sizeBytes": 0,  "width": 1,  "height": 1,  "durationMs": 0,  "purpose": "attachment",  "checksumSha256": "string",  "expiresAt": "string",  "createdAt": "string",  "confirmedAt": "string",  "upload": {    "url": "string",    "method": "PUT",    "headers": {      "property1": "string",      "property2": "string"    },    "expiresAt": "string"  }}

Related documentation

Complete a media upload

Verifies the uploaded object exists in storage, marks the media object ready, and returns it with a download URL.

Get a media download URL

Generates a presigned, time-limited download URL for a ready media object. Use this endpoint to get a media download URL through the Samva email API.