API reference

The Ceryx API is a small JSON API over HTTP. Use it to add, change and remove routes, and to store your own TLS certificates. Every change applies to new requests right away, without restarting or reloading Ceryx.

This reference is generated from the OpenAPI spec for Ceryx 1.0.0. You can use the spec to generate API clients, or give it to an agent as a tool definition.

Reaching the API#

The API listens on port 8080 inside the Ceryx container. Services on the ceryx Docker network reach it at:

http://ceryx:8080

From the server running Ceryx, you can call it through the container:

docker compose -p ceryx exec ceryx curl localhost:8080/api/routes

Requests and responses#

• Request and response bodies are JSON. Send Content-Type: application/json with every request that has a body.
• Every path also accepts a trailing slash, so /api/routes and /api/routes/ are the same.
• Creating something returns 201, deleting returns 204 with no body. Deleting something that doesn't exist also returns 204, so deletes are safe to retry.

Errors#

Errors return a JSON body with a detail message:

{
  "detail": "No route found for app.example.com"
}

Endpoints#

Routes#

Certificates#

Exposing the API safely#

Keep the API reachable only by the services that manage routes:

• Leave port 8080 unpublished, as the production Compose file does. Services that need the API join the ceryx network instead.
• If a service on another machine needs the API, put it behind something that authenticates requests, such as a VPN or an authenticating proxy.
• Give agents and CI jobs access through a small service of your own that checks which hostnames they may change. See Agent environments.