samva-dev Namespaces API
Sub-tenants that confine domains, senders, mailboxes, contacts, templates, and API keys inside an organization
Sub-tenants that confine domains, senders, mailboxes, contacts, templates, and API keys inside an organization
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-namespaces-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 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:
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
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
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
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
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
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
InternalError:
type: object
properties:
_tag:
type: string
enum:
- InternalError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
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
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
ForbiddenError:
type: object
properties:
_tag:
type: string
enum:
- ForbiddenError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: false
NamespaceSummary:
type: object
properties:
id:
$ref: '#/components/schemas/NamespaceId'
name:
type: string
createdAt:
type: string
required:
- id
- name
- createdAt
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
SuccessResponse:
type: object
properties:
success:
type: boolean
required:
- success
additionalProperties: false
Cursor:
type: string
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
NamespaceId:
type: string
pattern: ^ns_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: NamespaceId
NamespacePage:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/NamespaceSummary'
nextCursor:
anyOf:
- type: string
- type: 'null'
required:
- items
- nextCursor
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
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header