Racinage
Francais

Operations

APIs and connectors

Last updated 2026-07-30T20:30:47+00:00

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 publicly reachable HTTPS endpoints on port 443 when enabled resources change. Private, reserved, local, unresolved, and redirected destinations are rejected. 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.

Connected Messaging API v1

Racinage Free connects through a browser-based device flow. The desktop app never receives the hosted password, two-factor code, database credentials, or general account session. The user reviews the device on racinage.com, then the client receives short-lived scoped access and rotating refresh tokens.

  • Messaging endpoints use opaque identifiers, revisions, UTC cursors, idempotency keys, resumable file uploads, and an SSE recovery stream.
  • The desktop client encrypts cached message history and its ordered offline text/file outbox for the current Windows user.
  • Every reconnect rechecks account state, storage quota, conversation access, social blocks, and attachment policy. Rejections remain visible as conflicts.
  • Disconnecting revokes the current device token and removes its protected token from the Windows profile.

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 securityNextTroubleshooting