Skip to main content
The Caravanserai control plane exposes a JSON REST API served by cara-server.

​
Base URL

http://<cara-server-host>:8080/api/v1
Replace <cara-server-host> with the hostname or IP address of the machine running cara-server. The default port is 8080.

​
Request format

For endpoints that accept a body (POST, PATCH), set the Content-Type header: 
Content-Type: application/json

​
Response format

All responses — including errors — are JSON.

​
Error format

Errors follow RFC 7807 (application/problem+json) and always include title and detail fields: 
{
  "title": "Not Found",
  "detail": "node not found: worker-01",
  "status": 404,
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404"
}

​
HTTP status codes

CodeMeaning
200 OKRequest succeeded
201 CreatedResource was created successfully
202 AcceptedRequest accepted; processing continues asynchronously
204 No ContentRequest succeeded; no response body
400 Bad RequestInvalid input — check the detail field for specifics
404 Not FoundResource does not exist
409 ConflictResource already exists or has blocking dependents
500 Internal Server ErrorUnexpected server-side failure

​
Resources

The API exposes two top-level resource kinds. Nodes — physical or virtual machines running cara-agent. Nodes self-register on startup and send periodic heartbeats to report liveness and capacity. The scheduler only assigns work to nodes whose state is Ready. Projects — workload definitions composed of one or more containers (services) that must run co-located on a single node. Services share a Docker bridge network and resolve each other by service name.