API Overview

Breakwater provides a REST API for vendors to manage their products, customers, licenses, and more programmatically.

Base URL

All API endpoints are prefixed with /api/v1/vendor/.

Authentication

Send a vendor API token (vapi_...) as Authorization: Bearer. Create one in the vendor portal under API tokens. It acts as its owner, with their role, and registry tokens (vtok_, ctok_) are refused. See API Authentication, which includes a recipe for CI.

Available Resources

The API provides access to the following resources:

Resource Description
Products Manage your containerized software offerings
Repositories Configure Docker registry repositories
Customers Manage customer organizations
Licenses Grant and manage customer access to products
Releases Publish versions of a product with their images and files
Bundle events See what air-gapped customers bundled (Business plans and up)
Instances See the installs that report with license status checks (Business plans and up)
Registry tokens Create registry tokens for customers
Pulls View image pull history and analytics
Webhook Endpoints Configure webhook URLs, event subscriptions, and delivery history (delivery statuses)

Response Format

All responses are JSON. Successful responses return the requested data:

{
  "id": "prod_abc123",
  "name": "My Product",
  "slug": "my-product"
}

List endpoints include pagination metadata:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 100,
    "total_pages": 4
  }
}

Error Responses

Errors are RFC 9457 problem details, served as application/problem+json, with a machine-readable code to branch on and a detail sentence to show:

{
  "type": "https://www.breakwaterapp.com/docs/api/errors#validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "Status can't change once a license is cancelled; issue a new license instead.",
  "code": "validation_failed",
  "errors": [
    {"field": "status", "detail": "Status can't change once a license is cancelled; issue a new license instead"}
  ]
}

Common status codes:
- 400 - The request body is missing the resource's key, or isn't valid JSON
- 401 - Missing or invalid API token, or a registry token
- 403 - The token's scope, the owner's role or the vendor's plan doesn't allow it
- 404 - Nothing at this address, or the record doesn't exist
- 409 - The record isn't in a state that allows it, such as deleting a release that isn't withdrawn
- 422 - Validation failed, including a license status change the license status rules don't allow (such as changing a cancelled license, or setting expired by hand)
- 429 - Rate limited

API Errors lists every code and what to do about it.

Rate Limiting

API requests are rate limited per vendor. Requests whose credentials name no usable token share a separate limit of 30 per minute per IP address. Response headers indicate your current limits:

  • X-RateLimit-Limit - Maximum requests per period
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Unix timestamp when the limit resets

Customer API

The Breakwater CLI uses a separate API under /api/v1/customer, with a customer's pull token (ctok_...) as HTTP Basic credentials, not a vendor token. It lists the releases a customer can see, fetches a release's manifest and files, and records bundle events. Vendor tokens get 401. It's part of the Business and Enterprise plans; on other plans it answers 403 with the plan_required code, and a release the customer can't see is a 404. Requests are limited to 120 per minute per token. See Air-Gapped Installs.

Interactive Documentation

For detailed endpoint documentation with request/response examples, visit the API Explorer.

Last updated November 19, 2026