> ## Documentation Index > Fetch the complete documentation index at: https://docs.robase.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For chatbots and coding agents, start at /guides/ai-agents. > Hosted MCP: POST https://api.robase.dev/mcp (Streamable HTTP). Auth: Authorization: Bearer robe_… or robe_agent_…. > Phase 1 tools: get_pricing, send_otp, verify_otp, get_otp, send_sms, get_sms. No payment or top-up tools. > Call get_pricing; treat listed:true as marketed markets (NG, GH, KE, ZA, GB, BJ, CI, US). Do not invent countries or delivery percentages. > Prefer OTP-shaped tests such as "Your Robase test OTP is 123456". Do not send Hello or Good morning as tests. Match errors on error.type. # Send an OTP > POST /v1/otp/send — generate a code, charge credits, queue SMS delivery. ## OpenAPI ````yaml openapi.yaml POST /v1/otp/send openapi: 3.0.3 info: title: Robase SMS OTP 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 security: [] tags: - name: OTP description: Generate, deliver and verify one-time passwords. - name: SMS description: Send arbitrary transactional messages. - name: System description: Unauthenticated operational endpoints. paths: /v1/otp/send: post: tags: - OTP summary: Generate and send an OTP description: | Generates a random numeric code, charges the workspace, and queues the code for SMS delivery. The response returns once the OTP is persisted and charged — delivery is asynchronous, so `status` is `pending` on success. Subscribe to the `otp.sent` / `otp.failed` webhooks, or poll `GET /v1/otp/{id}`, to learn the delivery outcome. operationId: sendOTP parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendOTPRequest' responses: '200': description: OTP created, charged, and queued for delivery content: application/json: schema: $ref: '#/components/schemas/SendOTPResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/SendForbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: > Opaque client-generated key. Replaying the same key within 24 hours returns the original response instead of performing the action again. Recommended for every send so a network-level retry cannot double-charge. example: 550e8400-e29b-41d4-a716-446655440000 schemas: SendOTPRequest: type: object required: - phone_number properties: phone_number: type: string description: Phone number in E.164 format example: '+2348012345678' code_length: type: integer minimum: 4 maximum: 8 default: 6 description: | Number of digits in the generated code. Omit to use the default — sending `0` is not the same as omitting the field. Anything outside 4–8 is refused with `validation_error`. ttl_seconds: type: integer minimum: 1 maximum: 3600 default: 600 description: >- How long the code stays verifiable, in seconds. Omit to use the default. language: type: string enum: - en - fr description: > Language for the OTP message body. Omit to use the workspace's default language (Settings → General → Language & region). Supply it per request when your own end users are not all in the same language. `Accept-Language` deliberately does not affect the message body — it describes the integrator reading our error responses, not the person receiving the SMS. example: fr metadata: type: object additionalProperties: true description: >- Arbitrary key-value data stored with the OTP and returned by `GET /v1/otp/{id}` example: phone_number: '+2348012345678' code_length: 6 ttl_seconds: 600 language: fr SendOTPResponse: type: object required: - id - phone_number - country_code - credit_cost - status - code_length - expires_at - created_at properties: id: type: string format: uuid description: OTP ID to use with the verify and get endpoints phone_number: type: string description: Destination the code was sent to, in E.164 format example: '+2348012345678' country_code: type: string description: ISO 3166-1 alpha-2 country code derived from the number example: NG credit_cost: type: integer description: Credits consumed by this send example: 1 status: type: string enum: - pending description: Always `pending` — delivery happens asynchronously code_length: type: integer description: Number of digits in the generated code example: 6 expires_at: type: string format: date-time description: After this instant the code can no longer be verified created_at: type: string format: date-time ErrorResponse: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string description: | Stable machine-readable identifier. Match on this rather than on `message`. enum: - validation_error - invalid_phone - country_not_supported - unauthorized - insufficient_credits - kyc_required - account_temporarily_restricted - otp_not_found - sms_not_found - otp_expired - otp_already_verified - max_attempts_exceeded - rate_limited - internal_error message: type: string description: Human-readable description. Not stable — do not parse. example: error: type: insufficient_credits message: insufficient credit balance responses: BadRequest: description: | Invalid request. `error.type` is `validation_error` (malformed body or a missing required field), `invalid_phone` (not valid E.164), or `country_not_supported` (no SMS route to that destination). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: invalid_phone message: phone must be in E.164 format (e.g., +2348012345678) Unauthorized: description: The API key is missing, malformed, or unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: unauthorized message: invalid API key PaymentRequired: description: The workspace credit balance is below the cost of this send. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: insufficient_credits message: insufficient credit balance SendForbidden: description: | Sending is paused. `error.type` is `kyc_required` (business verification hold — KYB / financial-alert path, separate from antispam) or `account_temporarily_restricted` (48-hour antispam warning ban). Nothing is charged in either case. A warning ban auto-lifts when `warning_banned_until` expires. Retrying before then will not clear it. Match on `error.type`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: kyc_required: value: error: type: kyc_required message: sending is paused pending business verification account_temporarily_restricted: value: error: type: account_temporarily_restricted message: >- sending is paused on this workspace until the temporary restriction ends RateLimited: description: Rate limit exceeded. Retry after the window indicated by `Retry-After`. headers: Retry-After: description: Seconds to wait before retrying schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: rate_limited message: too many send attempts, try again later InternalError: description: >- An unexpected server-side failure. Safe to retry with the same `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: internal_error message: an unexpected error occurred securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Your Robase API key. Starts with robe_. Include as Authorization: Bearer robe_... ````