Developers

Your data, your API — log events from any script or app you trust.

Sample data

Your data, your API

v1

Anything that can send an HTTP request can log events into your Faceva account: Tasker, Home Assistant, a shell script, a smart scale bridge. Create a personal API token in Settings → Developer API, then POST events to the endpoint below. Faceva never sells or shares your data — this API exists so you can build on your own mirror. Settings provides both a complete structured-data export and a separate byte-for-byte download of your stored original uploads, so you can leave with your data anytime.

The contract

POST /api/ingest/events

Authenticate with Authorization: Bearer <your token>. Send up to 500 events per request. Events are stored as manual logs with confidence 0.7 (self-asserted data, same trust as the Shortcuts bridge) and show up in Activity and the Today strip like any other log.

curl -X POST https://your-faceva-host/api/ingest/events \
  -H "Authorization: Bearer faceva_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "activity.coffee",
        "timestamp": "2026-07-12T08:30:00Z",
        "amount": 1,
        "unit": "count",
        "externalId": "coffee-2026-07-12-0830",
        "metadata": { "machine": "kitchen" }
      }
    ]
  }'

A successful call answers:

{ "accepted": 1, "remainingToday": 999 }

Event fields

Validation
typeRequired. family.name, lowercase — e.g. activity.coffee, habit.reading, drink.water. Vice and health families keep their hard privacy classification automatically.
timestampOptional ISO 8601; defaults to now. May not be more than 5 minutes in the future.
amountNumber. Check-in types (*.checkin, vice.*.urge) take an integer intensity 1–5; everything else 0–100000.
valueAlternative to amount: a number, or short text up to 120 characters. Each event needs an amount or a value.
unitOptional, 16 characters or fewer — e.g. count, ml, min.
externalIdRequired, 1–120 characters (letters, digits, . _ : -). Retries with the same externalId are deduplicated, so scripts can resend safely.
metadataOptional JSON object, up to 2000 serialized characters. Stored on the event; provenance keys (ingestPath, tokenLabel) are server-owned.

Tokens & limits

Honest numbers

Tokens are created and revoked in Settings → Developer API. They expire after 30 days (create a new one anytime), you can hold up to 5 active tokens, and each token can ingest up to 1,000 events per rolling 24-hour window. Over-limit calls answer 429; a revoked or expired token answers 401. Only a hash of your token is stored — the plaintext is shown once, at creation.

Batches over 500 events answer 413; validation problems answer 400 with the failing event index, so scripts can fix data instead of guessing.

Faceva