robase-dev System API

openapi: 3.2.0
info:
  title: Robase SMS OTP System API
  description: 'Multi-provider SMS OTP delivery and transactional SMS API with automatic

    failover and per-country routing. Send and verify one-time passwords across

    Africa and globally.


    ## Authentication


    Every endpoint under `/v1` requires an API key issued in the dashboard,

    passed as a bearer token:


    ```

    Authorization: Bearer robe_your_api_key_here

    ```


    ## Idempotency


    `POST` endpoints accept an `Idempotency-Key` header. Replaying the same key

    within 24 hours returns the original response instead of sending a second

    message, so a request that times out mid-flight can be retried safely

    without double-charging credits. The official SDKs generate a key for every

    `POST` automatically.


    ## Rate limits


    Requests are limited per client IP (100/minute) and per destination phone

    number (3 OTP sends / 10 minutes, 10 OTP verifications / 10 minutes,

    10 transactional SMS / minute). Exceeding a limit returns `429` with a

    `Retry-After` header.


    ## Errors


    Failures return a consistent envelope:


    ```json

    {"error": {"type": "insufficient_credits", "message": "insufficient credit balance"}}

    ```


    Match on `error.type` (it is stable) rather than on `error.message`, which

    is prose and may change.


    ## Languages


    `error.message` is written in your workspace''s default language. Send an

    `Accept-Language` header (`en` or `fr`) to override that for one request.

    It changes only the prose, never `error.type`.


    `Accept-Language` does not affect the text of an SMS. The OTP message body

    follows the workspace''s language setting, or the `language` field on

    `POST /v1/otp/send`. A header describing which language *you* read should

    not decide what your end user receives.


    ## Webhooks


    Dashboard-configured HTTPS callbacks. The signed body is compact JSON

    (no pretty-print, no HTML escaping of `<>&`). HMAC-SHA256 is over those

    exact bytes. Envelope and `data` objects are `WebhookEnvelope`,

    `OTPWebhookData`, `SMSWebhookData`, and `CreditWebhookData`.'
  version: 1.0.0
  contact:
    name: Robase Support
    url: https://robase.dev
servers:
- url: https://api.robase.dev
  description: Production
- url: http://localhost:8080
  description: Local development
tags:
- name: System
  description: Unauthenticated operational endpoints.
paths:
  /health:
    get:
      summary: Liveness probe
      description: Returns 200 while the API process is serving traffic. No authentication.
      operationId: health
      tags:
      - System
      security: []
      responses:
        '200':
          description: The service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                example:
                  status: ok
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Your Robase API key. Starts with robe_. Include as Authorization: Bearer robe_...'