Safety Net Blueprint — Scheduling Service API

▶ GET /appointments List appointments #

Retrieve a paginated list of appointments.

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.

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

Responses

200 A paginated collection of appointments.

▶ AppointmentList

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[Appointment] required

startAt string (date-time) When the appointment begins.

endAt string (date-time) When the appointment ends.

appointmentType string Type of appointment (e.g., interview, recertification, orientation). Free-text, not enum — states define their own types.

status string Current status of the appointment. Will be driven by x-enum-source once a scheduling state machine is defined.

enumscheduled completed canceled no_show

personId string (uuid) Reference to the Person record (the subject of the appointment).

assignedToId string (uuid) Reference to the User record (staff member conducting the appointment).

notes string Free-text notes about the appointment.

id string (uuid) read-only Unique identifier (server-generated).

createdAt string (date-time) read-only Timestamp when the appointment was created.

updatedAt string (date-time) read-only Timestamp when the appointment was last updated.

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 /appointments Create an appointment #

Create a new appointment record.

Request body required

▶ AppointmentCreate

startAt string (date-time) When the appointment begins.

endAt string (date-time) When the appointment ends.

appointmentType string Type of appointment (e.g., interview, recertification, orientation). Free-text, not enum — states define their own types.

status string Current status of the appointment. Will be driven by x-enum-source once a scheduling state machine is defined.

enumscheduled completed canceled no_show

personId string (uuid) Reference to the Person record (the subject of the appointment).

assignedToId string (uuid) Reference to the User record (staff member conducting the appointment).

notes string Free-text notes about the appointment.

Responses

201 Appointment created successfully.

▶ Appointment

startAt string (date-time) When the appointment begins.

endAt string (date-time) When the appointment ends.

appointmentType string Type of appointment (e.g., interview, recertification, orientation). Free-text, not enum — states define their own types.

status string Current status of the appointment. Will be driven by x-enum-source once a scheduling state machine is defined.

enumscheduled completed canceled no_show

personId string (uuid) Reference to the Person record (the subject of the appointment).

assignedToId string (uuid) Reference to the User record (staff member conducting the appointment).

notes string Free-text notes about the appointment.

id string (uuid) read-only Unique identifier (server-generated).

createdAt string (date-time) read-only Timestamp when the appointment was created.

updatedAt string (date-time) read-only Timestamp when the appointment was last updated.

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 /appointments/{appointmentId} Get an appointment #

Retrieve a single appointment by identifier.

Parameters

Name	Type	In	Req	Description
appointmentId	string	path	✓	Unique identifier of the appointment.

Responses

200 Appointment retrieved successfully.

▶ Appointment

startAt string (date-time) When the appointment begins.

endAt string (date-time) When the appointment ends.

appointmentType string Type of appointment (e.g., interview, recertification, orientation). Free-text, not enum — states define their own types.

status string Current status of the appointment. Will be driven by x-enum-source once a scheduling state machine is defined.

enumscheduled completed canceled no_show

personId string (uuid) Reference to the Person record (the subject of the appointment).

assignedToId string (uuid) Reference to the User record (staff member conducting the appointment).

notes string Free-text notes about the appointment.

id string (uuid) read-only Unique identifier (server-generated).

createdAt string (date-time) read-only Timestamp when the appointment was created.

updatedAt string (date-time) read-only Timestamp when the appointment was last updated.

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.

▶ PATCH /appointments/{appointmentId} Update an appointment #

Apply partial updates to an existing appointment.

Parameters

Name	Type	In	Req	Description
appointmentId	string	path	✓	Unique identifier of the appointment.

Request body required

▶ AppointmentUpdate

startAt string (date-time) When the appointment begins.

endAt string (date-time) When the appointment ends.

appointmentType string Type of appointment (e.g., interview, recertification, orientation). Free-text, not enum — states define their own types.

status string Current status of the appointment. Will be driven by x-enum-source once a scheduling state machine is defined.

enumscheduled completed canceled no_show

personId string (uuid) Reference to the Person record (the subject of the appointment).

assignedToId string (uuid) Reference to the User record (staff member conducting the appointment).

notes string Free-text notes about the appointment.

Responses

200 Appointment updated successfully.

▶ Appointment

startAt string (date-time) When the appointment begins.

endAt string (date-time) When the appointment ends.

appointmentType string Type of appointment (e.g., interview, recertification, orientation). Free-text, not enum — states define their own types.

status string Current status of the appointment. Will be driven by x-enum-source once a scheduling state machine is defined.

enumscheduled completed canceled no_show

personId string (uuid) Reference to the Person record (the subject of the appointment).

assignedToId string (uuid) Reference to the User record (staff member conducting the appointment).

notes string Free-text notes about the appointment.

id string (uuid) read-only Unique identifier (server-generated).

createdAt string (date-time) read-only Timestamp when the appointment was created.

updatedAt string (date-time) read-only Timestamp when the appointment was last updated.

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.

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.

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.

▶ DELETE /appointments/{appointmentId} Delete an appointment #

Permanently remove an appointment record.

Parameters

Name	Type	In	Req	Description
appointmentId	string	path	✓	Unique identifier of the appointment.

Responses

204 Appointment deleted successfully.

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.

Appointments

Syntax

Examples

URL Encoding Reference

Syntax

Examples