Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Sift Family Service API
version: '1.0'
description: Service to programmatically interact with family configurations.
servers:
- url: https://api.siftstack.com
description: Production
- url: https://gov.api.siftstack.com
description: Gov
security:
- BearerAuth: []
tags:
- name: FamilyService
description: Service to programmatically interact with family configurations.
paths:
/api/v1/families:
get:
summary: ListFamilies
description: Retrieves families using an optional filter.
operationId: FamilyService_ListFamilies
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ListFamiliesResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: pageSize
description: 'The maximum number of families to return. The service may return fewer than this value, even if
there are additional pages. If unspecified, the limit defaults to 50. The maximum value is 100.'
in: query
required: false
schema:
type: integer
format: int64
- name: pageToken
description: 'A page token, received from a previous `ListFamilies` call. Provide this to retrieve the
subsequent page. When paginating, all other parameters provided to `ListFamilies` must match
the call that provided the page token.'
in: query
required: false
schema:
type: string
- name: filter
description: 'A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string.
Available fields to filter by are: `family_id`, `client_key`, `organization_id`, `archived_date`, `is_archived`, `created_by_user_id`, `created_date`, `modified_by_user_id`, `modified_date`, `name`, `description`, `run_query`, `run_id_includes`, `run_id_excludes`, `alignment_name`, `alignment_description`, `metadata`.
For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).'
in: query
required: false
schema:
type: string
- name: orderBy
description: 'How to order the retrieved families. Formatted as a comma-separated string i.e. "FIELD_NAME[ desc],...".
Available fields to order_by are: `created_date`, `modified_date`, `archived_date`.
If left empty, items are ordered by `created_date` in descending order.
For more information about the format of this field, read [this](https://google.aip.dev/132#ordering)
Example: "created_date desc"'
in: query
required: false
schema:
type: string
tags:
- FamilyService
post:
summary: CreateFamily
description: Creates a new family.
operationId: FamilyService_CreateFamily
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1CreateFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1CreateFamilyRequest'
required: true
tags:
- FamilyService
/api/v1/families/alignments/{familyAlignmentId}/points:
get:
summary: ListFamilyAlignmentPoints
description: Lists all alignment points for a specific family version alignment.
operationId: FamilyService_ListFamilyAlignmentPoints
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ListFamilyAlignmentPointsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyAlignmentId
description: Provide family_alignment_id to identify the family to list alignments points.
in: path
required: true
schema:
type: string
- name: pageSize
description: 'The maximum number of family version alignment points to return. The service may return fewer than this value, even if
there are additional pages. If unspecified, the limit defaults to 200. The maximum value is 1000.'
in: query
required: false
schema:
type: integer
format: int64
- name: filter
description: 'A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string.
Available fields to filter by are: `family_run_id`, and for the associated Run: `name`, `description`, `start_time`, `end_time`, `duration`.
Note: `name`, `description`, `start_time`, `end_time`, and `duration` are filters on the associated run.
For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).'
in: query
required: false
schema:
type: string
- name: pageToken
description: 'A page token, received from a previous `ListFamilyAlignmentPoints` call. Provide this to retrieve the
subsequent page. When paginating, all other parameters provided to `ListFamilyAlignmentPoints` must match
the call that provided the page token.'
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/candidate-runs:
get:
summary: ListFamilyCandidateRuns
description: Lists runs that match a candidate-run CEL filter. Supports `include_archived` as a CEL directive (archived runs are excluded by default; pass `include_archived == true` in the filter to include them). When `family_id` is provided, runs already on that family's persisted membership (both included and excluded) are filtered out so the response only contains runs not yet on the family.
operationId: FamilyService_ListFamilyCandidateRuns
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ListFamilyCandidateRunsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: pageSize
description: 'The maximum number of runs to return.
The service may return fewer than this value.
If unspecified, at most 50 runs will be returned.
The maximum value is 1000; values above 1000 will be coerced to 1000.'
in: query
required: false
schema:
type: integer
format: int64
- name: pageToken
description: 'A page token, received from a previous call.
Provide this to retrieve the subsequent page.
When paginating, all other parameters provided must match
the call that provided the page token.'
in: query
required: false
schema:
type: string
- name: filter
description: 'A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string.
Supports all ListRuns filter fields plus `include_archived`.
When `include_archived` is not present in the filter, archived runs are excluded by default.
Set `include_archived == true` in the filter to include archived runs.
Note: `include_archived` is a directive and must appear at the top level of the filter
(or within a top-level AND chain). It cannot be used inside an OR expression.'
in: query
required: false
schema:
type: string
- name: orderBy
description: 'How to order the retrieved runs. Formatted as a comma-separated string i.e. "FIELD_NAME[ desc],...".
Available fields to order_by are `name`, `description`, `created_date`, `modified_date`, `start_time`, and `stop_time`.
If left empty, items are ordered by `created_date` in descending order (newest-first).'
in: query
required: false
schema:
type: string
- name: familyId
description: 'Optional family ID to filter out runs already on the family''s persisted membership.
When set, the response excludes runs that are already included or excluded in the family.
Omit this field when working with draft membership changes.'
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/client_key/{clientKey}:
get:
summary: GetFamily
description: Retrieves the latest version of a family.
operationId: FamilyService_GetFamily2
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: clientKey
in: path
required: true
schema:
type: string
- name: familyId
in: query
required: false
schema:
type: string
tags:
- FamilyService
patch:
summary: UpdateFamily
description: Updates an existing family using the list of fields specified in `update_mask`.
operationId: FamilyService_UpdateFamily2
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1UpdateFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: clientKey
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
familyId:
type: string
family:
$ref: '#/components/schemas/v1FamilyDetails'
updateMask:
type: string
description: 'Note: Whenever the family is updated, the family stats are also updated to point to the new family version to ensure the family stats are always up to date.
client_key can only be updated if it is not already set. It must be passed in via the family request and cannot be used as identifier.'
required:
- family
- updateMask
required: true
tags:
- FamilyService
/api/v1/families/client_key/{clientKey}/export:
get:
summary: ExportFamily
description: Exports a family to YAML.
operationId: FamilyService_ExportFamily2
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ExportFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: clientKey
in: path
required: true
schema:
type: string
- name: familyId
in: query
required: false
schema:
type: string
- name: familyVersionId
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/client_key/{clientKey}/import-update:
patch:
summary: ImportUpdateFamily
description: Updates an existing family from YAML.
operationId: FamilyService_ImportUpdateFamily2
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ImportUpdateFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: clientKey
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
familyId:
type: string
familyYaml:
type: string
description: 'The source to update the family from. Must provide family_yaml. The contents of the source
should match the shape of UpdateFamilyRequest FamilyDetails. The update_mask is optional and defaults to updating provided fields.'
updateMask:
type: string
title: See UpdateFamilyRequest
required:
- familyYaml
required: true
tags:
- FamilyService
/api/v1/families/stat-range/name:
post:
summary: GenerateFamilyStatRangeName
description: Derives a name for a family range based on the range configuration. Nothing is persisted to the database.
operationId: FamilyService_GenerateFamilyStatRangeName
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GenerateFamilyStatRangeNameResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyAlignmentName
in: query
required: true
schema:
type: string
- name: windowStart.familyAlignmentName
in: query
required: false
schema:
type: string
- name: windowStart.duration
description: Duration relative to the alignment used to compare the data. Defaults to 0 seconds.
in: query
required: false
schema:
type: string
- name: windowEnd.familyAlignmentName
in: query
required: false
schema:
type: string
- name: windowEnd.duration
description: Duration relative to the alignment used to compare the data. Defaults to 0 seconds.
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/versions:
get:
summary: ListFamilyVersions
description: Lists all versions of a family.
operationId: FamilyService_ListFamilyVersions
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ListFamilyVersionsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: pageSize
description: 'The maximum number of family versions to return. The service may return fewer than this value, even if
there are additional pages. If unspecified, the max limit defaults to 50. The maximum value is 200.'
in: query
required: false
schema:
type: integer
format: int64
- name: filter
description: 'A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string.
Available fields to filter by are: `family_id`, `family_version_id`, `organization_id`, `name`, `description`, `run_query`, `user_notes`, `change_message`, `created_by_user_id`, `created_date`, `modified_by_user_id`, `modified_date`, `archived_date`, `is_archived`, `run_id_includes`, `run_id_excludes`, `alignment_name`, `alignment_description`.
For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).'
in: query
required: false
schema:
type: string
- name: pageToken
description: 'A page token, received from a previous `ListFamilyVersions` call. Provide this to retrieve the
subsequent page. When paginating, all other parameters provided to `ListFamilyVersions` must match
the call that provided the page token.'
in: query
required: false
schema:
type: string
- name: orderBy
description: 'How to order the retrieved family versions. Formatted as a comma-separated string i.e. "FIELD_NAME[ desc],...".
Available fields to order_by are: `created_date`, `modified_date`, `name`.
If left empty, items are ordered by `created_date` in descending order.
For more information about the format of this field, read [this](https://google.aip.dev/132#ordering)
Example: "created_date desc"'
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/versions/{familyVersionId}:
get:
summary: GetFamilyVersion
description: Retrieves a specific version of a family.
operationId: FamilyService_GetFamilyVersion
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetFamilyVersionResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyVersionId
in: path
required: true
schema:
type: string
tags:
- FamilyService
/api/v1/families/versions/{familyVersionId}/alignments:
get:
summary: ListFamilyAlignments
description: Lists all alignments for a specific family version.
operationId: FamilyService_ListFamilyAlignments
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ListFamilyAlignmentsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyVersionId
description: Provide family_id to identify the family to list alignments.
in: path
required: true
schema:
type: string
- name: pageSize
description: 'The maximum number of family version alignments to return. The service may return fewer than this value, even if
there are additional pages. If unspecified, the limit defaults to 200. The maximum value is 1000.'
in: query
required: false
schema:
type: integer
format: int64
- name: filter
description: 'A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string.
Available fields to filter by are: `name`, `description`.
For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).'
in: query
required: false
schema:
type: string
- name: pageToken
description: 'A page token, received from a previous `ListFamilyAlignments` call. Provide this to retrieve the
subsequent page. When paginating, all other parameters provided to `ListFamilyAlignments` must match
the call that provided the page token.'
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/versions/{familyVersionId}/candidate-run-count:
get:
summary: GetFamilyCandidateRunCount
description: Returns the count of candidate runs for a family version that are not already included or excluded.
operationId: FamilyService_GetFamilyCandidateRunCount
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetFamilyCandidateRunCountResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyVersionId
in: path
required: true
schema:
type: string
tags:
- FamilyService
/api/v1/families/versions/{familyVersionId}/candidate-runs:
get:
summary: GetFamilyCandidateRuns
description: Retrieves the candidate runs for a family version based on the run query stored in the family version.
operationId: FamilyService_GetFamilyCandidateRuns
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetFamilyCandidateRunsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyVersionId
in: path
required: true
schema:
type: string
tags:
- FamilyService
/api/v1/families/versions/{familyVersionId}/export:
get:
summary: ExportFamily
description: Exports a family to YAML.
operationId: FamilyService_ExportFamily3
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ExportFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyVersionId
in: path
required: true
schema:
type: string
- name: familyId
in: query
required: false
schema:
type: string
- name: clientKey
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/versions/{familyVersionId}/members:
get:
summary: ListFamilyMembers
description: Lists all members of a family version.
operationId: FamilyService_ListFamilyMembers
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ListFamilyMembersResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyVersionId
description: Provide family_version_id to identify the family to list members for.
in: path
required: true
schema:
type: string
- name: pageSize
description: 'The maximum number of family members to return. The service may return fewer than this value, even if
there are additional pages. If unspecified, the max limit defaults to 200. The maximum value is 500.'
in: query
required: false
schema:
type: integer
format: int64
- name: filter
description: 'A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string.
Available fields to filter by are: `is_exclusion`, `rationale`, `added_date`, `added_by_user_id`, `added_in_version_id`, and for the associated Run:`name`, `description`, `start_time`, `end_time`, `duration`.
Note: `name`, `description`, `start_time`, `end_time`, and `duration` are filters on the associated run.
For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).'
in: query
required: false
schema:
type: string
- name: pageToken
description: 'A page token, received from a previous `ListFamilyMembers` call. Provide this to retrieve the
subsequent page. When paginating, all other parameters provided to `ListFamilyMembers` must match
the call that provided the page token.'
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/{familyId}:
get:
summary: GetFamily
description: Retrieves the latest version of a family.
operationId: FamilyService_GetFamily
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyId
in: path
required: true
schema:
type: string
- name: clientKey
in: query
required: false
schema:
type: string
tags:
- FamilyService
patch:
summary: UpdateFamily
description: Updates an existing family using the list of fields specified in `update_mask`.
operationId: FamilyService_UpdateFamily
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1UpdateFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
clientKey:
type: string
family:
$ref: '#/components/schemas/v1FamilyDetails'
updateMask:
type: string
description: 'Note: Whenever the family is updated, the family stats are also updated to point to the new family version to ensure the family stats are always up to date.
client_key can only be updated if it is not already set. It must be passed in via the family request and cannot be used as identifier.'
required:
- family
- updateMask
required: true
tags:
- FamilyService
/api/v1/families/{familyId}/export:
get:
summary: ExportFamily
description: Exports a family to YAML.
operationId: FamilyService_ExportFamily
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ExportFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyId
in: path
required: true
schema:
type: string
- name: clientKey
in: query
required: false
schema:
type: string
- name: familyVersionId
in: query
required: false
schema:
type: string
tags:
- FamilyService
/api/v1/families/{familyId}/import-update:
patch:
summary: ImportUpdateFamily
description: Updates an existing family from YAML.
operationId: FamilyService_ImportUpdateFamily
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ImportUpdateFamilyResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
clientKey:
type: string
familyYaml:
type: string
description: 'The source to update the family from. Must provide family_yaml. The contents of the source
should match the shape of UpdateFamilyRequest FamilyDetails. The update_mask is optional and defaults to updating provided fields.'
updateMask:
type: string
title: See UpdateFamilyRequest
required:
- familyYaml
required: true
tags:
- FamilyService
/api/v1/families/{familyId}/rule-dependencies:
get:
summary: GetFamilyRuleDependencies
description: Retrieves all rules that reference the specified family across any of its stats.
operationId: FamilyService_GetFamilyRuleDependencies
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetFamilyRuleDependenciesResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: familyId
in: path
required: true
schema:
type: string
tags:
- FamilyService
/api/v1/families:batchGet:
post:
summary: GetFamilies
description: Retrieves the latest versions of multiple families.
operationId: FamilyService_GetFamilies
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetFamiliesResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
requestBody:
content:
app
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sift-stack/refs/heads/main/openapi/sift-stack-familyservice-api-openapi.yml