API foundations

Base URLs, sessions, response conventions, and runtime schema endpoints.

Use these endpoints to verify an instance and establish an authenticated session.

Base URL

CrossWatch serves its API from the instance URL. Routes are not versioned.

http://localhost:8787
https://crosswatch.example.com

Use HTTPS outside a trusted network.

Authentication

CrossWatch uses the HTTP-only cw_auth session cookie. Most /api/* routes require it when application authentication is enabled.

Method	Endpoint	Purpose
GET	/api/health	Return liveness and readiness.
GET	/healthz	Container health alias.
GET	/api/app-auth/status	Return authentication and session status.
POST	/api/app-auth/login	Create a local session.
POST	/api/app-auth/logout	End the current session.
POST	/api/app-auth/logout-all	End every session.
POST	/api/app-auth/logout-others	End all other sessions.
POST	/api/app-auth/credentials	Configure local credentials.

curl -sS -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"replace-me","remember_me":true}' \
  "$BASE_URL/api/app-auth/login"

Common responses

Check both the HTTP status and response body. Some operational endpoints return 200 with ok: false.

{"ok": true}

FastAPI validation failures return a detail array. Webhook behavior differs and is documented separately.

Runtime schema

Method	Endpoint	Purpose
GET	/openapi.json	Download the live OpenAPI schema.
GET	/docs	Open interactive API documentation.
GET	/redoc	Open ReDoc API documentation.
GET	/api/version	Return the application version.
GET	/api/version/check	Check the configured update source.
GET	/api/update	Return update information.

The runtime schema reflects registered routes. It can omit field details for dictionary-backed request bodies.