MedBuk+ API reference

This reference describes API 1.15.1. New clients use the /v1 compatibility prefix. Deployment and feature availability are checked separately. Public community, campaign and capture-capability endpoints are available; protected operations require authentication and their documented permissions.

The public API base is https://medbuk-api.cenvora.dev. The reference is published at medbuk-developer.cenvora.dev; the separate user guide explains app workflows. developer.medbuk.com and docs.medbuk.com remain intended future domains.

Start with authentication

Better Auth is the sole authentication authority. Native clients send the opaque session credential as Authorization: Bearer <session-token>. Browser clients use the configured host-only cookie and same-origin gateway; cookies are not exposed to JavaScript. There is no external JWT/Logto fallback. Platform access uses email and password; corporate/merchant clients use Password or Email code. Personal mobile accounts use WhatsApp OTP. Invitations have separate inbox-verification and explicit acceptance requirements.

Protected operations derive the account from the verified token. Tenant operations also check current database membership and role; knowing a tenant ID or presenting an admin claim does not bypass those checks. Owner-only passport, capture, care and reward flows restrict impersonation as described by their contracts.

Use Content-Type: application/json for JSON request bodies. Keep tokens, private QR proofs, images and health values out of URLs and logs. Consult each generated operation for its authentication, validation and response details.

Find an operation

New account-deletion requests and general terms enforcement default off until their operational/legal gates are complete. Store a private receipt token before submitting deletion and reuse it after a timeout; completed account erasure removes the original login. When terms enforcement is enabled, protected business writes may return 428 terms_acceptance_required. Reload the published terms, obtain an explicit agreement and retry. Privacy and safety controls retain their documented access.

The sidebar contains the remaining detail, confirmation, moderation and merchant operations. Welcome campaigns can be browsed without a token; passing a valid token adds the caller's own claim status. Claim/proof and merchant actions require auth.

Handle review, retries and pagination

Photo analysis returns a draft, not a saved health reading. Read the current capability and consent notice, obtain explicit consent, then submit an analysis attempt. Save only a reviewed confirmation with storage consent. category: auto resolves to food, BP or glucose; unsupported or ambiguous inputs return capture_needs_retake. Read the resolved category before choosing a review form. Food confirmation uses either catalogue IDs or server-pinned AI draft items and reviewed portions; clients never provide authoritative calories. Device readings retain their declared source and canonical units.

Explicitly discard an unconfirmed attempt with the capture DELETE operation. Cancellation deletes its draft and evidence and prevents an in-flight result restoring them. A create request that has not reserved its ID yet can race with a 404 cancellation; retry disposal after that request settles. Confirmed records cannot be cancelled through this endpoint.

Use the endpoint's documented stable identifier and identical payload when retrying a mutation. For example, manual readings use entryId, analysis uses captureId, and welcome reservations use claimId. A timeout does not prove that nothing committed; read the existing receipt/status before creating another attempt. A changed payload can conflict with an existing identifier.

Where a response supplies nextCursor, pass it unchanged to the same operation with the same filters, then continue until it is null. Do not infer a total count or decode an opaque cursor. Rate limits and photo budgets are enforced independently of retries; handle unavailable, expired, conflict and throttled responses explicitly.

Keep reward and care proofs separate

Welcome reward QR values are opaque welcome. proofs. Their short QR expiry is separate from the reservation lease and short-code validity. Merchant validation must precede an explicit redemption action in the UI. A repeated redemption returns already_redeemed; never treat it as a second reward to fulfil.

A care QR requests patient-approved access; scanning it does not grant access to records. Follow the care request, approval, scope and expiry contracts. Neither QR belongs in a public link, analytics payload or general application log.

Understand deployment and retention boundaries

The capture capability response is the source of truth for processor availability and the current consent notice. The pilot configuration uses Astra through OpenRouter and Azure US with explicit consent, a provider allowlist, no fallback, ZDR, denied data collection and bounded request budgets. Client consent must match the advertised notice; an old food-only notice does not authorize the expanded hosted flow.

Generic push delivery is disabled pending separate configuration and verification. Welcome campaign publication is an explicit operator action; no campaign has been published in this batch. Identity-required rewards remain unavailable until real identity verification is implemented.

An accepted deletion request is queued work. The privileged processor handles live MedBuk app data and local Better Auth credentials. Its notice discloses separately retained records and backup/processor handling. The original authenticated subject cannot sign in after account erasure; new clients use the private receipt capability. This does not assert that every retained record or backup has been erased.

How this reference stays aligned

Operation pages are generated from shared Zod contracts, Fastify route schemas and OpenAPI. Edit those sources and regenerate the reference; do not hand-edit generated v1 pages. This overview only explains how to navigate and use the contracts.

API 1.15.1 is the OpenAPI version, not the private workspace package version. A breaking API change belongs under a new compatibility prefix with a published transition plan. Mobile 1.5.0 source and its monotonically increasing native build number are tracked separately. Generated documentation and passing tests do not establish production deployment, store approval or capacity certification.

Operations separation in 1.15.1

Backups and receipt maintenance run in a separate private worker. The request-serving API rejects administrator, backup and deletion credentials at startup. No new public API route or client authentication method is introduced.

Deletion scheduling is disabled by default and requires separately provisioned operator credentials and review references. An encrypted request journal supports replay into an isolated restored database; the source implementation and synthetic rehearsal do not activate production deletion or certify backup-retention policy.