samva-dev

samva-dev Media API

Media objects and the presigned uploads that fill them

GitHub OpenAPI

Operations 5

POST /v1/media Create a media object #
POST /v1/media/{id}/complete Complete a media upload #
DELETE /v1/media/{id} Delete a media object #
GET /v1/media/{id} Get a media object #
GET /v1/media/{id}/url Get a media download URL #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/samva-dev/openapi/samva-dev-media-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-email-domain-verification-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-contact-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-template-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-conversation-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-message-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-mailbox-message-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/samva-dev:samva-dev-media-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

samva-dev-media-api-openapi.yml Raw ↑ 
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:
    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
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      additionalProperties: false
    MediaId:
      type: string
      pattern: ^media_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: MediaId
    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
    OrganizationId:
      type: string
      pattern: ^org_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: OrganizationId
    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
    MediaDownloadUrl:
      type: object
      properties:
        url:
          type: string
        expiresAt:
          type: string
      required:
      - url
      - expiresAt
      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
    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
    ForbiddenError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ForbiddenError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      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
    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
    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
    CompletedMedia:
      type: object
      properties:
        media:
          $ref: '#/components/schemas/Media'
        downloadUrl:
          type: string
      required:
      - media
      - downloadUrl
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header