hzel Docs

ProgramRecord

Returned by POST /api/v1/programs, GET /api/v1/programs, and PATCH /api/v1/programs/{id}/permissions.

Field	Type	Description
`id`	`string (UUID)`	Unique program identifier.
`name`	`string`	Human-readable program name.
`description`	`string`	Description of the program's purpose.
`created_by`	`string (UUID)`	User ID of the admin who created the program.
`created_at`	`string (ISO 8601)`	UTC timestamp when the program was created.
`can_create_containers`	`boolean`	Whether accepted members of this program may provision containers.

{
  "id": "11111111-0000-0000-0000-000000000001",
  "name": "Research Cohort",
  "description": "Participants in the summer 2025 research program.",
  "created_by": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "created_at": "2025-06-01T08:00:00Z",
  "can_create_containers": true
}

ProgramDetail

Returned by GET /api/v1/programs/{id}. Contains all ProgramRecord fields (flattened via #[serde(flatten)]) plus a members array of accepted participants.

Field	Type	Description
(all `ProgramRecord` fields)		See above.
`members`	`array of ProgramMember`	Users who have accepted an invitation to this program.

Each ProgramMember:

Field	Type	Description
`user_id`	`string (UUID)`	Unique user identifier.
`email`	`string`	Email address of the member.
`display_name`	`string \| null`	Display name from the user's OIDC profile, if available.
`invited_at`	`string (ISO 8601)`	UTC timestamp when the invitation was originally sent.
`responded_at`	`string (ISO 8601) \| null`	UTC timestamp when the user accepted. `null` if not yet responded (only accepted members appear in this list).

{
  "id": "11111111-0000-0000-0000-000000000001",
  "name": "Research Cohort",
  "description": "Participants in the summer 2025 research program.",
  "created_by": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "created_at": "2025-06-01T08:00:00Z",
  "can_create_containers": true,
  "members": [
    {
      "user_id": "aaaaaaaa-0000-0000-0000-000000000001",
      "email": "bob@example.com",
      "display_name": "Bob Example",
      "invited_at": "2025-06-02T09:00:00Z",
      "responded_at": "2025-06-02T10:30:00Z"
    }
  ]
}

ProgramInvitation

Returned by POST /api/v1/programs/{id}/invite.

Field	Type	Description
`id`	`string (UUID)`	Unique invitation identifier.
`program_id`	`string (UUID)`	ID of the program the user is being invited to.
`user_id`	`string (UUID)`	ID of the invited user.
`invited_by`	`string (UUID)`	User ID of the admin who sent the invitation.
`invited_at`	`string (ISO 8601)`	UTC timestamp when the invitation was created.
`responded_at`	`string (ISO 8601) \| null`	UTC timestamp when the user responded. `null` if pending.
`response`	`string \| null`	`"accepted"` or `"declined"` once the user responds. `null` while pending.

{
  "id": "bbbbbbbb-0000-0000-0000-000000000001",
  "program_id": "11111111-0000-0000-0000-000000000001",
  "user_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "invited_by": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "invited_at": "2025-06-02T09:00:00Z",
  "responded_at": null,
  "response": null
}

Returned by GET /api/v1/programs/invitations/pending. A denormalized read model that includes program and inviter details so the user can make an informed accept/decline decision in a single request.

Field	Type	Description
`id`	`string (UUID)`	Invitation identifier. Pass this to `POST /api/v1/programs/invitations/{id}/respond`.
`program_id`	`string (UUID)`	ID of the program the invitation is for.
`program_name`	`string`	Name of the program.
`program_description`	`string`	Description of the program.
`invited_by_display_name`	`string \| null`	Display name of the admin who sent the invitation. `null` if the admin has no display name.
`invited_by_email`	`string`	Email address of the admin who sent the invitation.
`invited_at`	`string (ISO 8601)`	UTC timestamp when the invitation was sent.

{
  "id": "bbbbbbbb-0000-0000-0000-000000000001",
  "program_id": "11111111-0000-0000-0000-000000000001",
  "program_name": "Research Cohort",
  "program_description": "Participants in the summer 2025 research program.",
  "invited_by_display_name": "Alice Admin",
  "invited_by_email": "alice@example.com",
  "invited_at": "2025-06-02T09:00:00Z"
}

Program Structures

ProgramRecord

ProgramDetail

ProgramInvitation

PendingInvitationView