API overview

Base URLs, authentication, and conventions for the skcal HTTP API.

The skcal API is a typed HTTP API for nutrition, body-composition, and training tracking. The reference pages in this section are generated from the OpenAPI spec.

Base URL

https://app.skcal.fit

Authentication

Requests are scoped to the signed-in account. See Authentication for the full picture. In short:

• Apps use a Better Auth session: a cookie on the web, a bearer token in the iPhone and Android apps.
• CLI uses an OAuth token from skcal login, or an API key.
• API keys are bearer keys (Authorization: Bearer skcal_…) with optional fine-grained scopes. Create them in the app under profile → API keys.
• Agents use an OAuth 2.1 token from the MCP server.
• Scale ingest uses a shared bearer token for POST /api/ingest/weight only.

Conventions

• Requests and responses are JSON (content-type: application/json).
• Write endpoints return a minimal { "ok": true } acknowledgement unless noted.
• Errors use a consistent envelope: { "error": "reason", "detail"?: "..." }.
• Weights are stored in kilograms and measurements in centimetres; the CLI and app convert to/from pounds and inches for display.