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 periodX-RateLimit-Remaining- Requests remainingX-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.