Skip to content

API Reference

CertifyClouds ships its full, always-current API contract inside every running deployment. The public docs site you're reading describes what the API does at a high level; the running container is the source of truth for how to call it.

Where the live contract lives

Every CertifyClouds deployment exposes:

URL What it is
https://<your-deployment>/docs Swagger UI - interactive request/response browser. Try real calls, see exact request and response shapes, schemas, error codes.
https://<your-deployment>/redoc ReDoc - same OpenAPI spec rendered as a static reference.
https://<your-deployment>/openapi.json The raw OpenAPI 3.x spec - import into Postman, Insomnia, VS Code REST Client, or a code-generator for client SDKs.

Local development URL is http://localhost:8080/docs.

The contracts shown in /docs are generated from the running code, so they always match what the deployment actually accepts and returns - no drift between docs and reality.

Why this isn't duplicated in the public docs

We deliberately do not publish exact request / response JSON examples on this site:

  • The auto-generated /docs is byte-accurate against the version your deployment is running. Hand-written examples drift the moment a field is added, renamed, or removed.
  • Different customer deployments may be on different CC versions; their /docs reflects their version's contract, not the latest.
  • Publishing exact payload shapes turns internal field names into a stable contract we'd have to support forever even when an internal refactor would benefit customers.

Authentication

Most endpoints require a JWT bearer token. In Swagger UI:

  1. Call POST /api/auth/login with your credentials to obtain a token.
  2. Click Authorize (lock icon) and paste Bearer <token>.
  3. Subsequent requests are authenticated.

Tokens are short-lived; refresh through the standard refresh endpoint documented in the live spec.

Rate limits

CertifyClouds applies per-endpoint rate limits. Exceeding a limit returns HTTP 429 with a Retry-After header. Specific limits per endpoint are shown in the live /docs description for each route.

Stability + versioning

The API is intended to remain backwards-compatible within a CertifyClouds minor release line. Breaking changes are flagged in the release notes shipped with the deployment image, with notice and migration guidance ahead of the release that ships them.

For any single endpoint, the authoritative behaviour is whatever your deployment's /docs shows for the version you're running.

Support

If something in the live /docs doesn't match what your client receives, email support@certifyclouds.com with the endpoint path, the request you sent, and the response you got - that's a bug we want to fix.