Safety Net Blueprint — Platform API

Cross-cutting platform services shared across all domains.

Includes the centralized event log (/events) and cross-resource search (/search). The /platform base path may be overlaid by state partners to match their own conventions.

Status: Alpha — Breaking changes expected.

Base URL: https://api.example.com/platform

Events

Centralized event log across all domains.

▶ GET /events List events #

Queryable log of all domain events across the blueprint. Supports REST polling as an integration pattern and provides permanent audit history regardless of whether a message broker is in use.

Events are returned in ascending time order (oldest first) to support cursor-based polling.

Parameters

Name Type In Req Description

▶q string query Search query using field:value syntax. Multiple conditions separated by

Search query using field:value syntax. Multiple conditions separated by spaces are ANDed together.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples in this documentation show human-readable syntax for clarity.

Syntax

Pattern	Description	Example
`term`	Full-text exact match	`john`
`term`	Full-text contains	`john`
`term*`	Full-text starts with	`john*`
`*term`	Full-text ends with	`*smith`
`field:value`	Exact match on field	`status:approved`
`field:value`	Contains (case-insensitive)	`name:john`
`field:value*`	Starts with	`name:john*`
`field:*value`	Ends with	`email:*@example.com`
`field:"value"`	Quoted value (for spaces)	`name:"john doe"`
`field.nested:value`	Nested field (dot notation)	`address.state:CA`
`field:>value`	Greater than	`income:>1000`
`field:>=value`	Greater than or equal	`income:>=1000`
`field:<value`	Less than	`income:<5000`
`field:<=value`	Less than or equal	`income:<=5000`
`field:val1,val2`	Match any value (OR)	`status:approved,pending`
`-field:value`	Exclude / negate	`-status:denied`
`field:*`	Field exists (not null)	`email:*`
`-field:*`	Field does not exist	`-deletedAt:*`

Examples

john — exact match for "john" in searchable fields
john — contains "john" in searchable fields
name:smith — name contains "smith" (case-insensitive)
email:*@example.com — email ends with "@example.com"
status:approved — exact match on status field
status:approved,pending — status is "approved" OR "pending"
income:>=1000 — income greater than or equal to 1000
created:>2024-01-01 — created after January 1, 2024
status:approved income:>=1000 — approved AND income >= 1000 (multiple conditions)
-status:denied — exclude records with status "denied"
-deletedAt:* — only records where deletedAt does not exist
applicant.state:CA — nested field filter

URL Encoding Reference

When manually constructing URLs, encode these characters:

Character	Encoded
(space)	`%20` or `+`
`"`	`%22`
`:`	`%3A`
`>`	`%3E`
`<`	`%3C`
`,`	`%2C`

Example: `` Human-readable: q=status:approved income:>=1000 URL-encoded: q=status%3Aapproved%20income%3A%3E%3D1000 ``

▶sort string query Comma-separated list of fields to sort the response by. Prefix a field

Comma-separated list of fields to sort the response by. Prefix a field with - for descending order. The first field is the primary sort; subsequent fields are tie-breakers in declaration order.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples below show human-readable syntax for clarity.

Which fields a given list endpoint allows is declared in the operation's x-sortable.fields extension. Sending a field name not present in that list returns 400 FIELD_NOT_SORTABLE. Sending a field name that doesn't exist on the resource schema returns 400 INVALID_SORT_FIELD. When this parameter is omitted, the operation's x-sortable.default (if declared) is applied; otherwise no client-driven sort is applied. A configured tie-breaker (default id) is always appended for stable pagination.

See api-patterns.yaml#sorting for the full convention and docs/architecture/x-extensions.md for the extension shape.

Syntax

Pattern	Description	Example
`fieldName`	Ascending	`sort=createdAt`
`-fieldName`	Descending	`sort=-createdAt`
`field1,field2`	Multi-field	`sort=status,-priority`
`nested.field`	Nested field via dot notation	`sort=name.lastName`

Examples

sort=createdAt — oldest first
sort=-createdAt — newest first
sort=-priority,dueDate — highest priority first, then oldest due date
sort=name.lastName,name.firstName — alphabetical by surname, then given name

type

string

query

Filter by CloudEvents type. Supports prefix matching with a trailing wildcard (e.g., intake.). When states apply an x-event-type-prefix overlay, the resolved prefix is prepended to all event types (e.g., org.example.intake.).

source

string

query

Filter by CloudEvents source (the domain that produced the event, e.g., /intake, /workflow).

subject

string

query

Filter by CloudEvents subject — the entity ID the event pertains to. Because every domain uses the same subject for the same entity, this returns a complete cross-domain timeline for that entity.

traceid

string

query

Filter by W3C Trace Context trace ID extracted from the traceparent attribute. All events sharing a trace ID were causally triggered by the same root action.

start

string

query

Return only events at or after this timestamp (ISO 8601).

end

string

query

Return only events before or at this timestamp (ISO 8601).

limit

integer

query

Maximum number of items to return (1-100).

offset

integer

query

Number of items to skip before collecting results.

Responses

200 Paginated list of CloudEvents envelopes, ordered by time ascending.

▶ EventList

total integer required Total number of items available.

limit integer required Maximum number of items requested.

offset integer required Number of items skipped before the current page.

hasNext boolean Whether more items are available beyond the current page.

▶ items array[Event] required

type string required Fully qualified CloudEvents event type following the convention {domain}.{entity}.{action} (e.g., intake.application.submitted). Must match a channel address declared in the domain's eventsSpec AsyncAPI file.

description string Human-readable annotation for state machine authors. Not a CloudEvents field.

subject string CloudEvents subject override. The entity ID the event pertains to. Defaults to the emitting resource's own id when omitted.

causationid string CloudEvents Causation extension (optional). Value expression resolving to the id of the event that directly caused this one. Use when an event is emitted in response to another event (e.g., auto-resume triggered by a timer callback).

data object Event-specific payload. Field values are value expressions resolved at emit time.

specversion string required CloudEvents specification version.

id string (uuid) required Unique event identifier.

source string required Domain base path that produced the event (e.g., /intake, /workflow).

subject string (uuid) required Entity ID the event pertains to.

time string (date-time) required When the event occurred.

datacontenttype string required Media type of the event payload.

traceparent string W3C Trace Context header (optional). Propagated from the triggering request or event. The trace ID component is stable across the full causal chain.

causationid string (uuid) CloudEvents Causation extension (optional). The `id` of the event that directly caused this one. Use when an event is emitted in direct response to another event (e.g., a task auto-resumed because a timer fired). Allows consumers to trace the immediate cause without inspecting the full distributed trace.

authid string CloudEvents Auth Context extension (optional). Principal identifier (userId from JWT claims) of the actor who triggered the event. No PII — user ID only, not name or email. Required for FTI-governed events per IRS Pub. 1075. Omitted when no caller identity is present.

authtype string CloudEvents Auth Context extension (optional). Principal type of the actor who triggered the event. Required when authid is present. Required for FTI-governed events per IRS Pub. 1075.

enumuser service_account api_key system unauthenticated unknown null

data object Event-specific payload. Schema is defined per event type in each domain's AsyncAPI file.

400 The request is malformed or contains invalid parameters.

▶ BadRequest

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

▶ POST /events Publish an event #

Publish a CloudEvents 1.0 envelope to the event log. Used by domain producers to record state transitions and significant data mutations.

Request body required

▶ Event

description string Human-readable annotation for state machine authors. Not a CloudEvents field.

subject string CloudEvents subject override. The entity ID the event pertains to. Defaults to the emitting resource's own id when omitted.

data object Event-specific payload. Field values are value expressions resolved at emit time.

specversion string required CloudEvents specification version.

id string (uuid) required Unique event identifier.

source string required Domain base path that produced the event (e.g., /intake, /workflow).

subject string (uuid) required Entity ID the event pertains to.

time string (date-time) required When the event occurred.

datacontenttype string required Media type of the event payload.

traceparent string W3C Trace Context header (optional). Propagated from the triggering request or event. The trace ID component is stable across the full causal chain.

enumuser service_account api_key system unauthenticated unknown null

data object Event-specific payload. Schema is defined per event type in each domain's AsyncAPI file.

Responses

201 Event published successfully.

▶ Event

description string Human-readable annotation for state machine authors. Not a CloudEvents field.

subject string CloudEvents subject override. The entity ID the event pertains to. Defaults to the emitting resource's own id when omitted.

data object Event-specific payload. Field values are value expressions resolved at emit time.

specversion string required CloudEvents specification version.

id string (uuid) required Unique event identifier.

source string required Domain base path that produced the event (e.g., /intake, /workflow).

subject string (uuid) required Entity ID the event pertains to.

time string (date-time) required When the event occurred.

datacontenttype string required Media type of the event payload.

traceparent string W3C Trace Context header (optional). Propagated from the triggering request or event. The trace ID component is stable across the full causal chain.

enumuser service_account api_key system unauthenticated unknown null

data object Event-specific payload. Schema is defined per event type in each domain's AsyncAPI file.

400 The request is malformed or contains invalid parameters.

▶ BadRequest

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

422 The request was well-formed but contained semantic errors.

▶ UnprocessableEntity

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

▶ GET /events/stream Stream domain events (SSE) #

Real-time stream of domain events delivered as Server-Sent Events (SSE).

Connect with Accept: text/event-stream. Each event is delivered as a data: line containing a JSON-encoded Event object.

The stream stays open until the client disconnects. A : heartbeat comment is sent every 30 seconds to prevent proxy timeouts.

Responses

200 SSE stream of domain events.

string

▶ GET /events/{eventId} Get a domain event #

Retrieve a single domain event by its identifier.

Parameters

Name	Type	In	Req	Description
eventId	string	path	✓	Unique identifier of the domain event.

Responses

200 Domain event retrieved successfully.

▶ Event

description string Human-readable annotation for state machine authors. Not a CloudEvents field.

subject string CloudEvents subject override. The entity ID the event pertains to. Defaults to the emitting resource's own id when omitted.

data object Event-specific payload. Field values are value expressions resolved at emit time.

specversion string required CloudEvents specification version.

id string (uuid) required Unique event identifier.

source string required Domain base path that produced the event (e.g., /intake, /workflow).

subject string (uuid) required Entity ID the event pertains to.

time string (date-time) required When the event occurred.

datacontenttype string required Media type of the event payload.

traceparent string W3C Trace Context header (optional). Propagated from the triggering request or event. The trace ID component is stable across the full causal chain.

enumuser service_account api_key system unauthenticated unknown null

data object Event-specific payload. Schema is defined per event type in each domain's AsyncAPI file.

404 The requested resource was not found.

▶ NotFound

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

Registry

Platform-level metadata registries shared across all domains.

▶ GET /registry/policies List policies #

Returns all regulatory citations in the platform policy registry, keyed by stable ID. Policies are shared platform-level metadata — not domain- scoped — and serve as the canonical source for annotation displays, compliance tooling, and caseworker UI.

Parameters

Name Type In Req Description

▶q string query Search query using field:value syntax. Multiple conditions separated by

Search query using field:value syntax. Multiple conditions separated by spaces are ANDed together.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples in this documentation show human-readable syntax for clarity.

Syntax

Pattern	Description	Example
`term`	Full-text exact match	`john`
`term`	Full-text contains	`john`
`term*`	Full-text starts with	`john*`
`*term`	Full-text ends with	`*smith`
`field:value`	Exact match on field	`status:approved`
`field:value`	Contains (case-insensitive)	`name:john`
`field:value*`	Starts with	`name:john*`
`field:*value`	Ends with	`email:*@example.com`
`field:"value"`	Quoted value (for spaces)	`name:"john doe"`
`field.nested:value`	Nested field (dot notation)	`address.state:CA`
`field:>value`	Greater than	`income:>1000`
`field:>=value`	Greater than or equal	`income:>=1000`
`field:<value`	Less than	`income:<5000`
`field:<=value`	Less than or equal	`income:<=5000`
`field:val1,val2`	Match any value (OR)	`status:approved,pending`
`-field:value`	Exclude / negate	`-status:denied`
`field:*`	Field exists (not null)	`email:*`
`-field:*`	Field does not exist	`-deletedAt:*`

Examples

john — exact match for "john" in searchable fields
john — contains "john" in searchable fields
name:smith — name contains "smith" (case-insensitive)
email:*@example.com — email ends with "@example.com"
status:approved — exact match on status field
status:approved,pending — status is "approved" OR "pending"
income:>=1000 — income greater than or equal to 1000
created:>2024-01-01 — created after January 1, 2024
status:approved income:>=1000 — approved AND income >= 1000 (multiple conditions)
-status:denied — exclude records with status "denied"
-deletedAt:* — only records where deletedAt does not exist
applicant.state:CA — nested field filter

URL Encoding Reference

When manually constructing URLs, encode these characters:

Character	Encoded
(space)	`%20` or `+`
`"`	`%22`
`:`	`%3A`
`>`	`%3E`
`<`	`%3C`
`,`	`%2C`

Example: `` Human-readable: q=status:approved income:>=1000 URL-encoded: q=status%3Aapproved%20income%3A%3E%3D1000 ``

limit

integer

query

Maximum number of items to return (1-100).

offset

integer

query

Number of items to skip before collecting results.

▶sort string query Comma-separated list of fields to sort the response by. Prefix a field

Comma-separated list of fields to sort the response by. Prefix a field with - for descending order. The first field is the primary sort; subsequent fields are tie-breakers in declaration order.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples below show human-readable syntax for clarity.

See api-patterns.yaml#sorting for the full convention and docs/architecture/x-extensions.md for the extension shape.

Syntax

Pattern	Description	Example
`fieldName`	Ascending	`sort=createdAt`
`-fieldName`	Descending	`sort=-createdAt`
`field1,field2`	Multi-field	`sort=status,-priority`
`nested.field`	Nested field via dot notation	`sort=name.lastName`

Examples

sort=createdAt — oldest first
sort=-createdAt — newest first
sort=-priority,dueDate — highest priority first, then oldest due date
sort=name.lastName,name.firstName — alphabetical by surname, then given name

Responses

200 Paginated list of policies.

▶ PolicyList

total integer required Total number of items available.

limit integer required Maximum number of items requested.

offset integer required Number of items skipped before the current page.

hasNext boolean Whether more items are available beyond the current page.

▶ items array[Policy] required

id string required Stable policy identifier (e.g., `snap-processing-clock`).

citation string required The regulatory citation string (e.g., "7 CFR § 273.2(g)(1)").

citationUrl string (uri) URL to the official regulatory text.

description string required Plain-language description of the regulatory requirement.

programs array[string] Programs this policy applies to.

400 The request is malformed or contains invalid parameters.

▶ BadRequest

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

▶ GET /registry/policies/{policyId} Get a policy #

Retrieve a single policy from the registry by its stable identifier.

Parameters

Name	Type	In	Req	Description
policyId	string	path	✓	Stable policy identifier (e.g., `snap-processing-clock`).

Responses

200 Policy retrieved successfully.

▶ Policy

id string required Stable policy identifier (e.g., `snap-processing-clock`).

citation string required The regulatory citation string (e.g., "7 CFR § 273.2(g)(1)").

citationUrl string (uri) URL to the official regulatory text.

description string required Plain-language description of the regulatory requirement.

programs array[string] Programs this policy applies to.

404 The requested resource was not found.

▶ NotFound

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

Search

Cross-resource search across all domains.

▶ GET /search Search across resources #

Search across all resource types (persons, cases, applications, tasks, appointments) and return a unified result list. Results include typed attributes for consistent client rendering and facet counts per resource type.

Parameters

Name Type In Req Description

▶q string query Search query using field:value syntax. Multiple conditions separated by

Search query using field:value syntax. Multiple conditions separated by spaces are ANDed together.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples in this documentation show human-readable syntax for clarity.

Syntax

Pattern	Description	Example
`term`	Full-text exact match	`john`
`term`	Full-text contains	`john`
`term*`	Full-text starts with	`john*`
`*term`	Full-text ends with	`*smith`
`field:value`	Exact match on field	`status:approved`
`field:value`	Contains (case-insensitive)	`name:john`
`field:value*`	Starts with	`name:john*`
`field:*value`	Ends with	`email:*@example.com`
`field:"value"`	Quoted value (for spaces)	`name:"john doe"`
`field.nested:value`	Nested field (dot notation)	`address.state:CA`
`field:>value`	Greater than	`income:>1000`
`field:>=value`	Greater than or equal	`income:>=1000`
`field:<value`	Less than	`income:<5000`
`field:<=value`	Less than or equal	`income:<=5000`
`field:val1,val2`	Match any value (OR)	`status:approved,pending`
`-field:value`	Exclude / negate	`-status:denied`
`field:*`	Field exists (not null)	`email:*`
`-field:*`	Field does not exist	`-deletedAt:*`

Examples

john — exact match for "john" in searchable fields
john — contains "john" in searchable fields
name:smith — name contains "smith" (case-insensitive)
email:*@example.com — email ends with "@example.com"
status:approved — exact match on status field
status:approved,pending — status is "approved" OR "pending"
income:>=1000 — income greater than or equal to 1000
created:>2024-01-01 — created after January 1, 2024
status:approved income:>=1000 — approved AND income >= 1000 (multiple conditions)
-status:denied — exclude records with status "denied"
-deletedAt:* — only records where deletedAt does not exist
applicant.state:CA — nested field filter

URL Encoding Reference

When manually constructing URLs, encode these characters:

Character	Encoded
(space)	`%20` or `+`
`"`	`%22`
`:`	`%3A`
`>`	`%3E`
`<`	`%3C`
`,`	`%2C`

Example: `` Human-readable: q=status:approved income:>=1000 URL-encoded: q=status%3Aapproved%20income%3A%3E%3D1000 ``

limit

integer

query

Maximum number of items to return (1-100).

offset

integer

query

Number of items to skip before collecting results.

types

array[string]

query

Filter results to specific resource types. When omitted, all types are searched.

Responses

200 A paginated list of search results with facet counts.

▶ SearchResultList

▶ items array[SearchResult] required

id string (uuid) required Unique identifier of the matched resource.

▶ type SearchResultType required The type of resource matched by the search.

No additional fields

title string required Display title for the result (e.g., person name, case number).

url string (uri) required Canonical API URL of the matched resource.

score number (float) Relevance score between 0 and 1. Higher is more relevant.

▶ attributes array[SearchResultAttribute] required Typed key-value pairs describing the result (e.g., status, date of birth, case number).

field string required Machine-readable field key (e.g., "dob", "status", "caseNumber").

label string Human-readable display label (e.g., "Date of Birth", "Status", "Case Number").

value string required Display value, pre-formatted as a string regardless of type.

type string required Value type hint for client rendering: - `string` — plain text (default) - `date` — date value (client may reformat) - `currency` — monetary amount (client may reformat)

enumstring date currency

createdAt string (date-time) required When the matched resource was created.

updatedAt string (date-time) required When the matched resource was last updated.

total integer required Total number of matching results across all types.

limit integer required Maximum number of results requested.

offset integer required Number of items skipped before the current page.

hasNext boolean Indicates whether more results are available beyond the current page.

▶ facets array[SearchFacet] Result counts per resource type.

▶ type SearchResultType required The type of resource matched by the search.

No additional fields

count integer required Number of matching results for this type.

400 The request is malformed or contains invalid parameters.

▶ BadRequest

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.