Introduction
Authentication, error envelope, and conventions for the marketplace API.
The OpenAPI specification served here is partial. It accurately
documents the public browse list, the audit log, and the three core
trader endpoints (create lease, issue signing token, reveal
credentials), each transcribed from the real handler. The remaining
marketplace routes are not yet in the machine-readable spec; the full
auto-generated spec from utoipa lands as a M5.5 / M10.4 follow-up.
Base URL
| Environment | URL |
|---|---|
| Production | https://api.swqos.dev |
| Staging | https://staging.api.swqos.dev |
| Local dev | http://localhost:8080 |
Authentication
Most endpoints require a bearer token issued from the marketplace dashboard:
Authorization: Bearer <token>
The GET /v1/validators browse endpoint is anonymous. Every other
endpoint authenticates the trader (or the admin) per Design Doc
§5.2 / §9.
Idempotency
State-changing endpoints (POST /v1/leases and
POST /v1/leases/{id}/extend) require an Idempotency-Key header.
The marketplace caches the response keyed by this value for 24 hours, so
retries return the same body, with no duplicate booking.
Idempotency-Key: 01HXY...
The value must be a 26-character Crockford-base32 ULID. A missing key
returns 400 idempotency-key-missing, and a non-ULID value returns
400 idempotency-key-malformed.
Errors
All error responses use the RFC 7807 Problem Details envelope:
{
"type": "https://docs.swqos.dev/errors/lease-slot-taken",
"title": "Lease slot taken",
"status": 409,
"detail": "Another lease overlaps the requested epoch range for this validator.",
"instance": "/v1/leases"
}
The type field links back to a docs page describing the failure
class and the recommended client behaviour.