Public API overview

The Floatless Public API is the stable integration surface for customer, catalog, subscription, invoice, webhook, and metered usage workflows.

Public API documentation belongs here in the Floatless website docs. The product console is used to create API keys, configure webhooks, and inspect operational state.

Base URL

https://api.floatless.com/api/public/v1

Local development commonly uses:

http://localhost:8000/api/public/v1

Current API version

The current public API version is 2026-07-07. Retrieve it at runtime from GET /meta:

curl https://api.floatless.com/api/public/v1/meta

{
  "data": {
    "name": "Floatless Public API",
    "version": "2026-07-07",
    "base_path": "/api/public/v1",
    "authentication": "bearer",
    "openapi_url": "/api/public/v1/openapi.json"
  }
}

Current public resources

Resource	Purpose
Customers	Create and retrieve billing customer records
Products	Read product catalog state used for subscriptions and invoices
Subscriptions	Read active customer subscription state and line items
Invoices	Read invoice headers, balances, periods, invoice items, documents, and transactions
Usage events	Ingest metered usage with idempotent retries
Webhooks	Manage webhook endpoints and delivery history

Orders, payments, quotes, wallets, and coupons are operated from the authenticated console and are not part of the public contract.

AI assistants can also reach billing data read-only through the MCP server, using the same API key.

Start with an integration plan

If you are connecting Floatless to a production system, read the Integration Guide before jumping into individual endpoints. It covers authentication, idempotency, webhook handling, invoice documents, and production launch checks.

API shape

Floatless follows common SaaS API conventions used by developer-first billing platforms:

• Resource-oriented REST paths.
• JSON request and response bodies.
• Standard HTTP status codes.
• Bearer API key authentication.
• Stable versioned base path.
• List responses with data and pagination.
• Write operations that need retry safety use Idempotency-Key.

Response envelope

Single-object responses use:

{
  "data": {
    "id": 123,
    "object": "customer"
  }
}

List responses use:

{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}

OpenAPI specification

The public OpenAPI specification is available from the API service:

GET /api/public/v1/openapi.json

Use it with Postman, Swagger UI, SDK generators, or contract tests.

Documentation update rule

Every new public endpoint, public request field, public response field, error behavior, webhook event, or API version change must update these website docs in the same product change.

Next steps

• Errors & request IDs — the error envelope, status mapping, and tracing
• Pagination — limit/offset semantics and has_more
• Authentication
• Integration Guide
• Customers API
• Usage events API