FOR DEVELOPERS

Connect Ovu.la to your tools.

The API is versioned, owner-scoped, and available over HTTPS only. Documentation is public and does not require an account.

HTTPS onlyJSONOwner-scoped

01 · START

Getting started

  1. Open Settings → API access in Ovu.la.
  2. Create a key and store it in a secrets manager. The full value is shown only once.
  3. Send a request with the Authorization: Bearer <token> header.
curl https://api.ovu.la/v1/me \
  -H "Authorization: Bearer <token>"

02 · AUTH

Authentication and scopes

Pass your key as Authorization: Bearer <token> or X-API-Key: <token>. Never put keys in URLs, frontend code, logs, or repositories.

profile:readdaily_logs:readdaily_logs:writedaily_logs:deletetemperature:readtemperature:writesymptoms:readsymptoms:writedata:export

Choose the smallest required set in Settings → API access. Every key requires an explicit, non-empty scope selection. Replacing a key applies the new permissions and invalidates the old key. A request missing the required scope returns 403 forbidden.

Daily-log responses include flow, notes, sexual activity, and cervical mucus by default when include is omitted. When supplied, include is the complete projection list and accepts flow, temperature, symptoms, notes, sexual_activity, and cervical_mucus; use include=flow,temperature to return only flow and temperature. Every daily-log read requires daily_logs:read; temperature and symptoms additionally require their matching read scopes. All base daily-log fields are covered by daily_logs:read and daily_logs:write, while temperature and symptom writes require their matching scopes. Unsupported or duplicate include fields are rejected.

03 · REFERENCE

Endpoints

Base URL: https://api.ovu.la. Dates use YYYY-MM-DD.

GET/healthPublic health check.
GET/v1/meProfile for the current API key.
GET/v1/me/daily-logsPaginated daily logs.
GET · PATCH · DELETE/v1/me/daily-logs/YYYY-MM-DDRead, update, or delete one daily log. The explicit delete scope authorizes deletion of the whole resource.
GET/v1/me/temperaturePaginated temperature records.
GET · PUT · DELETE/v1/me/temperature/YYYY-MM-DDRead, record, or delete one temperature.
GET/v1/me/symptomsPaginated symptom records.
GET · PUT · PATCH/v1/me/symptoms/YYYY-MM-DDRead or update one symptom record; PATCH requires both symptom read and write scopes.

04 · CONTRACT

Responses, errors, and pagination

Successful responses use data and meta.request_id. Errors include a machine-readable code, safe message, and request_id; stack traces are never returned.

List responses include next_cursor and has_more. Cursors are signed and opaque — pass them back unchanged. Requests cover up to 366 days and 500 records per page.

Write requests require an Idempotency-Key. Repeating the same request with the same key returns the stored result without applying the mutation again. Reusing the key for a different request returns 409 idempotency_conflict. Idempotency records become eligible for deletion after 24 hours and are removed by the daily cleanup job. Authenticated REST traffic is limited to 300 requests per minute per owner; excess requests return 429 rate_limited with Retry-After.

05 · SAFETY

Security requirements

  • Use HTTPS and store keys in a secrets manager.
  • Request only the scopes your integration needs.
  • Include a unique Idempotency-Key with every write.
  • Rotate or revoke keys when an integration changes.
  • Keep infrastructure secrets and signing keys server-side; never expose them to clients.