# Seamless Developer Portal

> Developer documentation for Seamless OS — the API platform for launching and running a mobile operator: orders, subscriptions, billing, payments, and telecom inventory.

Every page is also served as markdown: append `.md` to any page URL, or request the page URL with `text/markdown` ranked above `text/html` in the `Accept` header. The full machine-readable surface is listed under "Machine-readable artifacts" below.

## Get started

- [Intro to Seamless OS](https://docs.valdyr.tech/developer-guide/intro.md) — The fully automated digital telecom platform that makes launching a mobile operator playfully easy and infinitely scalable
- [Get your first order](https://docs.valdyr.tech/api-reference/get-started.md) — Place your first order with the Seamless OS API
- [Choose your integration](https://docs.valdyr.tech/api-reference/choose-your-integration.md) — Select the Seamless OS API integration style that fits your business model and your technical ownership

## Guides

- [Place an order](https://docs.valdyr.tech/developer-guide/use-cases/place-an-order.md) — Create a draft order, add subscription line items, validate and price the order, then submit it for fulfillment using the API
- [Order fulfillment](https://docs.valdyr.tech/developer-guide/use-cases/order-fulfillment.md) — Automate provisioning and delivery of telecommunications services after order completion using API workflows
- [Orders and payments](https://docs.valdyr.tech/developer-guide/use-cases/orders-and-payments.md) — Integrate payment collection with orders using your own payment provider or managed payment sessions
- [Payment processing](https://docs.valdyr.tech/developer-guide/use-cases/payment-processing.md) — Handle recurring billing, payment methods, invoicing, and payment failures using the API
- [Product management](https://docs.valdyr.tech/developer-guide/use-cases/product-management.md) — Discover product catalogs and offerings, understand pricing and billing cycles, and use offerings in orders, addons, and subscription changes
- [Customer self-service](https://docs.valdyr.tech/developer-guide/use-cases/self-management.md) — Build a portal in which a customer reads their usage, changes their plan, and manages their own subscriptions
- [Travel eSIM](https://docs.valdyr.tech/developer-guide/use-cases/travel-esim.md) — Integrate Travel eSIM products for international data connectivity
- [MCP server](https://docs.valdyr.tech/developer-guide/mcp.md) — Connect AI agents and assistants to Seamless OS through the Model Context Protocol (MCP) server
- [Docs for agents](https://docs.valdyr.tech/developer-guide/docs-for-agents.md) — The machine-readable surfaces of this site: markdown pages, llms.txt indexes, the docs MCP server, the OpenAPI spec, and the search index

## Concepts

- [Conventions](https://docs.valdyr.tech/api-reference/conventions.md) — Design principles and naming patterns that make the Seamless OS API consistent and predictable.
- [Authentication](https://docs.valdyr.tech/api-reference/authentication.md) — API keys, user tokens, and how to keep them safe on the Seamless OS API.
- [Versioning](https://docs.valdyr.tech/api-reference/versioning.md) — Pin your integration to an API revision so a breaking change never reaches you unannounced.
- [Upgrading](https://docs.valdyr.tech/api-reference/upgrading.md) — Step-by-step instructions for moving an integration from one API revision to the next.
- [Errors](https://docs.valdyr.tech/api-reference/errors.md) — The structure of an error response from the Seamless OS API, and what each status code means.
- [Idempotency](https://docs.valdyr.tech/api-reference/idempotency.md) — Retry a request with an idempotency key, and the operation still happens only once.
- [Rate limiting](https://docs.valdyr.tech/api-reference/rate-limiting.md) — The request limits on the Seamless OS API, and how to retry when you reach one.
- [Webhooks](https://docs.valdyr.tech/api-reference/webhooks.md) — Event notifications for subscriptions, billing, payments, and usage, with at-least-once delivery.

## Resources

- [Billing](https://docs.valdyr.tech/resources/billing.md) — Manage the billing lifecycle of a customer: bill generation, delivery, and collection
- [Customers](https://docs.valdyr.tech/resources/customers.md) — Manage customer entities and billing relationships
- [Discounts](https://docs.valdyr.tech/resources/discounts.md) — Manage promotional codes and pricing discounts
- [Inventory](https://docs.valdyr.tech/resources/inventory.md) — Manage telecommunications inventory and resource allocation
- [Invoices](https://docs.valdyr.tech/resources/invoices.md) — Generate and manage customer billing statements
- [Licenses](https://docs.valdyr.tech/resources/licenses.md) — Manage software licenses and digital service entitlements
- [Orders](https://docs.valdyr.tech/resources/orders.md) — Manage order creation, configuration, and submission workflows
- [Payment links](https://docs.valdyr.tech/resources/payment-links.md) — Generate shareable payment links for remote payment collection
- [Payment profiles](https://docs.valdyr.tech/resources/payment-profiles.md) — Store and manage customer payment methods securely
- [Payment profile sessions](https://docs.valdyr.tech/resources/payment-profile-sessions.md) — Secure hosted flows for managing customer payment methods
- [Payment sessions](https://docs.valdyr.tech/resources/payment-sessions.md) — Manage hosted payment flows and secure payment collection
- [Payments](https://docs.valdyr.tech/resources/payments.md) — Process one-time payments and manage payment transactions
- [Product catalogs](https://docs.valdyr.tech/resources/product-catalogs.md) — Organize and browse product collections for different customer segments
- [Product offerings](https://docs.valdyr.tech/resources/product-offerings.md) — Browse and manage telecommunications products and services
- [Signing](https://docs.valdyr.tech/resources/signing.md) — Digital signature and contract management for telecommunications services
- [Subscribers](https://docs.valdyr.tech/resources/subscribers.md) — Manage subscriber information and profiles
- [Subscriptions](https://docs.valdyr.tech/resources/subscriptions.md) — Manage active telecommunications service subscriptions
- [Subscription add-ons](https://docs.valdyr.tech/resources/subscription-addons.md) — Manage addon services and features for active subscriptions
- [Subscription usage](https://docs.valdyr.tech/resources/subscription-usage.md) — Monitor and track subscription service consumption and allowances
- [Tools](https://docs.valdyr.tech/resources/tools.md) — Utility endpoints and developer tools for API integration
- [Users](https://docs.valdyr.tech/resources/users.md) — Manage platform users and access permissions
- [Workflows](https://docs.valdyr.tech/resources/workflows.md) — Receive and process external webhooks to trigger automated workflows

## API reference

Generated from the OpenAPI spec. Each page carries every operation of one resource at full schema depth.

- [Reference overview](https://docs.valdyr.tech/api-reference.md) — Index of every reference page.
- [Auth](https://docs.valdyr.tech/api-reference/auth.md) — Authenticate users and obtain access tokens.
- [Customers](https://docs.valdyr.tech/api-reference/customers.md) — Manage customers.
- [Inventory](https://docs.valdyr.tech/api-reference/inventory.md) — Manage phone number inventory, SIM cards, and reservations.
- [Invoices](https://docs.valdyr.tech/api-reference/invoices.md) — Inspect invoice payments and their provider lifecycle.
- [Licenses](https://docs.valdyr.tech/api-reference/licenses.md) — Manage licenses.
- [Orders](https://docs.valdyr.tech/api-reference/orders.md) — Manage orders and line items.
- [Payment Intents](https://docs.valdyr.tech/api-reference/payment-intents.md) — Inspect the amounts the platform is collecting, including attempts, refunds, and billed items.
- [Payment Links](https://docs.valdyr.tech/api-reference/payment-links.md) — Create and manage payment links for orders and invoices.
- [Payment Profile Sessions](https://docs.valdyr.tech/api-reference/payment-profile-sessions.md) — Create sessions for setting up payment profiles.
- [Payment Profiles](https://docs.valdyr.tech/api-reference/payment-profiles.md) — Manage customer payment profiles and methods.
- [Payment Sessions](https://docs.valdyr.tech/api-reference/payment-sessions.md) — Create and manage payment sessions for orders.
- [Porting](https://docs.valdyr.tech/api-reference/porting.md) — Manage number porting for subscriptions.
- [Product Catalogs](https://docs.valdyr.tech/api-reference/product-catalogs.md) — Browse product catalogs.
- [Product Discounts](https://docs.valdyr.tech/api-reference/product-discounts.md) — Discounts and promotions.
- [Product Offerings](https://docs.valdyr.tech/api-reference/product-offerings.md) — Browse product offerings.
- [Reports](https://docs.valdyr.tech/api-reference/reports.md) — Retrieve generated reports and download their files.
- [Subscribers](https://docs.valdyr.tech/api-reference/subscribers.md) — Manage subscribers.
- [Subscription Addons](https://docs.valdyr.tech/api-reference/subscription-addons.md) — Manage subscription addons.
- [Subscription Usage](https://docs.valdyr.tech/api-reference/subscription-usage.md) — Get subscription usage.
- [Subscriptions](https://docs.valdyr.tech/api-reference/subscriptions.md) — Manage subscriptions and subscription.
- [Tools](https://docs.valdyr.tech/api-reference/tools.md) — Tools for address validation, number porting, device info, and network coverage.
- [Users](https://docs.valdyr.tech/api-reference/users.md) — Manage users.
- [Workflows](https://docs.valdyr.tech/api-reference/workflows.md) — Dynamic processing of customer journeys and events.
- [Webhook events](https://docs.valdyr.tech/api-reference/webhook-events.md) — Every event the API sends, grouped by the resource that emits it.
- [Schemas](https://docs.valdyr.tech/api-reference/models.md) — Every request, response and webhook payload schema in the API.

## Machine-readable artifacts

- [OpenAPI 3.1 spec](https://docs.valdyr.tech/bundled_openapi.json) — the bundled spec the whole reference is rendered from; the best source for code generation and exact schemas
- [Search index](https://docs.valdyr.tech/search-index.json) — the prebuilt index behind the site's search; covers operations, webhooks, schemas, fields, and prose with deep-link anchors
- Docs MCP server at `https://docs.valdyr.tech/mcp` — streamable HTTP, no auth; tools to search these docs and fetch any page as markdown
- [Seamless OS MCP server](https://docs.valdyr.tech/developer-guide/mcp.md) — the platform's own MCP server for reading and managing live data (customers, subscriptions, catalogs), deployed per brand

## Optional

- [llms-full-guides.txt](https://docs.valdyr.tech/llms-full-guides.txt) — every guide, concept, and resource page in one document
- [llms-full-api.txt](https://docs.valdyr.tech/llms-full-api.txt) — every endpoint, webhook, and schema in one document
- [llms-full.txt](https://docs.valdyr.tech/llms-full.txt) — both halves in one document; it exceeds most context windows, so prefer one of the two above, a page's own `.md`, or the OpenAPI spec