# Luffy SMS API documentation

> Reference documentation for the Luffy SMS REST API. Account data, secrets and purchase tools are NOT exposed by this documentation server.

## Documentation

- [Documentation overview](/docs/quickstart/markdown?lang=en): Everything you need for a reliable SMS integration, from your first request to production.
- [Authentication](/docs/authentication/markdown?lang=en): Personal Bearer keys, account boundaries, and safe rotation.
- [Your first activation](/docs/workflow/markdown?lang=en): The complete purchase and SMS retrieval flow, with checks at every step.
- [API conventions](/docs/conventions/markdown?lang=en): Base URL, formats, monetary values, timestamps, and public API boundaries.
- [Idempotency](/docs/idempotency/markdown?lang=en): Retry purchases after network failures without creating unintended orders.
- [SMS polling and states](/docs/polling/markdown?lang=en): Controlled polling, terminal states, and lossless code handling.
- [Cancellation and refunds](/docs/cancellation/markdown?lang=en): When an activation can be cancelled and how to handle races with SMS delivery.
- [Timeouts and recovery](/docs/timeouts/markdown?lang=en): Separate client waiting time, server execution, and business deadlines.
- [Pagination and history](/docs/pagination/markdown?lang=en): Load history while handling shifting pages and duplicates in your application.
- [Account balance](/docs/balance/markdown?lang=en): Returns the available account balance, shared by the website, Telegram bot, and API.
- [Service catalog](/docs/services/markdown?lang=en): Returns supported services and their identifiers for price lookup and number purchases.
- [Countries and prices](/docs/catalog/markdown?lang=en): Returns countries, current account-specific prices, and available number counts for a service.
- [Purchase a number](/docs/purchase/markdown?lang=en): Purchases one number for a service and country. The server rechecks the price and charges the shared balance.
- [Order status and SMS](/docs/sms/markdown?lang=en): Returns your order status and received SMS code. Missing orders and orders owned by another account return 404.
- [Order history](/docs/history/markdown?lang=en): Returns the latest account orders, newest first, including website, Telegram, and API purchases.
- [Cancel an order](/docs/cancel/markdown?lang=en): Cancels your eligible order without an SMS and refunds the shared balance. Send an empty JSON object.
- [Rate limits and retries](/docs/rate-limits/markdown?lang=en): Share the request budget between clients and handle HTTP 429 correctly.
- [Security](/docs/security/markdown?lang=en): Server-side secrets, user isolation, and safe diagnostics.
- [API errors](/docs/errors/markdown?lang=en): HTTP statuses, machine-readable codes, and recovery decisions for each error class.
- [Production checklist](/docs/production/markdown?lang=en): Check your integration’s resilience before enabling real traffic.
- [Troubleshooting](/docs/troubleshooting/markdown?lang=en): Practical solutions for connection, purchase, and SMS retrieval issues.
- [Examples in 9 languages](/docs/examples/markdown?lang=en): cURL, JavaScript, TypeScript, Python, PHP, Go, Java, C#, and Ruby — no required SDK.
- [OpenAPI and tooling](/docs/openapi/markdown?lang=en): A machine-readable contract for Postman, Insomnia, and type generation.
- [Data models](/docs/data-models/markdown?lang=en): Object semantics, nullable fields, and exact schemas from OpenAPI.
- [Frequently asked questions](/docs/faq/markdown?lang=en): Direct answers about environments, prices, keys, SMS, and v1 capabilities.
- [API Playground](/docs/playground/markdown?lang=en): Try a real request directly in the documentation.

## Tools

- [OpenAPI specification](/openapi.json)
- MCP Streamable HTTP endpoint: /mcp
- Read-only tools: search_docs, get_doc