> ## 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. # Get an OTP > GET /v1/otp/{id} — status and metadata. The code is never returned. ## OpenAPI ````yaml openapi.yaml GET /v1/otp/{id} 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/{id}: get: tags: - OTP summary: Get OTP status description: | Retrieves the current status and details of an OTP. The code itself is never returned — only its length and hash-verified state. `timeline` lists each hop the OTP took, oldest first: `queued`, `sent`, `delivered`, then `verified`, `expired` or `failed`. A `failed` hop carries a `reason` token and whether the credit was `refunded`. See [Delivery timeline](/sms/delivery-timeline). operationId: getOTP parameters: - name: id in: path required: true schema: type: string format: uuid description: OTP ID returned from send responses: '200': description: OTP details content: application/json: schema: $ref: '#/components/schemas/OTPDetails' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - BearerAuth: [] components: schemas: OTPDetails: type: object required: - id - workspace_id - phone_number - country_code - credit_cost - status - code_length - ttl_seconds - attempt_count - max_attempts - expired_at - created_at properties: id: type: string format: uuid workspace_id: type: string format: uuid phone_number: type: string country_code: type: string description: ISO 3166-1 alpha-2 country code credit_cost: type: integer status: type: string enum: - pending - sent - verified - expired - failed code_length: type: integer ttl_seconds: type: integer attempt_count: type: integer description: Verification attempts made so far max_attempts: type: integer description: Attempt budget before the OTP is burned example: 5 sent_at: type: string format: date-time delivered_at: type: string format: date-time verified_at: type: string format: date-time failed_at: type: string format: date-time description: When the OTP was marked failed. Absent otherwise. failure_reason: type: string description: Reason token behind a failed status. See TimelineItem. expired_at: type: string format: date-time description: When the code stops being verifiable metadata: type: object additionalProperties: true created_at: type: string format: date-time timeline: type: array description: Hops the OTP took, oldest first. items: $ref: '#/components/schemas/TimelineItem' TimelineItem: type: object required: - at - status properties: at: type: string format: date-time description: When the hop happened (RFC 3339). status: type: string description: | `queued` (charged and waiting for the worker), then the message's own status values: `sent`, `delivered`, `failed`, `blocked`, and for OTPs `verified` and `expired`. A hop is listed only when its time is known; `status` on the parent object is always authoritative. reason: type: string description: | Stable machine token. Present on a terminal hop when known, and on `sent` when the anti-spam screen flagged but still sent the message. Tokens: `send_failed`, `delivery_failed`, `antispam_blocked`, `antispam_flagged`, `max_attempts_exceeded`. Omitted when unknown. refunded: type: boolean description: | On a terminal `failed` or `blocked` hop only. Reflects the credit ledger: `true` means the charge was returned. 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: 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 NotFound: description: No record with that ID exists in this workspace. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: otp_not_found message: OTP not found 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_... ````