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-events-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

openapi: 3.2.0
info:
  title: Samva Events 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: Events
  description: Custom contact event ingestion
paths:
  /v1/events:
    post:
      tags:
      - Events
      operationId: events.create
      parameters:
      - name: idempotency-key
        in: header
        schema:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 255
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 255
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: ContactEvent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactEvent'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '402':
          description: PaymentRequiredError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredError'
        '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'
        '502':
          description: BillingProviderError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProviderError'
        '504':
          description: GatewayTimeoutError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutError'
      description: Records a custom contact event. Identify the contact by exactly one ID, external ID, or email. A missing email or external ID creates a contact; an unknown contact ID returns 404. An organization-scoped idempotency key replays the original event. Event names use letters, digits, underscores, hyphens, and dots, up to 255 characters; contact. and samva. prefixes are reserved. Properties allow at most 50 keys and 32 KiB of UTF-8 JSON. Events are retained for 90 days.
      summary: Record a contact event
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventPayload'
        required: true
      x-idempotent: true
      x-samva-scope: contacts:create
  /v1/events/batch:
    post:
      tags:
      - Events
      operationId: events.batch
      parameters:
      - name: idempotency-key
        in: header
        schema:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 255
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 255
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: BatchEventsResult
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEventsResult'
        '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: Validates the full request shape, contact references, and event names before processing. A schema failure rejects the entire batch without writes. Between 1 and 100 valid entries are then processed in input order, with independent indexed results for properties limits, contact resolution, and domain validation. An optional Idempotency-Key header scopes the batch; retries reuse each entry's original receipt by its position in the batch.
      summary: Record contact events in a batch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEventsPayload'
        required: true
      x-idempotent: true
      x-samva-scope: contacts:create
components:
  schemas:
    ContactId:
      type: string
      pattern: ^contact_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: ContactId
    BatchEventsPayload:
      type: object
      properties:
        events:
          type: array
          prefixItems:
          - $ref: '#/components/schemas/CreateEventPayload'
          minItems: 1
          items:
            $ref: '#/components/schemas/CreateEventPayload'
          maxItems: 100
      required:
      - events
      additionalProperties: 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
    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
    ContactEventReference:
      anyOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/ContactId'
          externalId:
            not: {}
          email:
            not: {}
        required:
        - id
        additionalProperties: false
      - type: object
        properties:
          externalId:
            type: string
            minLength: 1
          id:
            not: {}
          email:
            not: {}
        required:
        - externalId
        additionalProperties: false
      - type: object
        properties:
          email:
            type: string
            pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
          id:
            not: {}
          externalId:
            not: {}
        required:
        - email
        additionalProperties: false
    BillingProviderError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - BillingProviderError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    BatchEventsResult:
      type: object
      properties:
        total:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        accepted:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        errors:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        results:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              status:
                type: string
                enum:
                - accepted
                - error
              event:
                anyOf:
                - $ref: '#/components/schemas/ContactEvent'
                - type: 'null'
              error:
                anyOf:
                - type: string
                - type: 'null'
            required:
            - index
            - status
            additionalProperties: false
      required:
      - total
      - accepted
      - errors
      - results
      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
    JsonObject:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
    UnauthorizedError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - UnauthorizedError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    PaymentRequiredError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - PaymentRequiredError
        message:
          type: string
        resource:
          type: string
        currentUsage:
          type: number
        limit:
          type: number
      required:
      - _tag
      - message
      - resource
      - currentUsage
      - limit
      additionalProperties: false
      x-category:
      - billing
      x-retryable: false
    JsonValue:
      anyOf:
      - type: string
      - type: number
      - type: boolean
      - type: 'null'
      - type: array
        items:
          $ref: '#/components/schemas/JsonValue'
      - type: object
        additionalProperties:
          $ref: '#/components/schemas/JsonValue'
    ContactEvent:
      type: object
      properties:
        id:
          type: string
        contactId:
          $ref: '#/components/schemas/ContactId'
        name:
          type: string
        source:
          type: string
          enum:
          - api
          - samva
        properties:
          $ref: '#/components/schemas/JsonObject'
        occurredAt:
          type: string
        recordedAt:
          type: string
      required:
      - id
      - contactId
      - name
      - source
      - properties
      - occurredAt
      - recordedAt
      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
    ForbiddenError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ForbiddenError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    CreateEventPayload:
      type: object
      properties:
        contact:
          $ref: '#/components/schemas/ContactEventReference'
        name:
          type: string
          minLength: 1
          maxLength: 255
          x-samva-string-checks:
          - id: effect/schema/isMaxLength
            payload:
              maxLength: 255
          - id: effect/schema/isPattern
            payload:
              source: ^(?!(?:[Cc][Oo][Nn][Tt][Aa][Cc][Tt]|[Ss][Aa][Mm][Vv][Aa])\.)[A-Za-z][A-Za-z0-9_.-]*$
              flags: ''
        properties:
          anyOf:
          - $ref: '#/components/schemas/JsonObject'
          - type: 'null'
        occurredAt:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - contact
      - name
      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