Versioning

The API version is in the URL (/api/v1) and in the API-Version response header.

Additive changes inside v1

These can ship at any time without a new version:

• New endpoints.
• New optional request fields.
• New fields in responses.
• New error codes.
• New values in lists that are documented as open, such as record_type.

Write your client to ignore unknown fields, and to handle an unknown error code by its HTTP status.

Breaking changes mean a new major version

These only ship in a new version, /v2:

• Removing or renaming a field or an endpoint.
• Changing a field's type.
• Making an optional field required.
• Changing authentication or error behavior.

Deprecation

When v2 ships, v1 keeps running for at least 12 months. Deprecated responses carry Deprecation and Sunset headers so you can detect them in code.

Changelog

Every API change is listed, with its date, in the API changelog. It is separate from the product changelog.

Current limits of v1

A few fields exist in the shapes but are not filled in yet, so treat them as placeholders. For example, date and record_id on events are null; use year. When a field starts carrying data, that is an additive change and will be in the changelog.

• Creating a family (POST /families) needs one or two partner_ids; child_ids are optional, and a family needs at least two people in total. The API never creates placeholder parents, so to record siblings whose parents are unknown, create a parent first. If an extra child cannot be attached, the 201 response carries a warnings array naming it; the family itself was created.
• People have a created_at but no updated_at in v1. To detect changes to a person, compare the fields you care about.