samva-dev

samva-dev Namespaces API

Sub-tenants that confine domains, senders, mailboxes, contacts, templates, and API keys inside an organization

GitHub OpenAPI

Operations 8

GET /v1/namespaces List namespaces #
POST /v1/namespaces Create a namespace #
GET /v1/namespaces/{id} Get a namespace #
PATCH /v1/namespaces/{id} Update a namespace #
DELETE /v1/namespaces/{id} Delete a namespace #
POST /v1/namespaces/{id}/resources Move a resource into a namespace #
DELETE /v1/namespaces/{id}/resources/{type}/{resourceId} Return a resource to organization level #
GET /v1/namespaces/{id}/usage Get namespace usage #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/samva-dev/openapi/samva-dev-namespaces-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-namespaces-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-namespaces-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Samva Namespaces 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: Namespaces
  description: Sub-tenants that confine domains, senders, mailboxes, contacts, templates, and API keys inside an organization
paths:
  /v1/namespaces:
    get:
      tags:
      - Namespaces
      operationId: namespaces.list
      parameters:
      - name: limit
        in: query
        schema:
          anyOf:
          - type: integer
            maximum: 100
            exclusiveMinimum: 0
            description: Items per page, at most 100.
          - type: 'null'
        required: false
      - name: cursor
        in: query
        schema:
          anyOf:
          - $ref: '#/components/schemas/Cursor'
          - type: 'null'
        required: false
      - name: after
        in: query
        schema:
          anyOf:
          - type: string
          - type: 'null'
        required: false
      - name: before
        in: query
        schema:
          anyOf:
          - type: string
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: NamespacePage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespacePage'
        '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 namespace summaries, newest first, filterable by creation time (`after`, `before`). Pass `nextCursor` back as `cursor` for the next page; it is null on the last page. Read a namespace's metadata with `GET /v1/namespaces/{id}`.
      summary: List namespaces
      x-samva-scope: organization:read
    post:
      tags:
      - Namespaces
      operationId: namespaces.create
      parameters: []
      security:
      - apiKey: []
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Namespace'
        '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 namespace with status 201. Names are unique within the organization; a duplicate conflicts.
      summary: Create a namespace
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNamespacePayload'
        required: true
      x-samva-scope: organization:update
  /v1/namespaces/{id}:
    get:
      tags:
      - Namespaces
      operationId: namespaces.get
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NamespaceId'
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: Namespace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Namespace'
        '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 namespace.
      summary: Get a namespace
      x-samva-scope: organization:read
    patch:
      tags:
      - Namespaces
      operationId: namespaces.update
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NamespaceId'
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: Namespace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Namespace'
        '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 the fields you name and keeps the rest. `metadata` merges into the stored metadata by key, and a `null` value deletes that key.
      summary: Update a namespace
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNamespacePayload'
        required: true
      x-samva-scope: organization:update
    delete:
      tags:
      - Namespaces
      operationId: namespaces.remove
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NamespaceId'
        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 an empty namespace. A namespace that still holds anything conflicts, and the error counts what remains: mailboxes, API keys, webhook endpoints filtered to it, domains, senders, contacts, or template projects. Delete each, or return it to organization level with `DELETE /v1/namespaces/{id}/resources/{type}/{resourceId}`; mailboxes, keys, and webhook endpoints cannot move and are deleted. Messages keep the namespace they ran in.'
      summary: Delete a namespace
      x-samva-scope: organization:update
  /v1/namespaces/{id}/resources:
    post:
      tags:
      - Namespaces
      operationId: namespaces.assignResource
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NamespaceId'
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: NamespaceResource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceResource'
        '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: Moves a resource from organization level or another namespace into this one. A domain brings its senders; a sender on a domain cannot move alone (assign the domain); a contact brings its identities; a template brings every template in its project. A moved resource stops being a default. An address or external id the namespace already holds conflicts. Keys scoped to the old namespace stop reaching the resource at once. Mailboxes, API keys, and webhook endpoints keep the namespace they were created in.
      summary: Move a resource into a namespace
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignNamespaceResourcePayload'
        required: true
      x-samva-scope: organization:update
  /v1/namespaces/{id}/resources/{type}/{resourceId}:
    delete:
      tags:
      - Namespaces
      operationId: namespaces.removeResource
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NamespaceId'
        required: true
      - name: type
        in: path
        schema:
          $ref: '#/components/schemas/NamespaceResourceType'
        required: true
      - name: resourceId
        in: path
        schema:
          type: string
        required: true
      security:
      - apiKey: []
      responses:
        '200':
          description: NamespaceResource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceResource'
        '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: Moves a resource out of this namespace to organization level, with what follows it as in `POST /v1/namespaces/{id}/resources`. A resource in a different namespace is not found.
      summary: Return a resource to organization level
      x-samva-scope: organization:update
  /v1/namespaces/{id}/usage:
    get:
      tags:
      - Namespaces
      operationId: namespaces.getUsage
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NamespaceId'
        required: true
      - name: after
        in: query
        schema:
          anyOf:
          - type: string
          - type: 'null'
        required: false
      - name: before
        in: query
        schema:
          anyOf:
          - type: string
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: NamespaceUsage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceUsage'
        '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: 'Counts the messages the namespace sent and received in the window that count toward usage, by channel, with the same statuses as `GET /v1/organizations/usage`. A message counts toward the namespace it was sent or received in: that of the sender, mailbox, or key it used. The organization is billed for every namespace; read this to charge your own customer.'
      summary: Get namespace usage
      x-samva-scope: organization:read
components:
  schemas:
    NamespaceResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/NamespaceResourceType'
        id:
          type: string
        namespaceId:
          anyOf:
          - $ref: '#/components/schemas/NamespaceId'
          - type: 'null'
      required:
      - type
      - id
      - namespaceId
      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
    UpdateNamespacePayload:
      type: object
      properties:
        name:
          anyOf:
          - type: string
            pattern: ^\S[\s\S]*\S$|^\S$|^$
            minLength: 1
            maxLength: 128
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 128
          - type: 'null'
        metadata:
          anyOf:
          - type: object
            additionalProperties:
              anyOf:
              - type: string
              - type: 'null'
          - type: 'null'
      additionalProperties: false
    NamespaceId:
      type: string
      pattern: ^ns_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: NamespaceId
    Namespace:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NamespaceId'
        name:
          type: string
        createdAt:
          type: string
        metadata:
          $ref: '#/components/schemas/NamespaceMetadata'
        updatedAt:
          type: string
      required:
      - id
      - name
      - createdAt
      - metadata
      - updatedAt
      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
    CreateNamespacePayload:
      type: object
      properties:
        name:
          type: string
          pattern: ^\S[\s\S]*\S$|^\S$|^$
          minLength: 1
          maxLength: 128
          x-samva-string-checks:
          - id: effect/schema/isMaxLength
            payload:
              maxLength: 128
        metadata:
          anyOf:
          - $ref: '#/components/schemas/NamespaceMetadata'
          - type: 'null'
      required:
      - name
      additionalProperties: false
    NamespaceUsage:
      type: object
      properties:
        namespaceId:
          $ref: '#/components/schemas/NamespaceId'
        periodStart:
          type: string
        periodEnd:
          type: string
        emailCount:
          type: number
        totalMessages:
          type: number
      required:
      - namespaceId
      - periodStart
      - periodEnd
      - emailCount
      - totalMessages
      additionalProperties: false
    Cursor:
      type: string
    NamespacePage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NamespaceSummary'
        nextCursor:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - items
      - nextCursor
      additionalProperties: 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
    NamespaceResourceType:
      type: string
      enum:
      - domain
      - sender
      - contact
      - template
    AssignNamespaceResourcePayload:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/NamespaceResourceType'
        resourceId:
          type: string
          description: The resource's id, such as `dom_...` for a domain.
      required:
      - type
      - resourceId
      additionalProperties: false
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      additionalProperties: false
    NamespaceMetadata:
      type: object
      additionalProperties:
        type: string
      description: Your own labels for the namespace, such as the id of your customer it serves. Samva stores them and never reads them.
    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
    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
    NamespaceSummary:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NamespaceId'
        name:
          type: string
        createdAt:
          type: string
      required:
      - id
      - name
      - createdAt
      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
    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