samva-dev Media API
Media objects and the presigned uploads that fill them
Media objects and the presigned uploads that fill them
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/samva-dev:samva-dev-media-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Samva Media API
version: 1.0.0
description: Samva is the email API for your app. Send transactional email in one typed call. Delivery events and customer replies come back as signed webhooks, and replies thread to the email they answer.
servers:
- url: https://api.samva.dev
security: []
tags:
- name: Media
description: Media objects and the presigned uploads that fill them
paths:
/v1/media:
post:
tags:
- Media
operationId: media.create
parameters: []
security:
- apiKey: []
responses:
'201':
description: CreatedMedia
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedMedia'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: 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.
summary: Create a media object
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMediaPayload'
required: true
x-samva-scope: messages:create or email:send or mailboxes:send or mailboxes:update
/v1/media/{id}/complete:
post:
tags:
- Media
operationId: media.complete
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/MediaId'
required: true
security:
- apiKey: []
responses:
'200':
description: CompletedMedia
content:
application/json:
schema:
$ref: '#/components/schemas/CompletedMedia'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Verifies the uploaded object exists in storage, marks the media object ready, and returns it with a download URL. Requires the permission that creating the media object did.
summary: Complete a media upload
x-samva-scope: messages:create or email:send or mailboxes:send or mailboxes:update
/v1/media/{id}:
delete:
tags:
- Media
operationId: media.remove
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/MediaId'
required: true
security:
- apiKey: []
responses:
'200':
description: SuccessResponse
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Deletes a pending media object and the bytes stored for it. Fails if the media object is already ready.
summary: Delete a media object
x-samva-scope: messages:delete
get:
tags:
- Media
operationId: media.getById
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/MediaId'
required: true
security:
- apiKey: []
responses:
'200':
description: Media
content:
application/json:
schema:
$ref: '#/components/schemas/Media'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Returns the media object's metadata, including status, dimensions, and confirmation timestamps.
summary: Get a media object
x-samva-scope: messages:read
/v1/media/{id}/url:
get:
tags:
- Media
operationId: media.downloadUrl
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/MediaId'
required: true
security:
- apiKey: []
responses:
'200':
description: MediaDownloadUrl
content:
application/json:
schema:
$ref: '#/components/schemas/MediaDownloadUrl'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Generates a presigned, time-limited download URL for a ready media object.
summary: Get a media download URL
x-samva-scope: messages:read
components:
schemas:
GatewayTimeoutError:
type: object
properties:
_tag:
type: string
enum:
- GatewayTimeoutError
message:
type: string
retryAfterSeconds:
type: number
required:
- _tag
- message
- retryAfterSeconds
additionalProperties: false
x-category:
- transient
x-retryable: true
CreateMediaPayload:
type: object
properties:
filename:
type: string
minLength: 1
maxLength: 255
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 255
contentType:
type: string
minLength: 1
maxLength: 127
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 127
sizeBytes:
type: integer
maximum: 26214400
exclusiveMinimum: 0
purpose:
type: string
enum:
- attachment
- avatar
- review_evidence
checksumSha256:
anyOf:
- type: string
- type: 'null'
required:
- filename
- contentType
- sizeBytes
- purpose
additionalProperties: false
UnauthorizedError:
type: object
properties:
_tag:
type: string
enum:
- UnauthorizedError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: false
ValidationError:
type: object
properties:
_tag:
type: string
enum:
- ValidationError
message:
type: string
fields:
anyOf:
- type: object
additionalProperties:
type: array
items:
type: string
- type: 'null'
required:
- _tag
- message
additionalProperties: false
x-category:
- validation
x-retryable: false
MediaDownloadUrl:
type: object
properties:
url:
type: string
expiresAt:
type: string
required:
- url
- expiresAt
additionalProperties: false
ResourceNotFoundError:
type: object
properties:
_tag:
type: string
enum:
- ResourceNotFoundError
resource:
type: string
id:
type: string
message:
type: string
required:
- _tag
- resource
- id
- message
additionalProperties: false
x-category:
- notFound
x-retryable: false
InternalError:
type: object
properties:
_tag:
type: string
enum:
- InternalError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
MediaUploadInstruction:
type: object
properties:
url:
type: string
method:
type: string
enum:
- PUT
headers:
type: object
additionalProperties:
type: string
expiresAt:
type: string
required:
- url
- method
- headers
- expiresAt
additionalProperties: false
OrganizationId:
type: string
pattern: ^org_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: OrganizationId
SuccessResponse:
type: object
properties:
success:
type: boolean
required:
- success
additionalProperties: false
Media:
type: object
properties:
id:
$ref: '#/components/schemas/MediaId'
organizationId:
$ref: '#/components/schemas/OrganizationId'
status:
type: string
enum:
- pending
- uploading
- processing
- ready
- failed
- deleted
filename:
type: string
contentType:
type: string
sizeBytes:
type: number
minimum: 0
width:
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
height:
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
durationMs:
anyOf:
- type: number
minimum: 0
- type: 'null'
purpose:
type: string
enum:
- attachment
- avatar
- review_evidence
checksumSha256:
anyOf:
- type: string
- type: 'null'
expiresAt:
anyOf:
- type: string
- type: 'null'
createdAt:
type: string
confirmedAt:
anyOf:
- type: string
- type: 'null'
required:
- id
- organizationId
- status
- filename
- contentType
- sizeBytes
- width
- height
- durationMs
- purpose
- checksumSha256
- expiresAt
- createdAt
- confirmedAt
additionalProperties: false
MediaId:
type: string
pattern: ^media_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: MediaId
CompletedMedia:
type: object
properties:
media:
$ref: '#/components/schemas/Media'
downloadUrl:
type: string
required:
- media
- downloadUrl
additionalProperties: false
CreatedMedia:
type: object
properties:
id:
$ref: '#/components/schemas/MediaId'
organizationId:
$ref: '#/components/schemas/OrganizationId'
status:
type: string
enum:
- pending
- uploading
- processing
- ready
- failed
- deleted
filename:
type: string
contentType:
type: string
sizeBytes:
type: number
minimum: 0
width:
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
height:
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
durationMs:
anyOf:
- type: number
minimum: 0
- type: 'null'
purpose:
type: string
enum:
- attachment
- avatar
- review_evidence
checksumSha256:
anyOf:
- type: string
- type: 'null'
expiresAt:
anyOf:
- type: string
- type: 'null'
createdAt:
type: string
confirmedAt:
anyOf:
- type: string
- type: 'null'
upload:
$ref: '#/components/schemas/MediaUploadInstruction'
required:
- id
- organizationId
- status
- filename
- contentType
- sizeBytes
- width
- height
- durationMs
- purpose
- checksumSha256
- expiresAt
- createdAt
- confirmedAt
- upload
additionalProperties: false
ForbiddenError:
type: object
properties:
_tag:
type: string
enum:
- ForbiddenError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: false
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header