Skip to content
Emily Get an API key

Developers

Build on your family’s Emily.

Bring the family ledger, calendar, budgets, and spending summaries into your own scripts and tools.

API access is included in your family plan, with the same subscription and beta-access rules as the app. This first version supports structured data. Chat, receipt photos, billing, and family administration are available through Emily’s app.

Make your first request

  1. Sign in as a family owner or admin.
  2. Open Settings → Developer API, name your integration, and create a key. Read-only is the default.
  3. Copy the key when it appears. Save it in your server’s secret store or a local environment variable.

The base URL is https://emilysan.net/api/v1. Self-hosted installations use their own origin.

export EMILY_API_KEY='your-key-here'
curl 'https://emilysan.net/api/v1/family' \
  -H "Authorization: Bearer $EMILY_API_KEY"

A successful response identifies the family connected to this key:

{
  "family": {
    "id": "example-family-id",
    "name": "Our family",
    "defaultCurrency": "USD",
    "locale": "en",
    "createdAt": "2026-11-16T00:00:00.000Z"
  }
}

Record an expense

Create a key with Read and write access to add or change records. This example records $12.50 using the family currency:

curl 'https://emilysan.net/api/v1/expenses' \
  -H "Authorization: Bearer $EMILY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"amountMinor":1250,"description":"Groceries"}'

Writes save immediately. Read warnings in expense responses for conversion issues. Find category and payer IDs through GET /categories and GET /members.

Use JavaScript on your server

const response = await fetch('https://emilysan.net/api/v1/expenses?limit=50&offset=0', {
  headers: { Authorization: `Bearer ${process.env.EMILY_API_KEY}` }
});
if (!response.ok) throw new Error(`Emily returned ${response.status}`);
const { expenses, count } = await response.json();

Authentication and keys

Send Authorization: Bearer emily_sk_… with every request. Each key is fixed to one family, so no family ID is needed in the URL. Cookies, query-string keys, and keys for other families do not grant access.

Choose Read-only for GET requests or Read and write for all documented operations. Only family owners and admins can create, list, and revoke keys. Any owner or admin can revoke a family key.

Emily shows a new secret once and stores only its hash. Keys have no expiry and stay valid until revoked. A family can have 10 active keys. Removing or demoting the key’s creator revokes their keys. Key revocation takes effect on the next request.

Use keys in backends, local scripts, or automation tools. Keep them out of browser code, mobile app bundles, source control, URLs, and logs. Cross-origin browser requests are not supported. To rotate a key, create a replacement, update your integration, then revoke the old key.

Data conventions

  • Money: integer minor units, never decimal amounts. 1250 USD is $12.50; 1250 JPY is ¥1,250. Non-zero amounts are limited to ±1015. Positive amounts are expenses; negative amounts are income. Income automatically uses the Income category unless you provide another.
  • Family ownership: every entry belongs to the whole family. A payer records who paid and creates no debt or split.
  • Currency: each entry preserves its original currency, stored conversion rate, and family-currency amount. fxRate converts one original-currency unit into family currency. When fxSource is none, exclude its converted amount from totals; inspect unconverted instead.
  • Dates: calendar dates use YYYY-MM-DD, event times use HH:MM, and timestamps use UTC ISO 8601. Default dates and reporting periods follow UTC. Event times have no automatic time-zone conversion.
  • Pagination: ledger lists default to 50 entries, with a maximum of 200. Increment offset by the returned length until you reach count. Lists are live, so concurrent changes can move records between pages.
  • Recurring events: listing returns occurrences with eventId. Read, edit, or delete that ID to act on the entire series. If truncated is true, query smaller date windows.
  • Updates: PATCH changes only supplied fields. Unknown input fields are rejected. POST requests are not idempotent: retrying a create can add another record. After a timeout, check for the record before retrying.

Limits and errors

Each key allows 120 requests per minute, with a combined limit of 600 per minute per family. Limits use one-minute windows on the running server. JSON bodies are limited to 1 MiB.

Authenticated responses include X-RateLimit-Limit and X-RateLimit-Remaining for the key. A 429 response includes Retry-After in seconds. Wait before retrying. A family limit can apply even when a key has requests remaining.

StatusMeaning
400Invalid fields, dates, amounts, or references.
401Missing, invalid, or revoked key.
402Family billing requires attention.
403The key is read-only and cannot perform a write.
404The record is missing or belongs to another family.
413 / 415Body too large, or a write needs application/json.
429Rate limit reached; wait the Retry-After interval.
500A server error; retry reads with backoff.
{"error":{"code":"forbidden","message":"This API key has read-only access."}}

Use the stable error.code when handling errors. Messages can follow the family’s language.

Endpoint reference

Paths below are relative to /api/v1. Download the OpenAPI 3.0 specification for request and response schemas.

Loading endpoint reference…