samva-dev

samva-dev Brands API

Brand themes, logos and footers that templates import with `samva:brand`.

GitHub OpenAPI

Operations 6

GET /v1/brands List brands #
POST /v1/brands Create a brand #
GET /v1/brands/{slug} Get a brand #
PATCH /v1/brands/{slug} Update a brand #
DELETE /v1/brands/{slug} Delete a brand #
POST /v1/brands/{slug}/default Make a brand the default #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/samva-dev/openapi/samva-dev-brands-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-brands-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-brands-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Samva Brands 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: Brands
  description: Brand themes, logos and footers that templates import with `samva:brand`.
paths:
  /v1/brands:
    get:
      tags:
      - Brands
      operationId: brands.list
      parameters: []
      security:
      - apiKey: []
      responses:
        '200':
          description: BrandList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandList'
        '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: Returns the organization's brands, the default brand first.
      summary: List brands
      x-samva-scope: templates:read
    post:
      tags:
      - Brands
      operationId: brands.create
      parameters: []
      security:
      - apiKey: []
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '409':
          description: ConflictError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '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 a brand. The CSS must parse as a brand theme; a rejected theme answers 422 with located findings under `fields.css`. With `isDefault`, the new brand becomes the default. An organization holds at most 12 brands; creating one more answers 409 with a `ConflictError`.
      summary: Create a brand
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrand'
        required: true
      x-samva-scope: templates:create
  /v1/brands/{slug}:
    get:
      tags:
      - Brands
      operationId: brands.get
      parameters:
      - name: slug
        in: path
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: Brand
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '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 one brand by its slug.
      summary: Get a brand
      x-samva-scope: templates:read
    patch:
      tags:
      - Brands
      operationId: brands.update
      parameters:
      - name: slug
        in: path
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: Brand
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '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'
        '409':
          description: ConflictError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '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: Updates a brand. Each section given replaces that section whole. Published templates keep the brand they were built against until they are republished.
      summary: Update a brand
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBrand'
        required: true
      x-samva-scope: templates:update
    delete:
      tags:
      - Brands
      operationId: brands.remove
      parameters:
      - name: slug
        in: path
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
        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'
        '409':
          description: ConflictError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '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 brand. The default brand cannot be deleted; domains that used the deleted brand fall back to the default.
      summary: Delete a brand
      x-samva-scope: templates:delete
  /v1/brands/{slug}/default:
    post:
      tags:
      - Brands
      operationId: brands.setDefault
      parameters:
      - name: slug
        in: path
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: Brand
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '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: 'Makes this brand the organization''s default: bare `samva:brand` and domains without a brand resolve to it at their next build or send.'
      summary: Make a brand the default
      x-samva-scope: templates:update
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
    Brand:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/BrandId'
        slug:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
          description: The brand's handle, unique in the organization; `samva:brand/<slug>` names it.
        name:
          type: string
        isDefault:
          type: boolean
          description: Whether bare `samva:brand` and domains without a brand resolve to this brand.
        css:
          type: string
          description: 'Brand theme CSS: `@theme` variables, one dark-mode `@theme` of colors, and `@font-face` rules with https WOFF2 sources.'
        assets:
          $ref: '#/components/schemas/BrandAssets'
        footer:
          $ref: '#/components/schemas/BrandFooter'
        digest:
          type: string
          description: SHA-256 of the brand's css, assets and footer. A publication built against a different digest predates the brand's current content.
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
      - id
      - slug
      - name
      - isDefault
      - css
      - assets
      - footer
      - digest
      - createdAt
      - updatedAt
      additionalProperties: false
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      additionalProperties: false
    CreateBrand:
      type: object
      properties:
        slug:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
        name:
          type: string
          minLength: 1
          maxLength: 120
          x-samva-string-checks:
          - id: effect/schema/isMaxLength
            payload:
              maxLength: 120
        css:
          anyOf:
          - type: string
            maxLength: 32768
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 32768
          - type: 'null'
        assets:
          anyOf:
          - $ref: '#/components/schemas/BrandAssets'
          - type: 'null'
        footer:
          anyOf:
          - $ref: '#/components/schemas/BrandFooter'
          - type: 'null'
        isDefault:
          anyOf:
          - type: boolean
          - type: 'null'
      required:
      - slug
      - name
      additionalProperties: false
    BrandAssets:
      type: object
      properties:
        logoUrl:
          anyOf:
          - type: string
            maxLength: 2048
            pattern: ^https:\/\/[^\s]+$
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 2048
          - type: 'null'
        logoDarkUrl:
          anyOf:
          - type: string
            maxLength: 2048
            pattern: ^https:\/\/[^\s]+$
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 2048
          - type: 'null'
        iconUrl:
          anyOf:
          - type: string
            maxLength: 2048
            pattern: ^https:\/\/[^\s]+$
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 2048
          - type: 'null'
      additionalProperties: false
    ConflictError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ConflictError
        message:
          type: string
        resource:
          type: string
        id:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - _tag
      - message
      - resource
      additionalProperties: false
      x-category:
      - conflict
      x-retryable: false
    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
    BrandFooter:
      type: object
      properties:
        companyName:
          anyOf:
          - type: string
            maxLength: 255
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 255
          - type: 'null'
        websiteUrl:
          anyOf:
          - type: string
            maxLength: 2048
            pattern: ^https:\/\/[^\s]+$
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 2048
          - type: 'null'
        address:
          anyOf:
          - $ref: '#/components/schemas/BrandAddress'
          - type: 'null'
        socialLinks:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/BrandSocialLink'
            maxItems: 12
          - type: 'null'
      additionalProperties: false
    BrandId:
      type: string
      pattern: ^brand_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: BrandId
    BrandList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Brand'
      required:
      - items
      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
    BrandSocialLink:
      type: object
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 64
          x-samva-string-checks:
          - id: effect/schema/isMaxLength
            payload:
              maxLength: 64
        url:
          type: string
          maxLength: 2048
          pattern: ^https:\/\/[^\s]+$
          x-samva-string-checks:
          - id: effect/schema/isMaxLength
            payload:
              maxLength: 2048
      required:
      - label
      - url
      additionalProperties: false
    UpdateBrand:
      type: object
      properties:
        newSlug:
          anyOf:
          - type: string
            pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
            description: Renames the brand. Projects importing `samva:brand/<old slug>` stop building until they import the new slug.
          - type: 'null'
        name:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 120
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 120
          - type: 'null'
        css:
          anyOf:
          - type: string
            maxLength: 32768
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 32768
          - type: 'null'
        assets:
          anyOf:
          - $ref: '#/components/schemas/BrandAssets'
          - type: 'null'
        footer:
          anyOf:
          - $ref: '#/components/schemas/BrandFooter'
          - type: 'null'
      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
    BrandAddress:
      type: object
      properties:
        street1:
          type: string
          minLength: 1
        street2:
          anyOf:
          - type: string
          - type: 'null'
        city:
          type: string
          minLength: 1
        region:
          type: string
        postalCode:
          type: string
        country:
          type: string
          minLength: 1
      required:
      - street1
      - city
      - region
      - postalCode
      - country
      additionalProperties: false
    InternalError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - InternalError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    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
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header