API reference

The HTTP API of the Bastrel cloud, generated from the OpenAPI document of the API. The full document is openapi.json. Descriptions come from the code. The routes of the panel are not listed: they belong to the panel and are not served on the API host.

Status: the API is not deployed yet and nothing is sold (see cloud). The routes can still change before the release package.

Version: 0.1.0.

Routes for your server

Called by the Bastrel resource on your server, signed with the licence key and the secret (see licensing).

Method	Path	Description
POST	/v1/bans	Record a ban of the resource with the detections it rests on. Idempotent on ban_id.
PATCH	/v1/bans/{ban_id}	Put a ban under appeal or lift it. A lifting is final; repeating it changes nothing. Only the server that created a ban changes it (an id is drawn locally: two servers of an account may hold the same one).
GET	/v1/bans:changes	The bans of the tenant (all its servers) that changed after the cursor since.
POST	/v1/bans:lookup	Whether the references match a ban in force of another tenant that opted in. A signal.
GET	/v1/config	The config of the server, signed; 304 when the caller already holds it.
POST	/v1/detections:batch	Ingest up to 500 detections or economy transactions of the authenticated server.
POST	/v1/servers/handshake	Validate the licence, register the server and return a signed licence token.

Public routes

Without any credential; rate limited.

Method	Path	Description
GET	/v1/health	Liveness probe. Touches no dependency.
POST	/v1/public/terminations	Ask to end a subscription without signing in. Rate limited; the answer is the same whether or not the reference exists.

Webhook

Called by the payment platform from its own addresses, signed by it.

Method	Path	Description
POST	/v1/webhooks/tebex	Receive a payment-platform (Tebex) webhook.

Common errors

Every error answer is JSON with a code of the form BAS-API-NNN and a message. The table lists the statuses that any route can return; a route may also return its own business errors (for example a ban that cannot go back).

Status	Code	Meaning
401	BAS-API-006	Authentication failed (the same answer for every cause).
401	BAS-API-010	Clock skew too large; the answer carries server_time.
403	BAS-API-007	Not allowed.
403	BAS-API-011	Server limit of the plan reached, or the key is already used by another server.
404	BAS-API-003	Unknown route or resource.
405	BAS-API-004	Method not allowed.
409	BAS-API-012, BAS-API-013	A detection cited as evidence is not known; a lifted ban cannot change.
413	BAS-API-002	Request body too large.
422	BAS-API-002	The request does not match the schema.
429	BAS-API-005	Too many requests; Retry-After gives the delay.
500	BAS-API-001	Internal error.
503	BAS-API-009	Service unavailable (for example a dependency is down); nothing is granted.