# Vitalog

> An open-source, self-hosted health ledger with a dashboard, REST API and MCP.

- [Get started](https://www.vitalog.dev/quickstart.md): Install Vitalog, connect a client and record your first observation.
- [How Vitalog works](https://www.vitalog.dev/concepts.md): Understand observations, revisions, summaries, goals and client access.
- [Daily View and Weight Management](https://www.vitalog.dev/dashboard.md): View daily nutrition, mood, water, exercise and weight history.
- [Log an observation](https://www.vitalog.dev/logging.md): Use MCP or REST to write a supplied value and review the result.
- [Goals and progress](https://www.vitalog.dev/goals.md): Weight baselines, nutrition limits, water and exercise targets.
- [Record contracts](https://www.vitalog.dev/records.md): Log observations, discover schemas, read summaries and correct records.
- [Reusable attachments](https://www.vitalog.dev/attachments.md): Upload private images and PDFs once and reuse them across health records.
- [MCP setup and troubleshooting](https://www.vitalog.dev/mcp-guide.md): Connect any compatible MCP client to Vitalog's Streamable HTTP endpoint.
- [API keys](https://www.vitalog.dev/api-keys.md): Create a personal API key with explicit permissions and expiry, and manage keys and MCP connections.
- [MCP OAuth](https://www.vitalog.dev/oauth.md): Discovery, client identity, consent and authorization-code exchange.
- [MCP tools](https://www.vitalog.dev/mcp-tools.md): Tools generated from the same registry as the REST API.
- [Get context](https://www.vitalog.dev/api-reference/health-records/get-context.md): Read a bounded current snapshot with observation ages, provenance and missingness; no targets or coaching memory.
- [Get daily summary](https://www.vitalog.dev/api-reference/health-records/get-daily-summary.md): Read a local day with qualified daily-total precedence, known subtotals and completeness. Studies remain overlapping interval observations.
- [Get trends](https://www.vitalog.dev/api-reference/health-records/get-trends.md): Read up to 20 catalog metrics over at most 366 days, partitioned by supplied context. Use health_get_catalog for identifiers. No predictions.
- [List records](https://www.vitalog.dev/api-reference/health-records/list-records.md): Page through recorded observations using allowlisted dates, types and source filters; no arbitrary predicates.
- [Get record](https://www.vitalog.dev/api-reference/health-records/get-record.md): Retrieve one recorded observation and optionally a bounded page of immutable revisions.
- [Log measurements](https://www.vitalog.dev/api-reference/health-records/log-measurements.md): Save an atomic bounded batch of supplied measurement observations. Actual recorded events only. Use health_get_catalog for exact fields and units; do not infer missing values.
- [Log nutrition](https://www.vitalog.dev/api-reference/health-records/log-nutrition.md): Save one supplied nutrition observation. Actual recorded events only. Use health_get_catalog for exact fields and units; do not infer missing values.
- [Log hydration](https://www.vitalog.dev/api-reference/health-records/log-hydration.md): Save one supplied hydration observation. Actual recorded events only. Use health_get_catalog for exact fields and units; do not infer missing values.
- [Log activity](https://www.vitalog.dev/api-reference/health-records/log-activity.md): Save one supplied activity observation. Actual recorded events only. Use health_get_catalog for exact fields and units; do not infer missing values.
- [Log sleep](https://www.vitalog.dev/api-reference/health-records/log-sleep.md): Save one supplied sleep observation. Actual recorded events only. Use health_get_catalog for exact fields and units; do not infer missing values.
- [Log check-in](https://www.vitalog.dev/api-reference/health-records/log-check-in.md): Save one supplied check-in, including optional data.mood (very_low, low, neutral, good, great). Actual recorded events only. Numeric ratings remain separate. Use health_get_catalog for exact fields; do not infer missing values.
- [Log intake](https://www.vitalog.dev/api-reference/health-records/log-intake.md): Save one supplied intake observation. Actual recorded events only. Use health_get_catalog for exact fields and units; do not infer missing values.
- [Log lab results](https://www.vitalog.dev/api-reference/health-records/log-lab-results.md): Save an atomic bounded batch of supplied lab_result observations. Actual recorded events only. Use health_get_catalog for exact fields and units; do not infer missing values.
- [Correct record](https://www.vitalog.dev/api-reference/health-records/correct-record.md): Correct one record using a complete replacement and expected version. Preserve history and supplied provenance; a voided record stays voided.
- [Void record](https://www.vitalog.dev/api-reference/health-records/void-record.md): Void one record using its expected version and a reason. Exclude it from effective calculations and preserve history; this is not permanent erasure.
- [Get catalog](https://www.vitalog.dev/api-reference/catalog/get-catalog.md): Discover exact supported keys, panel memberships, nested fields, units and complete schemas. Returns code definitions independently of health data.
- [Get goal catalog](https://www.vitalog.dev/api-reference/goals/get-goal-catalog.md): Discover supported goal metrics, canonical units and fixed comparison rules. Goals are explicit user targets, separate from observed records.
- [List goals](https://www.vitalog.dev/api-reference/goals/list-goals.md): List current goals, active by default. Use health_get_goal_progress for historical goals and observed progress on a particular date.
- [Set goal](https://www.vitalog.dev/api-reference/goals/set-goal.md): Set or reactivate a user-supplied goal from today in the account timezone. Use expected_version=0 for a new metric, otherwise its current version. Weight requires an explicit baseline on creation; it is retained on edits unless supplied. No automatic recommendations.
- [Get goal](https://www.vitalog.dev/api-reference/goals/get-goal.md): Read a goal and optionally a bounded page of its immutable revisions, newest first.
- [Archive goal](https://www.vitalog.dev/api-reference/goals/archive-goal.md): Archive a goal from today with an expected version. Preserve history and previous-day progress. Reactivate with health_set_goal.
- [Get goal progress](https://www.vitalog.dev/api-reference/goals/get-goal-progress.md): Compare goals effective on a local date with qualified observed values. Unknown stays null. Nutrition uses limit utilization; water and exercise use target completion; weight uses an explicit baseline. Daily totals take precedence, gross calories are excluded, and elapsed time is never inferred as a…
- [Create attachment upload](https://www.vitalog.dev/api-reference/attachments/create-attachment-upload.md): Reserve one reusable image or PDF attachment (maximum 20 MB / 20,000,000 bytes). Supply its actual filename, MIME type, byte length and SHA-256. Send the original binary file with HTTP PUT to the returned signed URL and headers within 15 minutes; do not send ledger credentials to storage. Then call…
- [Complete attachment upload](https://www.vitalog.dev/api-reference/attachments/complete-attachment-upload.md): Verify an uploaded file's bytes, size, SHA-256 and image/PDF type, and make the attachment immutable and ready. Only ready IDs can be supplied in attachment_ids when logging or correcting any record. Reuse one ID across nutrition, measurements or a lab-results batch without uploading again. Retry fa…
- [Get attachment](https://www.vitalog.dev/api-reference/attachments/get-attachment.md): Get attachment metadata and upload state. This does not return file bytes or a download URL.
- [List attachments](https://www.vitalog.dev/api-reference/attachments/list-attachments.md): List reusable attachments with cursor pagination. Optionally filter by a record and its version; without a version, use that record's current attachments. Omitting record_id lists the ledger's attachments. No file contents or signed URLs are returned.
- [Get attachment download](https://www.vitalog.dev/api-reference/attachments/get-attachment-download.md): Get a private, signed download URL for a ready attachment, valid for five minutes. Treat the URL as sensitive temporary access and do not save it in records. Download the file outside MCP; health data and attachment metadata stay separate.
- [Create API key](https://www.vitalog.dev/api-reference/api-keys/create-api-key.md): Generate a personal API key using root credentials and required name, access, includeAdmin and expiresAt settings. Null expiry means Never. Read keys read health data; Edit keys also write it; Administrative permissions also allow operator readiness and OpenAPI inspection. Keys cannot manage credent…
- [List API keys](https://www.vitalog.dev/api-reference/api-keys/list-api-keys.md): List generated API keys, OAuth connections and browser session metadata, including expiry and revocation status. Requires the environment AUTH_KEY; never returns keys, tokens or hashes.
- [Revoke all API keys](https://www.vitalog.dev/api-reference/api-keys/revoke-all-api-keys.md): Revoke all currently unrevoked generated API keys, OAuth connections and browser sessions, including expired records, and cancel pending authorization codes. The environment AUTH_KEY is unaffected.
- [Revoke API key](https://www.vitalog.dev/api-reference/api-keys/revoke-api-key.md): Revoke a generated API key, OAuth connection or browser session by ID. Already revoked records return their metadata. Requires the environment AUTH_KEY.
- [Update browser profile](https://www.vitalog.dev/api-reference/account-settings/update-browser-profile.md): Update the root account display name using a browser session. Email and password remain environment-managed. Health records are unaffected.
- [Update browser preferences](https://www.vitalog.dev/api-reference/account-settings/update-browser-preferences.md): Save date format, time format and display time zone for the root account using a browser session. Recorded dates, daily summary boundaries and goal effective dates remain unchanged.
- [Get browser session](https://www.vitalog.dev/api-reference/browser-sessions/get-browser-session.md): Validate a browser session and read its expiry, account timezone and today's local date. Accepts a vls_ Bearer token or the API cookie from UI_BASE_URL.
- [Create browser session](https://www.vitalog.dev/api-reference/browser-sessions/create-browser-session.md): Create a revocable 30-day read-only session using root credentials. Requests from UI_BASE_URL receive a host-only HttpOnly API cookie and signed_in response; non-browser clients receive an opaque Bearer token. It cannot write records or goals, manage keys, or access MCP.
- [Revoke browser session](https://www.vitalog.dev/api-reference/browser-sessions/revoke-browser-session.md): Revoke the authenticated browser session. Accepts no body or query arguments. The environment AUTH_KEY can also revoke sessions through API-key management.
- [Get key management session](https://www.vitalog.dev/api-reference/key-management/get-key-management-session.md): Validate a key-management session and read its effective expiry. Requires a vlm_ Bearer token.
- [Create key management session](https://www.vitalog.dev/api-reference/key-management/create-key-management-session.md): Verify root credentials and issue a revocable, 30-minute session for API-key management only. Requests from UI_BASE_URL receive a host-only HttpOnly API cookie; non-browser clients receive a Bearer token. This credential cannot read or write health data, access MCP, or use the primary AUTH_KEY admin…
- [Revoke key management session](https://www.vitalog.dev/api-reference/key-management/revoke-key-management-session.md): Revoke the authenticated key-management session. Accepts no body or query arguments.
- [List managed API keys](https://www.vitalog.dev/api-reference/key-management/list-managed-api-keys.md): Using a browser or management session, list unrevoked API keys and MCP connections, filtering before pagination. Excludes dashboard and management sessions. Never returns tokens or hashes.
- [Create managed API key](https://www.vitalog.dev/api-reference/key-management/create-managed-api-key.md): Generate a personal API key using a verified management session with required name, access, includeAdmin and expiresAt settings. Null expiry means Never. Credential and account management remain browser/root-only. The complete key is returned once.
- [Revoke all managed API keys](https://www.vitalog.dev/api-reference/key-management/revoke-all-managed-api-keys.md): Revoke all API keys and MCP connections, including expired records, and cancel pending OAuth authorization codes. An optional kind filter revokes only manual keys or MCP connections. Dashboard and management sessions remain signed in. The environment AUTH_KEY is unaffected.
- [Revoke managed API key](https://www.vitalog.dev/api-reference/key-management/revoke-managed-api-key.md): Revoke one API key or MCP connection. Dashboard and management session IDs are rejected. Accepts no body or query arguments.
- [Redirect to the separate API-key creation UI](https://www.vitalog.dev/api-reference/service/redirect-to-the-separate-api-key-creation-ui.md): Redirect to the separate API-key creation UI
- [Minimal liveness](https://www.vitalog.dev/api-reference/service/minimal-liveness.md): Minimal liveness
- [Authenticated database and migration readiness](https://www.vitalog.dev/api-reference/service/authenticated-database-and-migration-readiness.md): Authenticated database and migration readiness
- [Authenticated OpenAPI document](https://www.vitalog.dev/api-reference/service/authenticated-openapi-document.md): Authenticated OpenAPI document
- [OAuth resource metadata](https://www.vitalog.dev/api-reference/oauth/oauth-resource-metadata.md): MCP OAuth authorization with CIMD, pre-registered clients and dynamic registration; see docs/oauth.md. Enabled with a canonical public issuer. Public metadata contains no health records or credentials.
- [OAuth mcp resource metadata](https://www.vitalog.dev/api-reference/oauth/oauth-mcp-resource-metadata.md): MCP OAuth authorization with CIMD, pre-registered clients and dynamic registration; see docs/oauth.md. Enabled with a canonical public issuer. Public metadata contains no health records or credentials.
- [OAuth issuer metadata](https://www.vitalog.dev/api-reference/oauth/oauth-issuer-metadata.md): MCP OAuth authorization with CIMD, pre-registered clients and dynamic registration; see docs/oauth.md. Enabled with a canonical public issuer. Public metadata contains no health records or credentials.
- [OAuth authorize](https://www.vitalog.dev/api-reference/oauth/oauth-authorize.md): MCP OAuth authorization with CIMD, pre-registered clients and dynamic registration; see docs/oauth.md. Enabled with a canonical public issuer. Public metadata contains no health records or credentials.
- [OAuth connection request](https://www.vitalog.dev/api-reference/oauth/oauth-connection-request.md): MCP OAuth authorization with CIMD, pre-registered clients and dynamic registration; see docs/oauth.md. Enabled with a canonical public issuer. Public metadata contains no health records or credentials.
- [OAuth approve](https://www.vitalog.dev/api-reference/oauth/oauth-approve.md): Requires the flow cookie, exact UI_BASE_URL Origin header and matching CSRF token. Allow signs in with ROOT_EMAIL and ROOT_PASSWORD in the JSON body and authorizes the requested scopes. Cancel does not need credentials. Returns the client-bound callback containing iss and the original state when sup…
- [OAuth exchange code](https://www.vitalog.dev/api-reference/oauth/oauth-exchange-code.md): Authorization-code exchange with S256 PKCE and exact client, consented callback and canonical MCP resource binding. Public clients use client_id without a secret; confidential clients use their declared client_secret_basic, client_secret_post or private_key_jwt method. JWT clients send a signed asse…
- [OAuth register client](https://www.vitalog.dev/api-reference/oauth/oauth-register-client.md): RFC 7591 dynamic registration for clients without a metadata document or configured client ID. Accepts HTTPS, literal loopback HTTP and reverse-domain native callbacks. Public clients explicitly use token_endpoint_auth_method=none. The default is client_secret_basic; client_secret_post and private_k…
- [Installation](https://www.vitalog.dev/installation.md): Run Vitalog's API, web app and PostgreSQL with Docker Compose.
- [Configuration](https://www.vitalog.dev/configuration.md): Configure the database, authentication, origins and runtime limits.
- [Deploy with Towbar](https://www.vitalog.dev/towbar.md): Run PostgreSQL, the API and the web app on your own server.
- [Operations and security](https://www.vitalog.dev/operations.md): Check health, apply migrations, back up PostgreSQL and protect credentials.
- [Troubleshooting](https://www.vitalog.dev/troubleshooting.md): Resolve sign-in, missing records, API errors and deployment problems.
- [Contribute to Vitalog](https://www.vitalog.dev/contributing.md): Develop locally and keep API, MCP, examples and documentation in sync.
- [An open-source health ledger](https://www.vitalog.dev/index.md): Record health observations through MCP or REST, review your day, and keep the ledger on infrastructure you control.

## OpenAPI Specs

- [openapi](/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.