Operations

APIs and connectors

Last updated 2026-07-05 08:42

Family, Max, and Lifetime plans can expose selected family records through scoped CRUDSSF API keys and signed outgoing webhooks.

Access model

Enable API access from Manage > APIs & Connectors. A family manager chooses the resource scopes, then creates API keys for external tools. Super-admins can view usage, suspend a family API, revoke keys, and test webhooks from admin7839 > APIs & Connectors.

Authenticate API requests with Authorization: Bearer YOUR_API_KEY.
Keys are hashed at rest and the full key is shown only once.
Every request is limited to the key resource scopes, operation scopes, and selected family_long_id.
Existing keys stay read/search/sort/filter only. Grant create, update, or delete only to trusted integrations.
Lite plans cannot enable API access.

Resources and formats

The first API version is /api/v1. Supported resources are trees, persons, gallery, events, projects, finances, documents, history, and all.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://racinage.com/api/v1/persons?format=json"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://racinage.com/api/v1/events?format=csv"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://racinage.com/api/v1/all?format=pdf"

curl -L -H "Authorization: Bearer YOUR_API_KEY" \
  "https://racinage.com/api/v1/documents/DOCUMENT_ID/file"

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ada","last_name":"Lovelace","gender":"F"}' \
  "https://racinage.com/api/v1/persons"

curl -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"last_name":"Byron"}' \
  "https://racinage.com/api/v1/persons/PERSON_ID"

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  "https://racinage.com/api/v1/persons/PERSON_ID"

Use format=json for integrations, csv for spreadsheets, html for printable browser views, and pdf for lightweight snapshots. Media is returned as URLs; protected document files are fetched through the bearer-authenticated file endpoint.

Search, sort, and filter are query operations: ?search=Ada, ?sort=created_at&direction=asc, and ?filter[gender]=F. Gallery and document creates accept file_base64, original_name, and optional mime_type.

Continuous updates

Use Server-Sent Events for a low-overhead stream of family changes. The stream sends metadata only; fetch the record again when your integration needs full details.

curl -N -H "Authorization: Bearer YOUR_API_KEY" \
  "https://racinage.com/api/v1/events/stream"

Webhooks

Webhooks send JSON to HTTPS endpoints when enabled resources change. Verify the signature with the webhook secret and the X-Racinage-Timestamp header.

signed_payload = timestamp + "." + raw_body
expected = "sha256=" + hmac_sha256(webhook_secret, signed_payload)

Webhook headers include X-Racinage-Event, X-Racinage-Delivery, X-Racinage-Timestamp, and X-Racinage-Signature.

Developer notes

The implementation lives in includes/api_functions.php, the route is registered in core/router.php, and the production schema is documented in database/2026_07_05_api_connectors.sql. Keep future changes versioned under /api/v2 when response shape or authentication behavior becomes incompatible.

PreviousAdmin and security NextTroubleshooting