API documentation

Cordavix provides a REST API (v1) that the dashboard itself, as well as your own integrations, can use to communicate with your account and your servers.

Where to find the full reference

We maintain the full technical API reference in the repository under docs/api.md. There you will find all endpoints, request/response formats and error codes in detail.

Fundamentals

• Base URL: the relevant Cordavix API instance (e.g.

https://api.your-cordavix-instance.example).

• Response format: all responses follow the same envelope –

{ "success": true, "data": … } on success and { "success": false, "error": { "code", "message", "details?" } } on an error.

• Authentication: a signed, HttpOnly session cookie – for your own

scripts outside the browser, the API is currently not intended as an official developer product with its own API keys.

• Rate limit: 120 requests per minute and IP address; individual

sensitive endpoints (e.g. sign-in, contact) are restricted more tightly still.

Key public endpoints

These endpoints are reachable without signing in and underpin this website:

| Endpoint | Purpose | | --- | --- | | GET /api/v1/billing/plans | Public price list | | GET /api/v1/public/faq | Frequently asked questions | | GET /api/v1/public/giveaways | Public giveaway overview | | GET /api/v1/public/giveaways/:slug | Giveaway detail | | GET /api/v1/public/legal/:type | Legal documents (imprint, terms, …) | | GET /api/v1/public/status | System status | | POST /api/v1/contact | Contact form | | POST /api/v1/newsletter | Newsletter sign-up |

Authenticated endpoints (excerpt)

For your own account and your servers, the following areas are available among others (full list in docs/api.md): user profile, server management, moderation, modules, tickets, level system, economy, billing, custom bots, organisations, as well as data export and account deletion.

Error codes

Alongside general error codes such as VALIDATION_ERROR, UNAUTHORIZED or RATE_LIMITED, individual areas use their own descriptive codes (e.g. GIVEAWAY_NOT_ACTIVE, EMAIL_NOT_VERIFIED, BILLING_NOT_CONFIGURED) – these too are fully documented in docs/api.md.

Note

This API is primarily the foundation for our own dashboard. If you are planning an integration of your own, we recommend contacting us beforehand via the contact form (category "Technical problem").