{ "openapi": "3.1.0", "info": { "title": "AnyBio API", "description": "AnyBio is a healthcare SaaS platform for real-time biosignal monitoring and analysis. This API provides endpoints for managing users, organizations, projects, biosignal data ingestion, and real-time monitoring.", "contact": { "name": "AnyBio Support", "email": "support@anybiosignal.com" }, "license": { "name": "Proprietary" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.anybio.io", "description": "Production API" }, { "url": "https://api-dev.anybio.io", "description": "Development API" }, { "url": "http://localhost:8080", "description": "Local development" } ], "paths": { "/api/v1/admin/config/destructive-policy": { "get": { "tags": [ "Admin" ], "summary": "Platform-staff read of the destructive-action policy and of the caller's own\ntier.", "description": "Readable by every platform-staff tier, including `support`.", "operationId": "get_destructive_policy", "responses": { "200": { "description": "Current destructive-action policy (whether hard delete is enabled) plus the caller's platform tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestructivePolicy" } } } }, "403": { "description": "Caller holds no platform-staff standing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/episode-profiles": { "get": { "tags": [ "Admin" ], "summary": "SuperAdmin program (episode profile) listing, across organizations or\nfiltered to one.", "description": "Without `org_id` the listing spans every organization. Soft-deleted\nprograms are excluded unless `include_deleted=true`. Pagination follows\nthe admin project listing: `page` and `page_size`, or `offset` and\n`limit`, with the same bounds and precedence. The response is\n`{ data, total, has_more }`.", "operationId": "list_admin_episode_profiles", "parameters": [ { "name": "org_id", "in": "query", "description": "Optional org filter", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "include_deleted", "in": "query", "description": "Include soft-deleted rows", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page index (default 0)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Page size (1-200; default 50)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Alternative to page_size; page_size wins when both are sent", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Row offset, a multiple of the page size; alternative to page, which wins when both are sent", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated episode-profile listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEpisodeProfiles" } } } }, "400": { "description": "Invalid pagination params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/episode-profiles/{profile_id}/hard-delete": { "post": { "tags": [ "Admin" ], "operationId": "hard_delete_admin_episode_profile", "parameters": [ { "name": "profile_id", "in": "path", "description": "Episode profile id (must already be soft-deleted)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Episode profile hard-deleted" }, "403": { "description": "Hard delete is disabled on this deployment, or caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Episode profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Not soft-deleted yet (two-step gate), or enrollments still reference it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/episode-profiles/{profile_id}/restore": { "post": { "tags": [ "Admin" ], "operationId": "restore_admin_episode_profile", "parameters": [ { "name": "profile_id", "in": "path", "description": "Episode profile (program) id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Episode profile restored" }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Episode profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Conflict (live slug/handle collision, or already restored)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/orgs": { "get": { "tags": [ "Admin" ], "operationId": "list_orgs", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (clamped to [1, 200]; default 50)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Row offset for pagination", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "Sort column: name | tier | created_at (default)", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort direction: asc | desc", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated cross-org listing with rollup counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrgs" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/orgs/{org_id}": { "get": { "tags": [ "Admin" ], "summary": "One organization with the same rollup counts as the organization listing.", "operationId": "get_org", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Single org with rollup counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgListRow" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/orgs/{org_id}/projects": { "get": { "tags": [ "Admin" ], "summary": "SuperAdmin project listing for one organization.", "description": "Paginate with `page` and `page_size` (defaults 0 and 50; `page` above\n10000 or `page_size` outside 1 to 200 is a 400), or with `offset` and\n`limit` (`offset` must be a multiple of the page size). When both forms are sent, `page_size` takes precedence over\n`limit` and `page` over `offset`. The response is\n`{ data, total, has_more }`.", "operationId": "list_org_projects", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "include_deleted", "in": "query", "description": "Include soft-deleted rows", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page index (default 0)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Page size (1-200; default 50)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Alternative to page_size; page_size wins when both are sent", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Row offset, a multiple of the page size; alternative to page, which wins when both are sent", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated per-org project listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjects" } } } }, "400": { "description": "Invalid pagination params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/projects": { "get": { "tags": [ "Admin" ], "summary": "SuperAdmin project listing, across organizations or filtered to one.", "description": "Without `org_id` the listing spans every organization. Soft-deleted\nprojects are excluded unless `include_deleted=true`. Paginate with `page`\nand `page_size` (defaults 0 and 50; `page` above 10000 or `page_size`\noutside 1 to 200 is a 400), or with `offset` and `limit` (`offset` must be\na multiple of the page size). When both forms are sent, `page_size` takes precedence over `limit` and `page` over\n`offset`. The response is `{ data, total, has_more }`.", "operationId": "list_admin_projects", "parameters": [ { "name": "org_id", "in": "query", "description": "Optional org filter", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "include_deleted", "in": "query", "description": "Include soft-deleted rows", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page index (default 0)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Page size (1-200; default 50)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Alternative to page_size; page_size wins when both are sent", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Row offset, a multiple of the page size; alternative to page, which wins when both are sent", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated cross-org project listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjects" } } } }, "400": { "description": "Invalid pagination params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/projects/{project_id}": { "get": { "tags": [ "Admin" ], "operationId": "get_admin_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Project, including a soft-deleted one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "delete": { "tags": [ "Admin" ], "operationId": "soft_delete_admin_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Project soft-deleted; restorable for 30 days" }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Already soft-deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "patch": { "tags": [ "Admin" ], "operationId": "update_admin_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdatePayload" } } }, "required": true }, "responses": { "200": { "description": "Updated project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Empty body or invalid name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Project is soft-deleted; restore first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/projects/{project_id}/hard-delete": { "post": { "tags": [ "Admin" ], "operationId": "hard_delete_admin_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project id (must already be soft-deleted)", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Project hard-deleted" }, "403": { "description": "Hard delete is disabled on this deployment, or caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Not soft-deleted yet (two-step gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/projects/{project_id}/restore": { "post": { "tags": [ "Admin" ], "operationId": "restore_admin_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Project restored" }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Conflict (concurrent op or constraint)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/users/{user_id}/platform-role": { "post": { "tags": [ "Admin" ], "summary": "Grant, or change, one user's platform tier.", "description": "Root only. A root may grant any tier, including `root`, to another user but\ncannot change their own. Every grant is audited with the actor, the previous\ntier and the new one.", "operationId": "grant_platform_role", "parameters": [ { "name": "user_id", "in": "path", "description": "Target user id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantPlatformRoleBody" } } }, "required": true }, "responses": { "200": { "description": "Standing granted (or already held)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformRoleChangeResponse" } } } }, "400": { "description": "Unrecognized platform_role value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Caller is not platform root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Target user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/admin/users/{user_id}/platform-role/revoke": { "post": { "tags": [ "Admin" ], "summary": "Remove all of one user's platform standing.", "description": "Root only. Refuses with 409 when it would remove the last `root`.", "operationId": "revoke_platform_role", "parameters": [ { "name": "user_id", "in": "path", "description": "Target user id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokePlatformRoleBody" } } }, "required": true }, "responses": { "200": { "description": "Standing revoked (or already absent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformRoleChangeResponse" } } } }, "403": { "description": "Caller is not platform root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Target user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Would remove the last root", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/admin/xusers/search": { "post": { "tags": [ "Admin" ], "summary": "SuperAdmin patient listing for one `(organization, environment)`.", "description": "Returns each live patient's id, external identifier and name, at most 200\nper call, with the total that match. `q` filters by name or identifier. The\norganization and environment travel in the request body so that search\nterms never appear in a URL.", "operationId": "list_admin_xusers", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminXUsersRequest" } } }, "required": true }, "responses": { "200": { "description": "Patients in this organization and environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminXUserListResponse" } } } }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "415": { "description": "Content-Type is not application/json (plain-text body, not the standard error envelope)" }, "422": { "description": "Body is not valid JSON, or a required field is missing (plain-text body, not the standard error envelope)" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/xusers/{xuser_id}/hard-delete": { "post": { "tags": [ "Admin" ], "operationId": "hard_delete_xuser", "parameters": [ { "name": "xuser_id", "in": "path", "description": "XUser (patient) id (must already be soft-deleted)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "XUser hard-deleted" }, "403": { "description": "Hard delete is disabled on this deployment, or caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "XUser not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Not soft-deleted yet (two-step gate), or enrollments still reference it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/admin/xusers/{xuser_id}/restore": { "post": { "tags": [ "Admin" ], "operationId": "restore_xuser", "parameters": [ { "name": "xuser_id", "in": "path", "description": "XUser (patient) id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "XUser restored" }, "403": { "description": "Caller is not a SuperAdmin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "XUser not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "409": { "description": "Conflict (live unique-key collision or already restored)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/anybio/enroll/resolve": { "post": { "tags": [ "Enrollment" ], "summary": "Resolve enrollment using the platform app key. SMS opt-in is a separate,\noptional affirmative choice and cannot override an existing SMS opt-out.", "operationId": "resolve_app_enrollment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResolveResponse" } } } }, "400": { "description": "Invalid acknowledgment or input" }, "401": { "description": "Invalid platform key" }, "403": { "description": "Program enrollment is not permitted or sandbox cap reached" }, "410": { "description": "Enrollment window is closed" } }, "security": [ { "platform_app_key": [] } ] } }, "/api/v1/anybio/programs/{handle}/disclosure": { "get": { "tags": [ "Enrollment" ], "summary": "Fetch the enrollment disclosure and a separate optional SMS disclosure.", "operationId": "fetch_disclosure", "parameters": [ { "name": "handle", "in": "path", "description": "Program handle", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosurePreviewResponse" } } } }, "401": { "description": "Invalid platform key" } }, "security": [ { "platform_app_key": [] } ] } }, "/api/v1/auth/login": { "post": { "tags": [ "Authentication" ], "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginFormPayload" } } }, "required": true }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResult" }, "example": { "success": true, "message": "Login successful" } } } }, "400": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } } } }, "/api/v1/billing-periods/current-period": { "get": { "tags": [ "Billing Periods" ], "operationId": "list_current_periods", "parameters": [ { "name": "project_id", "in": "query", "description": "Restrict to live enrollments in this project. 404 when the project is\nnot in this org + environment.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "episode_profile_id", "in": "query", "description": "Restrict to live enrollments in this program. 404 when the program is\nnot in this org + environment.", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Page size (default 100, max 500).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset (default 0).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "The current period per live enrollment with its pace, behind-but-reachable first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentPeriodListingResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden: signed-in staff only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project or program not found in this environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/billing-periods/enrollments/{enrollment_id}/order-reference": { "patch": { "tags": [ "Billing Periods" ], "operationId": "set_order_reference", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "Enrollment id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetOrderReferenceBody" } } }, "required": true }, "responses": { "200": { "description": "The stored order reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderReferenceResponse" } } } }, "400": { "description": "Over-long reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden: signed-in staff only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Enrollment not found in this environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/billing-periods/patients/{xuser_id}": { "get": { "tags": [ "Billing Periods" ], "operationId": "list_patient_periods", "parameters": [ { "name": "xuser_id", "in": "path", "description": "Patient id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Every enrollment ledger for the patient in the active environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientBillingPeriodsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden: signed-in staff only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/billing-periods/programs/{episode_profile_id}/patients": { "get": { "tags": [ "Billing Periods" ], "operationId": "list_program_patients", "parameters": [ { "name": "episode_profile_id", "in": "path", "description": "Program (episode profile) id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period_index", "in": "query", "description": "Select this period (1-based) for every enrollment.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "from", "in": "query", "description": "Select periods overlapping [from, to]. Either bound alone selects the\nsingle day. Ignored when `period_index` is given.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "limit", "in": "query", "description": "Page size (default 100, max 500).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "description": "Page offset (default 0).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "One row per (patient, period) for the program and selection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramBillingPeriodsResponse" } } } }, "400": { "description": "Bad selection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden: signed-in staff only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Program not found in this environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/care-handoffs": { "get": { "tags": [ "Care handoffs" ], "operationId": "list", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "sort", "in": "query", "description": "created (oldest first, default) or due (earliest first, unset last).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "xuser_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "overdue", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffList" } } } }, "403": { "description": "" } } } }, "/api/v1/care-handoffs/{id}": { "get": { "tags": [ "Care handoffs" ], "operationId": "detail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "events_before", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffDetail" } } } }, "403": { "description": "" }, "404": { "description": "" } } } }, "/api/v1/care-handoffs/{id}/claim": { "post": { "tags": [ "Care handoffs" ], "operationId": "claim", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } } } }, "/api/v1/care-handoffs/{id}/contact-attempt": { "post": { "tags": [ "Care handoffs" ], "operationId": "contact_attempt", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" }, "422": { "description": "" } } } }, "/api/v1/care-handoffs/{id}/resolve": { "post": { "tags": [ "Care handoffs" ], "operationId": "resolve", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" }, "422": { "description": "" } } } }, "/api/v1/care-handoffs/{id}/resume": { "post": { "tags": [ "Care handoffs" ], "operationId": "resume", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" }, "422": { "description": "" } } } }, "/api/v1/developer-keys": { "get": { "tags": [ "Developer" ], "summary": "List all active developer keys for the authenticated user's organization.", "operationId": "list_developer_keys", "responses": { "200": { "description": "List of developer keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperKeyResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "post": { "tags": [ "Developer" ], "summary": "Create a new developer key for the authenticated user's organization.", "operationId": "create_developer_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeveloperKeyPayload" } } }, "required": true }, "responses": { "201": { "description": "Developer key created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKeyResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/developer-keys/{key_id}/revoke": { "post": { "tags": [ "Developer" ], "summary": "Revoke a developer key that belongs to the user's organization.", "operationId": "revoke_developer_key", "parameters": [ { "name": "key_id", "in": "path", "description": "Developer key ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Developer key revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKeyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Developer key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/episode-profiles/{id}/baseline": { "put": { "tags": [ "Program measures" ], "summary": "Record the program's baseline period, replacing any earlier one. Each\nwrite is audited with the period it replaced.", "operationId": "record_baseline", "parameters": [ { "name": "id", "in": "path", "description": "Program (episode profile) id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBaselineRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramBaseline" } } } }, "400": { "description": "Period empty, inverted or longer than the maximum" }, "403": { "description": "Caller is not an organization admin or an Admin key" }, "404": { "description": "No such live program in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/episode-profiles/{id}/digest-schedule": { "get": { "tags": [ "Program digests" ], "operationId": "get_schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "403": { "description": "" }, "404": { "description": "" } } }, "put": { "tags": [ "Program digests" ], "operationId": "put_schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "No patient messaging routing policy in this environment" }, "422": { "description": "Cadence out of bounds" } } }, "delete": { "tags": [ "Program digests" ], "operationId": "delete_schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "The program sends no digest" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/api/v1/episode-profiles/{id}/digests": { "get": { "tags": [ "Program digests" ], "operationId": "list_digests", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Most recent first; 1 to 100, default 20.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigestList" } } } }, "403": { "description": "" }, "404": { "description": "" } } } }, "/api/v1/episode-profiles/{id}/measures": { "get": { "tags": [ "Program measures" ], "summary": "The four measures over a window and over the program's baseline.", "operationId": "program_measures", "parameters": [ { "name": "id", "in": "path", "description": "Program (episode profile) id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Inclusive start, RFC 3339 with a `Z` offset (a `+` offset must be percent-encoded); default thirty days before `to`", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Exclusive end, RFC 3339 with a `Z` offset (a `+` offset must be percent-encoded); default the instant the report is computed", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramMeasuresReport" } } } }, "400": { "description": "Window empty, inverted or longer than the maximum" }, "403": { "description": "Caller is not an organization admin or an Admin key" }, "404": { "description": "No such program in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/episodes": { "get": { "tags": [ "Episodes" ], "operationId": "list_episodes", "parameters": [ { "name": "xuser_id", "in": "query", "description": "XUser ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum number of episodes to return", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Number of episodes to skip", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of episodes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EpisodeDto" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/episodes/{id}": { "get": { "tags": [ "Episodes" ], "operationId": "get_episode", "parameters": [ { "name": "id", "in": "path", "description": "Episode ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Episode details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Episode not found" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications": { "get": { "tags": [ "Govern" ], "operationId": "list_applications", "responses": { "200": { "description": "Applications in the caller's organization and environment", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationDto" } } } } }, "403": { "description": "Requires an organization admin session or an Admin developer key" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "post": { "tags": [ "Govern" ], "summary": "Create an application and mint its first key.", "operationId": "create_application", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApplicationRequest" } } }, "required": true }, "responses": { "201": { "description": "Application created; the key secret appears only here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApplicationResponse" } } } }, "400": { "description": "Invalid name, channel, project scope or webhook URL" }, "403": { "description": "Requires an organization admin session or an Admin developer key" }, "409": { "description": "An application with this name already exists in this environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}": { "get": { "tags": [ "Govern" ], "operationId": "get_application", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationDto" } } } }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "patch": { "tags": [ "Govern" ], "summary": "Patch an application. A change to the default mode or to any channel's\nmode is an audited event with the actor and the previous and new mode.", "operationId": "patch_application", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchApplicationRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationDto" } } } }, "400": { "description": "Invalid name, channel, project scope or webhook URL" }, "404": { "description": "No such application in this organization and environment" }, "409": { "description": "An application with this name already exists in this environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}/keys": { "get": { "tags": [ "Govern" ], "operationId": "list_application_keys", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Key metadata, newest first; never a secret", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationKeyDto" } } } } }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}/keys/rotate": { "post": { "tags": [ "Govern" ], "summary": "Rotate the application's key: mint a new one and give the previous keys an\noverlap window, after which they are refused.", "operationId": "rotate_application_key", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Optional; defaults to a one-day overlap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateKeyBody" } } }, "required": true }, "responses": { "201": { "description": "New key minted; the secret appears only here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateKeyResponse" } } } }, "400": { "description": "overlap_seconds out of range" }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}/observe-report": { "get": { "tags": [ "Govern" ], "summary": "The observe report: counts by decision, policy and channel over a window,\nwould-have separated from enforced.", "operationId": "observe_report", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Inclusive start, RFC 3339; default fourteen days before `to`", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Exclusive end, RFC 3339; default now", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObserveReport" } } } }, "400": { "description": "Window empty, inverted or longer than the maximum" }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}/observe-report.csv": { "get": { "tags": [ "Govern" ], "summary": "The observe report as a CSV of the buckets its counts were summed from.", "operationId": "observe_report_csv", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Inclusive start, RFC 3339; default fourteen days before `to`", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Exclusive end, RFC 3339; default now", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One line per (policy, version, channel, mode, source, status, outcome) bucket, with `would_have` and `enforced` in columns of their own", "content": { "text/csv": {} } }, "400": { "description": "Window empty, inverted or longer than the maximum" }, "403": { "description": "Requires an organization admin session or an Admin developer key" }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}/observe-report.pdf": { "get": { "tags": [ "Govern" ], "summary": "The observe report as a PDF the account holder sends to a reviewer.", "operationId": "observe_report_pdf", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Inclusive start, RFC 3339; default fourteen days before `to`", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Exclusive end, RFC 3339; default now", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The report as a document carrying the organization, the application, the environment, the window, the generation time, and the policy name and version behind each count", "content": { "application/pdf": {} } }, "400": { "description": "Window empty, inverted or longer than the maximum" }, "403": { "description": "Requires an organization admin session or an Admin developer key" }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}/patients": { "delete": { "tags": [ "Govern" ], "summary": "Purge every patient's state and ledger for an application (retention, or\nthe end of the relationship). Decision records are untouched.", "operationId": "purge_application_patients", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeResponse" } } } }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/applications/{application_id}/webhook-secret/rotate": { "post": { "tags": [ "Govern" ], "summary": "Replace the application's webhook signing secret. The new secret is in\nthis response only; deliveries attempted from now on are signed with it.", "operationId": "rotate_webhook_secret", "parameters": [ { "name": "application_id", "in": "path", "description": "Application id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Rotated; the secret appears only here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintedWebhookSecret" } } } }, "403": { "description": "Requires an organization admin session or an Admin developer key" }, "404": { "description": "No such application in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/decisions/{decision_id}": { "get": { "tags": [ "Govern" ], "summary": "The decision with its review state; the first hold-resolution path.", "operationId": "get_decision", "parameters": [ { "name": "decision_id", "in": "path", "description": "Decision id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionView" } } } }, "403": { "description": "Not an application key" }, "404": { "description": "No such decision for this application" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/decisions/{decision_id}/outcome": { "post": { "tags": [ "Govern" ], "summary": "Report what was delivered for a decision. One outcome per decision: a\nreplay that says the same thing is `200`, one that differs is `409`.", "operationId": "record_outcome", "parameters": [ { "name": "decision_id", "in": "path", "description": "Decision id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeRequest" } } }, "required": true }, "responses": { "200": { "description": "The same outcome was already recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionView" } } } }, "201": { "description": "Outcome recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionView" } } } }, "400": { "description": "Invalid hash or delivery reference, or delivered without a hash" }, "403": { "description": "Not an application key" }, "404": { "description": "No such decision for this application" }, "409": { "description": "A different outcome is already recorded" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/disclosures": { "post": { "tags": [ "Govern" ], "summary": "Record the AI-identity disclosure shown at the start of a conversation.\nOnce per conversation; a second call returns the same evidence with `200`.", "operationId": "record_disclosure", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordDisclosureRequest" } } }, "required": true }, "responses": { "200": { "description": "The conversation's evidence already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureView" } } } }, "201": { "description": "Evidence recorded; attach `ref` on every evaluate for the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureView" } } } }, "400": { "description": "Blank or oversized text, or an invalid conversation id" }, "403": { "description": "Not an application key, or a key not bound to the named application" }, "503": { "description": "The evidence could not be recorded; retry" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/evaluate": { "post": { "tags": [ "Govern" ], "summary": "Evaluate one turn of the application's AI output.", "description": "Enforce answers inline (`200`); observe accepts (`202`) and evaluates off\nthe request path; a channel that is `off` answers `200` with\n`status = not_evaluated`. A replay of a `turn_id` returns the stored\ndecision. `Idempotency-Key`, when sent, must equal `turn_id`.", "operationId": "evaluate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateRequest" } } }, "required": true }, "responses": { "200": { "description": "Decided inline (enforce), replayed, or not evaluated (channel off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionView" } } } }, "202": { "description": "Accepted (observe); evaluated off the request path, poll the decision id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionView" } } } }, "400": { "description": "Invalid identifiers, content, metadata, or an audience not allowed on the channel" }, "403": { "description": "Not an application key, or a key not bound to the named application" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/handoffs": { "get": { "tags": [ "Govern" ], "summary": "The application-scoped hand-offs of the organization and environment.", "operationId": "list_handoffs", "parameters": [ { "name": "application_id", "in": "query", "description": "Staff may narrow to one application; a key is always its own", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "queued | claimed | resolved", "required": false, "schema": { "type": "string" } }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "overdue", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "created (default) | due", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffList" } } } }, "403": { "description": "Not an application key or a staff session of the organization" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/handoffs/{handoff_id}": { "get": { "tags": [ "Govern" ], "summary": "One hand-off with its events and the decisions that opened or joined it.\nThe inbound text is on this staff-and-application surface only.", "operationId": "handoff_detail", "parameters": [ { "name": "handoff_id", "in": "path", "description": "Hand-off id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalHandoffDetail" } } } }, "403": { "description": "Not an application key or a staff session of the organization" }, "404": { "description": "No such external hand-off in this organization and environment" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/govern/handoffs/{handoff_id}/claim": { "post": { "tags": [ "Govern" ], "summary": "Claim the hand-off. `expected_version` must be the current version.", "operationId": "claim_handoff", "parameters": [ { "name": "handoff_id", "in": "path", "description": "Hand-off id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "403": { "description": "Staff only, and only staff the routing names" }, "404": { "description": "" }, "409": { "description": "The hand-off changed; refresh before acting" } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/govern/handoffs/{handoff_id}/contact-attempt": { "post": { "tags": [ "Govern" ], "summary": "Record a contact attempt on a claimed hand-off.", "operationId": "contact_handoff", "parameters": [ { "name": "handoff_id", "in": "path", "description": "Hand-off id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "400": { "description": "Missing outcome, note, or next due time" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/govern/handoffs/{handoff_id}/resolve": { "post": { "tags": [ "Govern" ], "summary": "Resolve a claimed hand-off.", "operationId": "resolve_handoff", "parameters": [ { "name": "handoff_id", "in": "path", "description": "Hand-off id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "400": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/govern/handoffs/{handoff_id}/resume": { "post": { "tags": [ "Govern" ], "summary": "Release the hold on a resolved hand-off.", "operationId": "resume_handoff", "parameters": [ { "name": "handoff_id", "in": "path", "description": "Hand-off id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CareHandoff" } } } }, "400": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } }, "security": [ { "session_cookie": [] } ] } }, "/api/v1/govern/patients/consent": { "post": { "tags": [ "Govern" ], "summary": "Record consent granted or revoked for a patient of the key's application.", "operationId": "record_patient_consent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRequest" } } }, "required": true }, "responses": { "200": { "description": "The patient's current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientStateView" } } } }, "400": { "description": "Invalid patient reference" }, "403": { "description": "Not an application key" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/patients/opt-out": { "post": { "tags": [ "Govern" ], "summary": "Record a patient opting out, or back in. An opt-out the patient typed\n(STOP in their inbound message) cannot be undone here.", "operationId": "record_patient_opt_out", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOutRequest" } } }, "required": true }, "responses": { "200": { "description": "The patient's current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientStateView" } } } }, "400": { "description": "Invalid patient reference" }, "403": { "description": "Not an application key" }, "409": { "description": "The patient opted out in their own words; only a START from the patient opts them back in" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/patients/state": { "post": { "tags": [ "Govern" ], "summary": "The patient's state. A POST so the reference travels in the body, never\nin a path that a request log keeps.", "operationId": "read_patient_state", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientStateRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientStateView" } } } }, "400": { "description": "Invalid patient reference" }, "403": { "description": "Not an application key" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/transcripts": { "post": { "tags": [ "Govern" ], "summary": "Post a batch of past turns for observe-only evaluation. The batch is\nvalidated whole (nothing is stored if any turn is refused), held as a job,\nand processed off the request path; poll the job id. `Idempotency-Key`,\nwhen sent, replays the job it opened.", "operationId": "submit_transcripts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptBatch" } } }, "required": true }, "responses": { "200": { "description": "Replayed: a job with this Idempotency-Key already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptJobView" } } } }, "202": { "description": "Accepted; the job is being processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptJobView" } } } }, "400": { "description": "An empty or oversized batch, a repeated turn_id, an invalid turn, or a sent_at in the future" }, "403": { "description": "Not an application key, or a key not bound to the named application" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/transcripts/{job_id}": { "get": { "tags": [ "Govern" ], "summary": "A transcript job's status and counts.", "operationId": "transcript_job", "parameters": [ { "name": "job_id", "in": "path", "description": "Transcript job id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptJobView" } } } }, "403": { "description": "Not an application key" }, "404": { "description": "No such job for this application" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/transcripts/{job_id}/turns": { "get": { "tags": [ "Govern" ], "summary": "The turns of a transcript job in batch order, each with the decision it\nproduced or matched. Never the text.", "operationId": "transcript_job_turns", "parameters": [ { "name": "job_id", "in": "path", "description": "Transcript job id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptTurnView" } } } } }, "403": { "description": "Not an application key" }, "404": { "description": "No such job for this application" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/govern/webhook-deliveries": { "get": { "tags": [ "Govern" ], "summary": "The webhook delivery log for the key's application: newest first, at most\ntwo hundred. Filter by `decision_id`, `handoff_id`, `status`.", "operationId": "list_webhook_deliveries", "parameters": [ { "name": "decision_id", "in": "query", "description": "Only deliveries about this decision", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "handoff_id", "in": "query", "description": "Only deliveries about this hand-off", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "pending | delivered | exhausted | skipped", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryView" } } } } }, "403": { "description": "Not an application key" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/ingest/session/start": { "post": { "tags": [ "Ingest" ], "operationId": "start_session", "parameters": [ { "name": "resume_if_active", "in": "query", "description": "Resume if active session exists", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartBody" } } }, "required": true }, "responses": { "200": { "description": "Resumed existing session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartResp" } } } }, "201": { "description": "Session started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartResp" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden" }, "409": { "description": "Active session already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartConflictResp" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/ingest/sessions": { "get": { "tags": [ "Ingest" ], "operationId": "list_sessions", "parameters": [ { "name": "xuser_id", "in": "query", "description": "Filter by XUser ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "description": "Filter by project ID", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "Maximum number of sessions to return", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Number of sessions to skip", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "paginated", "in": "query", "description": "Return the {data,total,has_more} envelope instead of a bare array. Required to paginate meaningfully: without a total, a `limit` is a silent truncation.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated sessions, when ?paginated=true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSessions" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/ingest/sessions/{session_id}": { "get": { "tags": [ "Ingest" ], "summary": "Get a single session by id.", "operationId": "get_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Ingest session ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListItem" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Session not found" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/ingest/sessions/{session_id}/decode-issues": { "get": { "tags": [ "Ingest" ], "summary": "List the chunk-level decode problems of a session.", "description": "Which chunks had a problem, what kind, and the detail recorded at the time.\nAlways paginated.", "operationId": "get_session_decode_issues", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Chunk-level decode problems, worst kind first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedChunkIssues" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Session not found" } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List all organizations (SuperAdmin only).", "operationId": "list_organizations", "responses": { "200": { "description": "List of all organizations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Permission denied - SuperAdmin only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/organizations/{id}": { "get": { "tags": [ "Organizations" ], "summary": "Get one organization.", "operationId": "get_organization", "parameters": [ { "name": "id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "patch": { "tags": [ "Organizations" ], "summary": "Update an organization. Only the fields present change.", "operationId": "update_organization", "parameters": [ { "name": "id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/patient-messaging-policy": { "get": { "tags": [ "Patient messaging" ], "operationId": "get_policy", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "403": { "description": "Staff session required" } } }, "put": { "tags": [ "Patient messaging" ], "operationId": "put_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagingPolicy" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "400": { "description": "Invalid configuration" }, "403": { "description": "Organization admin required" } } } }, "/api/v1/patient-messaging-policy/programs/{episode_profile_id}": { "get": { "tags": [ "Patient messaging" ], "operationId": "get_program_allowance", "parameters": [ { "name": "episode_profile_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramAllowanceResponse" } } } }, "403": { "description": "Staff session required" }, "404": { "description": "No live program with this id in the organization and environment" } } }, "put": { "tags": [ "Patient messaging" ], "operationId": "put_program_allowance", "parameters": [ { "name": "episode_profile_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageAllowance" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramAllowanceResponse" } } } }, "400": { "description": "Invalid allowance" }, "403": { "description": "Organization admin required" }, "404": { "description": "No live program with this id in the organization and environment" } } }, "delete": { "tags": [ "Patient messaging" ], "operationId": "delete_program_allowance", "parameters": [ { "name": "episode_profile_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The organization policy governs this program's sends again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramAllowanceResponse" } } } }, "403": { "description": "Organization admin required" }, "404": { "description": "No live program with this id in the organization and environment" } } } }, "/api/v1/patient-messaging-policy/staff": { "get": { "tags": [ "Patient messaging" ], "operationId": "list_staff", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffResponse" } } } }, "403": { "description": "Staff session required" } } } }, "/api/v1/projects": { "get": { "tags": [ "Projects" ], "operationId": "list_projects", "responses": { "200": { "description": "List of projects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "post": { "tags": [ "Projects" ], "operationId": "create_project", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPayload" } } }, "required": true }, "responses": { "201": { "description": "Project created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/projects/{project_id}": { "get": { "tags": [ "Projects" ], "operationId": "get_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Project details with organization API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWithOrgKey" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "delete": { "tags": [ "Projects" ], "operationId": "delete_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Project soft-deleted; restorable for 30 days" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "403": { "description": "Delete not permitted via developer key or SDK token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "patch": { "tags": [ "Projects" ], "operationId": "update_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdatePayload" } } }, "required": true }, "responses": { "200": { "description": "Project updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/projects/{project_id}/users": { "get": { "tags": [ "Projects" ], "operationId": "get_project_users", "parameters": [ { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "List of users in project", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/XUser" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "post": { "tags": [ "Projects" ], "operationId": "assign_users_to_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAssignmentPayload" } } }, "required": true }, "responses": { "200": { "description": "Users assigned successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "delete": { "tags": [ "Projects" ], "operationId": "unassign_users_from_project", "parameters": [ { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAssignmentPayload" } } }, "required": true }, "responses": { "200": { "description": "Users unassigned successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/public/biosignals": { "get": { "tags": [ "Biosignals" ], "summary": "List the full biosignal catalog.", "description": "Public and unauthenticated. The response is the same for every caller and\nmay be cached.", "operationId": "list_public_biosignals", "responses": { "200": { "description": "Full biosignal catalog (public, CDN-cacheable)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBiosignalDto" } } } } } } } }, "/api/v1/users/{xuser_id}/projects": { "get": { "tags": [ "Projects" ], "operationId": "get_user_projects", "parameters": [ { "name": "xuser_id", "in": "path", "description": "XUser ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of projects for user", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/xusers": { "get": { "tags": [ "XUsers" ], "operationId": "list_xusers", "parameters": [ { "name": "project_id", "in": "query", "description": "Filter by project ID", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "List of xusers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/XUser" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "post": { "tags": [ "XUsers" ], "operationId": "create_xuser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XUserPayload" } } }, "required": true }, "responses": { "200": { "description": "XUser already exists. Shaped like the patient record so a client that decodes one type from both 200 and 201 keeps working, but it carries NO stored patient data beyond the resolved id: `identifier` and `name` are echoed from the request and the remaining fields are fixed values. This route is create-or-GET and never updates an existing patient; use PATCH /api/v1/xusers/{xuser_id} to change one, and GET /api/v1/xusers/{xuser_id} to read one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XUserResolvedResponse" } } } }, "201": { "description": "XUser created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XUserFullResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/api/v1/xusers/{xuser_id}": { "get": { "tags": [ "XUsers" ], "operationId": "get_xuser", "parameters": [ { "name": "xuser_id", "in": "path", "description": "XUser ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "description": "Scope stats to project", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "XUser details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XUserFullResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "XUser not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "delete": { "tags": [ "XUsers" ], "operationId": "delete_xuser", "parameters": [ { "name": "xuser_id", "in": "path", "description": "XUser ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "XUser soft-deleted; restorable for 30 days" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "XUser not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] }, "patch": { "tags": [ "XUsers" ], "operationId": "patch_xuser", "parameters": [ { "name": "xuser_id", "in": "path", "description": "XUser ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XUserUpdatePayload" } } }, "required": true }, "responses": { "200": { "description": "XUser updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XUser" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } }, "404": { "description": "XUser not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponseError" } } } } }, "security": [ { "session_cookie": [] }, { "bearer_token": [] } ] } }, "/fhir/ContactPoint": { "get": { "tags": [ "FHIR" ], "operationId": "list_contact_points", "parameters": [ { "name": "xuser_id", "in": "query", "description": "xuser ID to fetch FHIR ContactPoints for", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get FHIR ContactPoints", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactPoint" } } } } } } } } }, "components": { "schemas": { "AdminEpisodeProfileRow": { "type": "object", "description": "One program (episode profile) in the admin program listing: identity,\nlifecycle status and soft-delete state.", "required": [ "id", "org_id", "environment_id", "slug", "name", "status", "category", "created_at", "updated_at" ], "properties": { "category": { "type": "string" }, "created_at": { "type": "string" }, "deleted_at": { "type": [ "string", "null" ], "description": "RFC 3339 tombstone timestamp; `null` for a live program." }, "environment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "org_id": { "type": "integer", "format": "int32" }, "program_handle": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ], "format": "int32" }, "slug": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" } } }, "AdminProjectWithOrg": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "type": "object", "properties": { "organization_compliance_tier": { "type": [ "string", "null" ] }, "organization_name": { "type": [ "string", "null" ] }, "organization_tier": { "type": [ "string", "null" ] } } } ], "description": "A project with its organization's name, tier and compliance tier. The\nproject's own fields are at the top level." }, "AdminXUserListItem": { "type": "object", "description": "One patient in the admin patient listing: id, external identifier and name.", "required": [ "id", "identifier", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The patient's id." }, "identifier": { "type": "string", "description": "The customer-supplied external identifier (MRN, enrollment code and so\non). PHI." }, "name": { "type": "string", "description": "The patient's display name. PHI." } } }, "AdminXUserListResponse": { "type": "object", "description": "A patient listing capped at 200 rows. `total` counts every patient that\nmatches the same filter, so `truncated` shows when the cap applied; narrow\nwith `q` to reach the rest.", "required": [ "items", "total", "truncated" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminXUserListItem" } }, "total": { "type": "integer", "format": "int64", "description": "How many patients match the filter in this organization and environment,\nbefore the cap.", "minimum": 0 }, "truncated": { "type": "boolean", "description": "True when `items` is shorter than `total`." } } }, "AppError": { "oneOf": [ { "type": "object", "required": [ "NotFoundError" ], "properties": { "NotFoundError": { "type": "string" } } }, { "type": "object", "required": [ "NotAvailableError" ], "properties": { "NotAvailableError": { "$ref": "#/components/schemas/Resource" } } }, { "type": "object", "required": [ "ResourceExistsError" ], "properties": { "ResourceExistsError": { "$ref": "#/components/schemas/Resource" } } }, { "type": "object", "required": [ "PermissionDeniedError" ], "properties": { "PermissionDeniedError": { "type": "string" } } }, { "type": "object", "required": [ "UserNotActiveError" ], "properties": { "UserNotActiveError": { "type": "string" } } }, { "type": "object", "required": [ "InvalidSessionError" ], "properties": { "InvalidSessionError": { "type": "string" } } }, { "type": "object", "required": [ "ConflictError" ], "properties": { "ConflictError": { "type": "string" } } }, { "type": "object", "required": [ "UnauthorizedError" ], "properties": { "UnauthorizedError": { "type": "string" } } }, { "type": "object", "required": [ "BadRequestError" ], "properties": { "BadRequestError": { "type": "string" } } }, { "type": "object", "required": [ "GoneError" ], "properties": { "GoneError": { "type": "string" } } }, { "type": "object", "required": [ "ServiceUnavailableError" ], "properties": { "ServiceUnavailableError": { "type": "string" } } }, { "type": "object", "required": [ "RateLimitError" ], "properties": { "RateLimitError": { "type": "string" } } }, { "type": "object", "required": [ "InvalidPayloadError" ], "properties": { "InvalidPayloadError": { "type": "string" } } }, { "type": "object", "required": [ "HashError" ], "properties": { "HashError": { "type": "string" } } }, { "type": "object", "required": [ "TracingInitError" ], "properties": { "TracingInitError": { "type": "string" } } }, { "type": "object", "required": [ "InvalidInputError" ], "properties": { "InvalidInputError": { "type": "string" } } }, { "type": "object", "required": [ "DatabaseError" ], "properties": { "DatabaseError": { "type": "string" } } }, { "type": "object", "required": [ "WebSocketError" ], "properties": { "WebSocketError": { "type": "string" } } }, { "type": "object", "required": [ "IoError" ], "properties": { "IoError": { "type": "string" } } }, { "type": "object", "required": [ "UuidError" ], "properties": { "UuidError": { "type": "string" } } }, { "type": "object", "required": [ "JwtError" ], "properties": { "JwtError": { "type": "string" } } }, { "type": "object", "required": [ "HttpClientError" ], "properties": { "HttpClientError": { "type": "string" } } }, { "type": "object", "required": [ "RedisError" ], "properties": { "RedisError": { "type": "string" } } }, { "type": "object", "required": [ "ConfigError" ], "properties": { "ConfigError": { "type": "string" } } }, { "type": "object", "required": [ "SmtpError" ], "properties": { "SmtpError": { "type": "string" } } }, { "type": "object", "required": [ "LetterError" ], "properties": { "LetterError": { "type": "string" } } }, { "type": "object", "required": [ "ParseJsonError" ], "properties": { "ParseJsonError": { "type": "string" } } }, { "type": "object", "required": [ "ParseFloatError" ], "properties": { "ParseFloatError": { "type": "string" } } }, { "type": "object", "required": [ "AddrParseError" ], "properties": { "AddrParseError": { "type": "string" } } }, { "type": "object", "required": [ "SpawnTaskError" ], "properties": { "SpawnTaskError": { "type": "string" } } }, { "type": "object", "required": [ "TeraError" ], "properties": { "TeraError": { "type": "string" } } }, { "type": "object", "required": [ "Base64Error" ], "properties": { "Base64Error": { "type": "string" } } }, { "type": "object", "required": [ "StrumParseError" ], "properties": { "StrumParseError": { "type": "string" } } }, { "type": "object", "required": [ "SystemTimeError" ], "properties": { "SystemTimeError": { "type": "string" } } }, { "type": "object", "required": [ "AxumError" ], "properties": { "AxumError": { "type": "string" } } }, { "type": "object", "required": [ "UnknownError" ], "properties": { "UnknownError": { "type": "string" } } }, { "type": "object", "required": [ "Infallible" ], "properties": { "Infallible": { "type": "string" } } }, { "type": "object", "required": [ "TypeHeaderError" ], "properties": { "TypeHeaderError": { "type": "string" } } }, { "type": "object", "required": [ "FromEnvError" ], "properties": { "FromEnvError": { "type": "string" } } } ], "example": { "kind": "INVALID_INPUT_ERROR", "error_message": "email: not a valid email\n", "code": null, "details": [ [ "email", "not a valid email" ] ] } }, "AppResponseError": { "type": "object", "description": "The error body returned by the API.\n\n`kind` names the error class and `error_message` describes it. `details` is\nan array of two-element arrays (`[[\"email\", \"not a valid email\"]]`),\nnon-empty only for invalid-input and resource-exists errors. `code` is\n`null` except for the few errors that name a resource type.", "required": [ "kind", "error_message", "details" ], "properties": { "code": { "type": [ "integer", "null" ], "format": "int32" }, "details": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "string" }, { "type": "string" } ] } }, "error_message": { "type": "string" }, "kind": { "type": "string" } }, "example": { "kind": "NOT_FOUND_ERROR", "error_message": "Project not found", "code": null, "details": [] } }, "ApplicationDto": { "type": "object", "required": [ "id", "organization_id", "environment_id", "name", "default_mode", "channel_policies", "red_flag_categories", "frequency_cap_unreadable", "consent_required_channels", "created_at", "updated_at" ], "properties": { "channel_policies": { "type": "object", "description": "Per-channel overrides, keyed by `sms` | `app_message` | `web_chat` |\n`voice` | `email`.", "additionalProperties": { "$ref": "#/components/schemas/ChannelPolicy" }, "propertyNames": { "type": "string" } }, "consent_required_channels": { "type": "array", "items": { "type": "string" }, "description": "Which channels require a `granted` consent on record: each channel's\ndefault with this application's overrides applied. Read-only.\n`channel_policies` names only the overrides." }, "created_at": { "type": "string", "format": "date-time" }, "default_mode": { "$ref": "#/components/schemas/GovernMode" }, "environment_id": { "type": "string", "format": "uuid" }, "frequency_cap": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FrequencyCap", "description": "The per-patient message cap per fixed window, if any." } ] }, "frequency_cap_unreadable": { "type": "boolean", "description": "True when the stored cap cannot be read. The cap then holds every turn\n(fail-closed), so `frequency_cap: null` alone would read as \"no cap\"\nwhile the gate is holding everything." }, "handoff_routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RoutingPolicy", "description": "The routing hand-offs opened for this application's patients are given;\n`null` opens them on the organization's default queue." } ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "integer", "format": "int32" }, "project_id": { "type": [ "integer", "null" ], "format": "int32", "description": "Policy scope; `null` is the organization-level active policy." }, "red_flag_categories": { "type": "array", "items": { "type": "string" }, "description": "The red-flag categories the inbound screen runs with." }, "updated_at": { "type": "string", "format": "date-time" }, "webhook_secret_hint": { "type": [ "string", "null" ], "description": "The last four characters of the webhook signing secret." }, "webhook_secret_rotated_at": { "type": [ "string", "null" ], "format": "date-time" }, "webhook_url": { "type": [ "string", "null" ] } } }, "ApplicationKeyDto": { "type": "object", "description": "Key metadata. Never the hash, never the secret.", "required": [ "id", "application_id", "key_hint", "created_at" ], "properties": { "application_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set by rotation: when this key stops authenticating." }, "id": { "type": "string", "format": "uuid" }, "key_hint": { "type": "string", "description": "The last four characters of the secret, for telling keys apart." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BillingPeriodConfigDto": { "type": "object", "description": "The program configuration that produced the tiers in a response. Echoed so\na non-default program stays legible: the label vocabulary is fixed, the\nthresholds are not.", "required": [ "period_days", "tier_low_min_days", "tier_high_min_days", "anchor" ], "properties": { "anchor": { "type": "string", "description": "`enrollment` or `first_transmission`." }, "period_days": { "type": "integer", "format": "int32" }, "tier_high_min_days": { "type": "integer", "format": "int32" }, "tier_low_min_days": { "type": "integer", "format": "int32" } } }, "BrandingDto": { "type": "object", "required": [ "display_name", "primary_color", "secondary_color", "accent_color", "tone", "copy_overrides" ], "properties": { "accent_color": { "type": "string" }, "copy_overrides": {}, "display_name": { "type": "string" }, "logo_url": { "type": [ "string", "null" ] }, "primary_color": { "type": "string" }, "secondary_color": { "type": "string" }, "tone": { "type": "string" } } }, "CareHandoff": { "type": "object", "required": [ "id", "organization_id", "environment_id", "reason", "state", "queue_label", "pauses_automation", "version", "created_at", "updated_at" ], "properties": { "application_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The Govern application whose patient this hand-off is about." }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "automation_resumed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The hold survives resolution until a person explicitly releases it." }, "claimed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "disposition": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "environment_id": { "type": "string", "format": "uuid" }, "episode_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The episode the hand-off was opened from, fixed at creation. Null for\nhand-offs opened without an episode." }, "escalated_at": { "type": [ "string", "null" ], "format": "date-time" }, "escalation_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "integer", "format": "int32" }, "patient_ref_hash": { "type": [ "string", "null" ], "description": "SHA-256 of the customer's opaque patient reference; never the reference." }, "pauses_automation": { "type": "boolean", "description": "Whether this item also pauses automated messaging to its subject.\nMessaging is paused while `automation_resumed_at` is null and\n`pauses_automation` is true. A red flag, an exhausted message budget, a\nmissing policy, an unknown delivery outcome and a route-to-human decision\nall pause; an item that only owes the patient a reply does not." }, "queue_label": { "type": "string" }, "reason": { "type": "string" }, "resolution_note": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ], "format": "uuid" }, "routing_snapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "state": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32" }, "xuser_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The patient record this hand-off is about. Null for a hand-off opened\nthrough Govern for a patient of the customer's application, which has no\npatient record here; `application_id` and `patient_ref_hash` then name\nthe subject. Every hand-off has exactly one subject." } } }, "CareHandoffEvent": { "type": "object", "required": [ "id", "handoff_id", "organization_id", "environment_id", "event_type", "source_key", "evidence", "created_at" ], "properties": { "actor_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "environment_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "evidence": { "$ref": "#/components/schemas/Value" }, "handoff_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "note": { "type": [ "string", "null" ] }, "organization_id": { "type": "integer", "format": "int32" }, "source_key": { "type": "string" } } }, "ChannelBreakdown": { "allOf": [ { "$ref": "#/components/schemas/Counts" }, { "type": "object", "required": [ "channel" ], "properties": { "channel": { "type": "string" } } } ] }, "ChannelPolicy": { "type": "object", "description": "A per-channel binding: the policy scope, the mode, and the consent\nrequirement for one channel. Any field absent means \"the default for this\nchannel\".", "properties": { "mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GovernMode" } ] }, "project_id": { "type": [ "integer", "null" ], "format": "int32", "description": "The project whose active policy decides this channel; `null` means the\napplication's `project_id`." }, "requires_consent": { "type": [ "boolean", "null" ], "description": "Whether an outbound turn on this channel requires a `granted` consent on\nrecord. Absent means the channel default: required for `sms`, `voice` and\n`email`, not required for `app_message` and `web_chat`." } } }, "ChunkIssueRow": { "type": "object", "description": "One chunk's recorded decode problem, for the per-chunk list.", "required": [ "ingest_chunk_id", "ingest_device_id", "chunk_sequence", "outcome", "detected_at" ], "properties": { "bytes_decoded": { "type": [ "integer", "null" ], "format": "int32" }, "bytes_in": { "type": [ "integer", "null" ], "format": "int32" }, "chunk_sequence": { "type": "integer", "format": "int32", "description": "The device's own sequence number for this chunk." }, "detail": { "type": [ "string", "null" ] }, "detected_at": { "type": "string", "format": "date-time" }, "frames": { "type": [ "integer", "null" ], "format": "int32" }, "ingest_chunk_id": { "type": "string", "format": "uuid" }, "ingest_device_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string" }, "packets": { "type": [ "integer", "null" ], "format": "int32" }, "samples": { "type": [ "integer", "null" ], "format": "int64" } } }, "ConfidenceDetails": { "type": "object", "description": "Per-episode data-quality assessment. Reserved: no episode carries one at\npresent.", "required": [ "level", "explanation", "coverage_score", "ingest_session_score", "data_quality_score" ], "properties": { "coverage_percentage": { "type": [ "number", "null" ], "format": "double" }, "coverage_score": { "type": "number", "format": "double" }, "data_quality_score": { "type": "number", "format": "double" }, "explanation": { "type": "string" }, "ingest_session_score": { "type": "number", "format": "double" }, "level": { "type": "string" } } }, "ConsentRequest": { "type": "object", "description": "`POST /api/v1/govern/patients/consent`. The reference travels in the body,\nnever in a path, so it is never in a request log.", "required": [ "patient_ref", "state" ], "properties": { "at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the patient granted or revoked; default now." }, "channel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GovernChannel" } ] }, "patient_ref": { "type": "string" }, "state": { "$ref": "#/components/schemas/ConsentState" } } }, "ConsentState": { "type": "string", "enum": [ "granted", "revoked" ] }, "ContactPoint": { "type": "object", "description": "A patient's phone number or email address.", "required": [ "id", "xuser_id", "system", "value", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the contact point was deleted; null while it is live. A deleted\ncontact point is hidden from every read, and the patient can add the same\nvalue again." }, "id": { "type": "integer", "format": "int32" }, "rank": { "type": [ "integer", "null" ], "format": "int32" }, "system": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "use_field": { "type": [ "string", "null" ] }, "value": { "type": "string", "description": "The phone number or email address. PHI." }, "xuser_id": { "type": "string", "format": "uuid" } } }, "ContactRequest": { "type": "object", "required": [ "expected_version", "outcome", "note" ], "properties": { "expected_version": { "type": "integer", "format": "int32" }, "next_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "note": { "type": "string" }, "outcome": { "type": "string" } } }, "ContactTimeMeasure": { "allOf": [ { "$ref": "#/components/schemas/MeasureAbout" }, { "type": "object", "properties": { "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContactTimes", "description": "`null` when the program has no baseline recorded." } ] }, "period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContactTimes" } ] } } } ] }, "ContactTimes": { "type": "object", "description": "Measure 1 over one period.", "required": [ "occurrences", "contacted", "awaiting_contact" ], "properties": { "awaiting_contact": { "type": "integer", "format": "int64" }, "contacted": { "type": "integer", "format": "int64" }, "median_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Median over the contacted occurrences, whole seconds; `null` when none\nwas contacted." }, "occurrences": { "type": "integer", "format": "int64" } } }, "Counts": { "type": "object", "description": "Counts keyed by the raw gate decision (`allow`, `rewrite`,\n`block_and_review`, `policy_missing`, `unavailable`) for observe turns, and\nby the binding answer (`allow`, `hold`, `block`) for enforce turns.", "required": [ "would_have", "enforced" ], "properties": { "enforced": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "would_have": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } } } }, "CreateApplicationRequest": { "type": "object", "required": [ "name" ], "properties": { "channel_policies": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/ChannelPolicy" }, "propertyNames": { "type": "string" } }, "default_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GovernMode" } ] }, "frequency_cap": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FrequencyCap", "description": "The per-patient message cap per fixed window; none by default." } ] }, "handoff_routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RoutingPolicy", "description": "The routing a hand-off opened for this application's patients is given:\nqueue label, primary and backup staff, response and\nescalation seconds. Staff must be members of the organization." } ] }, "name": { "type": "string" }, "project_id": { "type": [ "integer", "null" ], "format": "int32" }, "red_flag_categories": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The red-flag categories the inbound screen runs with (`cardiac`,\n`respiratory`, `neuro_stroke`, `self_harm`). Default: all four." }, "webhook_url": { "type": [ "string", "null" ] } } }, "CreateApplicationResponse": { "type": "object", "required": [ "application", "key", "webhook_secret" ], "properties": { "application": { "$ref": "#/components/schemas/ApplicationDto" }, "key": { "$ref": "#/components/schemas/MintedKeyDto" }, "webhook_secret": { "$ref": "#/components/schemas/MintedWebhookSecret", "description": "The webhook signing secret, shown here once." } } }, "CreateDeveloperKeyPayload": { "type": "object", "required": [ "scope" ], "properties": { "description": { "type": [ "string", "null" ], "example": "API key for production mobile app" }, "name": { "type": [ "string", "null" ], "example": "Production API Key" }, "scope": { "$ref": "#/components/schemas/DeveloperKeyScope", "description": "Scope for the key (read, write, admin). Required field." } } }, "CurrentPeriodListingResponse": { "type": "object", "description": "The current period per live enrollment, with pace.", "required": [ "environment_id", "as_of", "count", "total", "rows", "omitted" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "The instant the listing was evaluated at." }, "count": { "type": "integer", "description": "Rows on this page.", "minimum": 0 }, "environment_id": { "type": "string", "format": "uuid" }, "episode_profile_id": { "type": [ "string", "null" ], "format": "uuid" }, "omitted": { "type": "array", "items": { "$ref": "#/components/schemas/OmittedEnrollmentDto" }, "description": "Live enrollments in the selection with no current period yet (a\nfirst-transmission anchor waiting for a reading)." }, "project_id": { "type": [ "integer", "null" ], "format": "int32", "description": "The scopes that produced `rows`, echoed." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramPeriodRowDto" }, "description": "One row per live enrollment with a current period. Sorted\n`behind_reachable` first, then `not_reachable`, then `on_pace`; within\na state, fewest days remaining first. `period.pace_state` and the\nother pace fields are always present on these rows." }, "total": { "type": "integer", "description": "Rows across all pages.", "minimum": 0 } } }, "DecidedBy": { "type": "string", "description": "Which stage produced a decision. `stage_one` is the deterministic gate;\n`stage_two` and `timeout` are reserved values.", "enum": [ "stage_one", "stage_two", "timeout" ] }, "DecisionStatus": { "type": "string", "enum": [ "pending", "decided", "unavailable", "not_evaluated" ] }, "DecisionView": { "type": "object", "description": "The decision as the contract presents it, from `evaluate` and from the\npoll. `released_content` and `deliverable_content` are the only fields that\ncan carry message text, and each does so under a stated condition.", "required": [ "status", "decision", "mode", "channel", "audience", "conversation_id", "turn_id", "reasons", "detected_claims", "disclosure_required", "send_holding_line", "retryable", "route_to_human", "would_have_routed", "inbound_flags", "webhook_deliveries" ], "properties": { "audience": { "$ref": "#/components/schemas/GovernAudience" }, "channel": { "$ref": "#/components/schemas/GovernChannel" }, "conversation_id": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "decision": { "$ref": "#/components/schemas/GovernDecision" }, "decision_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Absent only when the channel is `off`." }, "deliverable_content": { "type": [ "string", "null" ], "description": "Clinician audience only: the gate's term substitution, when there is\none to deliver. Never present for a patient audience." }, "detected_claims": { "type": "array", "items": { "type": "string" } }, "disclosure_required": { "type": "boolean" }, "handoff": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HandoffRef", "description": "The hand-off this decision opened or joined, with its current state." } ] }, "inbound_flags": { "type": "array", "items": { "$ref": "#/components/schemas/InboundFlag" }, "description": "The red-flag rules the inbound matched; rule ids and categories only." }, "mode": { "$ref": "#/components/schemas/GovernMode" }, "model": { "type": [ "string", "null" ], "description": "The model the caller named for this turn, and its version. Null when the caller named none; never inferred." }, "model_version": { "type": [ "string", "null" ] }, "outcome": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutcomeView", "description": "What the customer reported delivering, once it has." } ] }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolicyRef" } ] }, "rationale": { "type": [ "string", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "released_content": { "type": [ "string", "null" ], "description": "Present once a reviewer released the held content: what to deliver." }, "retry_of": { "type": [ "string", "null" ], "format": "uuid", "description": "The decision this turn retries, when it is a retry. Null otherwise." }, "retryable": { "type": "boolean", "description": "Your application may write ONE new draft for this turn and evaluate\nit with `retry_of` set to this `decision_id`.\n\n`true` only when this turn was stopped in enforce mode, for a patient,\nbecause of the draft's own content (the `reasons` name a clinical\nclaim the program may not make, or a missing disclaimer), the stop\nclass is `uncertain`, the policy does not review every send, and the\nhold is still pending. It is `false` for a `never_sendable` stop, for\nevery stop about the patient rather than the draft (an opt-out, a\nconsent, a frequency cap, a missing disclosure), for a missing policy,\nfor a turn that is itself a retry at the platform's limit, for a turn\nwhose inbound routed the patient to a person, and once a reviewer has\nacted. Add the `reasons` and the policy's rules to your\nmodel's instructions; this service never writes the new draft." }, "review_state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReviewState" } ] }, "review_url": { "type": [ "string", "null" ], "description": "Console deep link for the customer's own reviewers, present when the\ndecision is in (or has been through) the review queue." }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "route_to_human": { "type": "boolean", "description": "A person must contact this patient. Independent of\n`decision`: a clean draft can be `allow` with `route_to_human: true`,\nand a violating one `hold` with it." }, "send_holding_line": { "type": "boolean", "description": "Send your holding line to this patient now.\n\nThis turn was stopped and the patient is waiting on a reply, so your\napplication sends the fixed text your clinical owner wrote: that a person\nwill reply, when, and what to do if it is urgent. This field says when to\nsend it; the text is yours and this service does not send it.\n\n`false` when the turn was stopped because the patient should not be\nmessaged at all (an opt-out, a missing or revoked consent, a frequency\ncap), and always `false` in observe. Each stopped turn carries its own\nanswer.\n\nOn a `retryable` turn this is still `true`: a caller that retries sends\nthe retry first and the holding line only if the retry is stopped too,\nso the patient never gets a holding line followed by an answer." }, "status": { "$ref": "#/components/schemas/DecisionStatus" }, "stop_class": { "type": [ "string", "null" ], "description": "Which of the two stopped classes this turn is: `never_sendable` or\n`uncertain`; null when nothing was stopped.\n\nIn enforce it describes the `hold` the caller received. A\n`never_sendable` turn cannot be released, so reviewers record a\nreplacement instead. In observe it is read beside `would_have` and\ndescribes what the stop would have been." }, "turn_id": { "type": "string" }, "webhook_deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryView" }, "description": "The signed webhook deliveries about this decision: the\nlog, never the body." }, "would_have": { "type": [ "string", "null" ], "description": "Observe: the raw gate decision (`allow` | `rewrite` | `block_and_review`\n| `policy_missing`) or `unavailable`. Null in enforce." }, "would_have_routed": { "type": "boolean", "description": "Observe: the screen matched and would have routed; no task was opened." } } }, "DecodeReport": { "type": "object", "description": "Per-device decode tally, derived from the chunk ledger.", "required": [ "total_chunks", "chunks_ok", "chunks_with_issues", "chunks_not_attempted", "by_outcome" ], "properties": { "by_outcome": { "type": "object", "description": "Counts by outcome (`hard`, `corrupt`, `partial`, `unmatched`, `empty`),\nkeyed in a stable order.", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "chunks_not_attempted": { "type": "integer", "format": "int64", "description": "Chunks decoding never reached: neither a failure nor a success. A run\nthat ended early leaves these behind." }, "chunks_ok": { "type": "integer", "format": "int64", "description": "Decode ran and produced usable output. DERIVED as\n`total - issues - not_attempted`, because the ledger holds only\nexceptions and a clean chunk has no row to count." }, "chunks_with_issues": { "type": "integer", "format": "int64", "description": "Chunks carrying a recorded decode finding, whatever its kind." }, "total_chunks": { "type": "integer", "format": "int64", "description": "Chunks ingest stored for this device." } } }, "DestructivePolicy": { "type": "object", "description": "The destructive-action policy and the caller's own platform tier.", "required": [ "hard_delete_enabled" ], "properties": { "hard_delete_enabled": { "type": "boolean", "description": "True when hard delete is enabled on this deployment. When false, every\nhard-delete route answers 403." }, "platform_role": { "type": [ "string", "null" ], "description": "The caller's own platform tier (`support`, `operator` or `root`), or null\nif they hold none. Informational: every admin route enforces the tier\nitself.", "example": "root" } } }, "DeveloperKey": { "type": "object", "required": [ "id", "organization_id", "environment_id", "key_hash", "scope", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "environment_id": { "type": "string", "format": "uuid" }, "id": { "type": "integer", "format": "int32" }, "key_encrypted": { "type": [ "string", "null" ] }, "key_hash": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "type": "integer", "format": "int32" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "scope": { "$ref": "#/components/schemas/DeveloperKeyScope" } } }, "DeveloperKeyResponse": { "type": "object", "required": [ "id", "organization_id", "environment_id", "scope", "created_at", "key_prefix" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "environment_id": { "type": "string", "format": "uuid", "description": "The environment (sandbox, production or clinical) the key is scoped to." }, "id": { "type": "integer", "format": "int32" }, "key": { "type": [ "string", "null" ], "description": "The actual key - only returned on creation, never stored or retrieved again", "example": "org_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" }, "key_prefix": { "type": "string", "description": "Prefix of the key for identification (e.g., \"org_a1b2c3...\")", "example": "org_a1b2c3..." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "type": "integer", "format": "int32" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "scope": { "$ref": "#/components/schemas/DeveloperKeyScope" } } }, "DeveloperKeyScope": { "type": "string", "description": "Developer key scopes define what operations the key can perform", "enum": [ "read", "write", "admin", "sdk" ] }, "Digest": { "type": "object", "description": "One recorded digest, as the staff console reads it.", "required": [ "id", "episode_profile_id", "period_start", "period_end", "cadence_hours", "missed_periods", "definitions_version", "all_clear", "reasons", "counts", "scheduled_work", "patient_refs", "delivery_status", "created_at" ], "properties": { "all_clear": { "type": "boolean" }, "cadence_hours": { "type": "integer", "format": "int32" }, "counts": { "$ref": "#/components/schemas/DigestCounts" }, "created_at": { "type": "string", "format": "date-time" }, "definitions_version": { "type": "string" }, "delivery_status": { "type": "string", "description": "`pending`, `sent`, `no_recipients`, `failed` or `withdrawn`." }, "episode_profile_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "missed_periods": { "type": "integer", "format": "int32", "description": "Digests that did not go out on schedule before this one; this one\ncovers their periods too." }, "patient_refs": { "$ref": "#/components/schemas/PatientRefs", "description": "Narrowed on read to patients who are still live in this environment, so\na deleted patient's id never comes back through a digest. That makes\nthese lists SHORTER than the matching `counts` once a patient has been\ndeleted: the counts are what the period was, the references are who can\nstill be looked up." }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": { "type": "string" } }, "recipients_sent": { "type": [ "integer", "null" ], "format": "int32" }, "recipients_total": { "type": [ "integer", "null" ], "format": "int32" }, "scheduled_work": { "$ref": "#/components/schemas/ScheduledWork" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DigestCounts": { "type": "object", "description": "The counts a digest carries. Definitions (version `program-digest-v1`):\n\n- `patients`: patients whose episode of the program overlapped the period:\n who was in the program during it, not who is in it now, so a patient\n whose episode ended mid-period is still counted for the part they were\n there. Deleted patients are excluded outright.\n- `patients_resolved_without_person`: patients whose check-in (a symptom\n session of this program) completed during the period with every required\n answer recorded, and who were not routed to a person during it.\n- `patients_routed_to_person`: patients with a care hand-off opened during\n the period. `patients_with_open_handoff`: patients whose hand-off was\n still unresolved at the end of the period.\n- `readings`: device readings measured during\n the period, since the patient's enrollment. `readings_inside_rules`: one\n of THIS program's reading-triggered rules evaluated it and none matched.\n `readings_outside_rules`: one matched. `readings_not_evaluated`: none of\n this program's rules evaluated it, which includes every reading no rule\n was configured to look at, so this is a count to read, never a reason a\n period is not an all-clear.\n- `devices_transmitting`: a patient's device (source and device reference)\n with a reading during the period. `devices_stopped`: one with a reading\n in the PREVIOUS period of the same length and none in this one. The\n lookback is one period rather than since enrollment so that a device a\n patient replaced stops counting instead of blocking every later\n all-clear.\n- `patients_without_readings`: patients enrolled before the period began\n with no device reading in it or in the one before it. A patient who\n joined during the period is not counted: they have not gone quiet.", "properties": { "devices_stopped": { "type": "integer", "format": "int64", "default": 0 }, "devices_transmitting": { "type": "integer", "format": "int64", "default": 0 }, "patients": { "type": "integer", "format": "int64", "default": 0 }, "patients_resolved_without_person": { "type": "integer", "format": "int64", "default": 0 }, "patients_routed_to_person": { "type": "integer", "format": "int64", "default": 0 }, "patients_with_open_handoff": { "type": "integer", "format": "int64", "default": 0 }, "patients_without_readings": { "type": "integer", "format": "int64", "default": 0 }, "readings": { "type": "integer", "format": "int64", "default": 0 }, "readings_inside_rules": { "type": "integer", "format": "int64", "default": 0 }, "readings_not_evaluated": { "type": "integer", "format": "int64", "default": 0 }, "readings_outside_rules": { "type": "integer", "format": "int64", "default": 0 } } }, "DigestList": { "type": "object", "required": [ "items", "environment_id" ], "properties": { "environment_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Digest" } } } }, "DisclosureAcknowledgment": { "type": "object", "required": [ "version", "text_hash", "acknowledged_at" ], "properties": { "acknowledged_at": { "type": "string", "format": "date-time" }, "text_hash": { "type": "string" }, "version": { "type": "string" } } }, "DisclosureAttachment": { "type": "object", "properties": { "established": { "type": [ "boolean", "null" ], "description": "The caller's own assertion; informational. The gate reads the ref." }, "ref": { "type": [ "string", "null" ], "description": "The reference returned when THIS conversation's disclosure was\nrecorded. Any other value is ignored, and the turn is answered on\nthis conversation's own evidence, so a reference borrowed from\nanother conversation or application leaves the disclosure owed." } } }, "DisclosurePreviewResponse": { "type": "object", "required": [ "program_handle", "tier", "version", "rendered_text", "text_hash" ], "properties": { "program_handle": { "type": "string" }, "rendered_text": { "type": "string" }, "sms_disclosure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SmsDisclosurePreview", "description": "Unavailable means SMS opt-in cannot be offered; ordinary enrollment remains available." } ] }, "text_hash": { "type": "string" }, "tier": { "type": "string" }, "version": { "type": "string" } } }, "DisclosureView": { "type": "object", "required": [ "ref", "application_id", "conversation_id", "channel", "evidence_id", "recorded_at" ], "properties": { "application_id": { "type": "string", "format": "uuid" }, "channel": { "$ref": "#/components/schemas/GovernChannel" }, "conversation_id": { "type": "string" }, "evidence_id": { "type": "string", "format": "uuid", "description": "The evidence row; the id a reviewer sees in the console." }, "recorded_at": { "type": "string", "format": "date-time" }, "ref": { "type": "string", "description": "Attach this as `disclosure.ref` on every evaluate for the conversation.\n`evaluate` also derives it from `conversation_id` when absent." } } }, "EnrollmentAuthDto": { "type": "object", "required": [ "jwt", "expires_in", "refresh_url" ], "properties": { "expires_in": { "type": "integer", "format": "int64" }, "jwt": { "type": "string" }, "refresh_url": { "type": "string" } } }, "EnrollmentContextDto": { "type": "object", "description": "The per-enrollment context every period shares.", "required": [ "enrollment_id", "xuser_id", "episode_profile_id", "project_id", "identifier", "name", "timezone", "enrolled_at", "consent_missing", "order_reference_missing", "config", "config_fell_back_to_defaults" ], "properties": { "anchor_date": { "type": [ "string", "null" ], "format": "date", "description": "The patient-local date period one starts on. Absent only for a\nfirst-transmission anchor with no reading yet." }, "config": { "$ref": "#/components/schemas/BillingPeriodConfigDto" }, "config_fell_back_to_defaults": { "type": "boolean", "description": "The program stores a `billing_period` block the ledger could not derive\nunder (malformed, or it breaks a rule the spec validator enforces), so\n`config` is the defaults and the stored block was ignored. `false` when\nthe program has no block or a usable one." }, "consent_missing": { "type": "boolean" }, "consent_recorded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest recorded consent grant for this patient; absent is reported,\nnot an error." }, "enrolled_at": { "type": "string", "format": "date-time" }, "enrollment_id": { "type": "string", "format": "uuid" }, "episode_profile_id": { "type": "string", "format": "uuid" }, "identifier": { "type": "string", "description": "External patient identifier (PHI, returned only to the authorized tenant)." }, "name": { "type": "string", "description": "Patient name (PHI, returned only to the authorized tenant)." }, "order_reference": { "type": [ "string", "null" ], "description": "Clinic-entered external order reference; absent is reported, not an\nerror." }, "order_reference_missing": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int32" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "setup_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The enrollment's start (from the enrollment record)." }, "timezone": { "type": "string", "description": "IANA zone the period calendar is evaluated in." }, "xuser_id": { "type": "string", "format": "uuid" } } }, "EnrollmentDto": { "type": "object", "required": [ "id", "org_id", "project_id", "project_key", "program_id", "program_handle", "tier", "xuser_id", "started_at" ], "properties": { "episode_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The patient's active episode for this enrollment, for use with the\nepisode-scoped endpoints. Absent only when episode setup failed; the\nenrollment itself still succeeds." }, "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "integer", "format": "int32" }, "program_handle": { "type": "string" }, "program_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "integer", "format": "int32", "description": "Numeric project id, kept for older SDK builds. Prefer `project_key`." }, "project_key": { "type": "string", "description": "Opaque project key (e.g. `proj_xxxxx`), the project identifier the SDK\nendpoints accept." }, "started_at": { "type": "string", "format": "date-time" }, "tier": { "type": "string" }, "xuser_id": { "type": "string", "format": "uuid" } } }, "EnrollmentLedgerDto": { "allOf": [ { "$ref": "#/components/schemas/EnrollmentContextDto" }, { "type": "object", "required": [ "periods" ], "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/PeriodDto" } } } } ], "description": "One enrollment's ledger: context plus every period." }, "EnrollmentResolveRequest": { "type": "object", "required": [ "program_handle", "anybio_user_id", "anybio_user_email", "device_id", "bundle_id", "disclosure_acknowledgment" ], "properties": { "anybio_user_email": { "type": "string" }, "anybio_user_id": { "type": "string" }, "anybio_user_name": { "type": [ "string", "null" ] }, "bundle_id": { "type": "string" }, "cohort": { "type": [ "string", "null" ] }, "device_id": { "type": "string" }, "disclosure_acknowledgment": { "$ref": "#/components/schemas/DisclosureAcknowledgment" }, "program_handle": { "type": "string" }, "provider_binding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderBinding", "description": "The provider's patient-identity binding captured at enrollment. Required,\nwith a non-blank `identifier_value`, when the program's EHR integration\nrequires a binding; the enrollment is refused otherwise. The identifier\nsystem is not sent: the server resolves it from the integration." } ] }, "sms_opt_in": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SmsOptIn", "description": "Omit unless the patient affirmatively checks the separate SMS choice." } ] }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone identifier from the device, e.g. \"America/New_York\".\nStored on the patient so scheduled policies run at local time. When\nabsent, the patient's timezone stays `UTC`." } } }, "EnrollmentResolveResponse": { "type": "object", "required": [ "enrollment", "auth", "branding", "program" ], "properties": { "auth": { "$ref": "#/components/schemas/EnrollmentAuthDto" }, "branding": { "$ref": "#/components/schemas/BrandingDto" }, "enrollment": { "$ref": "#/components/schemas/EnrollmentDto" }, "program": { "$ref": "#/components/schemas/ProgramDto" }, "sms_opt_in": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SmsOptInResult" } ] } } }, "EpisodeDto": { "type": "object", "required": [ "id", "xuser_id", "episode_type", "start_ts", "severity", "confidence", "sessions", "status", "attention_level" ], "properties": { "attention_level": { "type": "integer", "format": "int32" }, "confidence": { "type": "string" }, "confidence_assessment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConfidenceDetails", "description": "Reserved for a per-episode data-quality assessment. Not computed at\npresent, so it is always absent. Read an absent value as \"not computed\",\nnot as \"no coverage\"." } ] }, "details": { "type": [ "string", "null" ] }, "end_ts": { "type": [ "string", "null" ] }, "episode_profile_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Episode profile ID - links to the profile that defines this episode type" }, "episode_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "ingest_session": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IngestSessionInfo" } ] }, "ingest_session_id": { "type": [ "string", "null" ], "format": "uuid" }, "latest_summary": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EpisodeSummaryDto", "description": "Latest summary generated for this episode (populated on detail view)" } ] }, "profile_name": { "type": [ "string", "null" ], "description": "Human-readable profile name (e.g., \"30-day Sleep & HRV Recovery Program\")\nUse this for display instead of episode_type when available" }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/EpisodeSessionInfo" }, "description": "All sessions linked to this episode." }, "severity": { "type": "string" }, "start_ts": { "type": "string" }, "status": { "type": "string" }, "thresholds": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EpisodeThresholds" } ] }, "xuser": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/XuserInfo", "description": "XUser info (name, etc.) - populated for org-wide queries" } ] }, "xuser_id": { "type": "string", "format": "uuid" } } }, "EpisodeSessionInfo": { "type": "object", "description": "A session linked to an episode. An episode can have several sessions.", "required": [ "id", "linked_at", "link_source", "started_at", "total_devices", "signal_types" ], "properties": { "duration_human": { "type": [ "string", "null" ] }, "ended_at": { "type": [ "string", "null" ] }, "firmware": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "link_source": { "type": "string", "description": "How this link was created: \"automatic\", \"manual\", \"migrated\"" }, "linked_at": { "type": "string" }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "quality": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SessionQualitySummary", "description": "Per-signal quality computed from the streams' current quality output.\nUnlike `quality_score`, a coarse snapshot taken when the session ended,\nthis reflects any later reprocessing and shows which signal is degraded." } ] }, "quality_score": { "type": [ "string", "null" ] }, "signal_types": { "type": "array", "items": { "type": "string" } }, "started_at": { "type": "string" }, "total_devices": { "type": "integer", "format": "int32" }, "total_size_human": { "type": [ "string", "null" ] } } }, "EpisodeSummaryDto": { "type": "object", "description": "Summary DTO for episode summaries", "required": [ "id", "summary", "summary_type", "created_at" ], "properties": { "agent_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "context_snapshot": {}, "created_at": { "type": "string" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "summary": { "type": "string" }, "summary_type": { "type": "string" } } }, "EpisodeThresholds": { "type": "object", "properties": { "drop_percent": { "type": [ "number", "null" ], "format": "float" }, "feature": { "type": [ "string", "null" ] }, "hr_threshold_bpm": { "type": [ "number", "null" ], "format": "float" }, "max_motion_index": { "type": [ "number", "null" ], "format": "float" }, "min_duration_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "min_phasic_peaks_per_min": { "type": [ "number", "null" ], "format": "float" }, "min_tonic_delta": { "type": [ "number", "null" ], "format": "float" } } }, "EvaluateRequest": { "type": "object", "required": [ "conversation_id", "turn_id", "channel", "audience", "content" ], "properties": { "application_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional; when present it must be the application the key is bound to." }, "audience": { "$ref": "#/components/schemas/GovernAudience" }, "channel": { "$ref": "#/components/schemas/GovernChannel" }, "content": { "type": "string", "description": "The draft the customer's AI produced." }, "conversation_id": { "type": "string" }, "disclosure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DisclosureAttachment" } ] }, "inbound": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InboundMessage", "description": "The patient's message this turn answers. Screened by the\ndeterministic red-flag floor with the application's categories; a\nmatch routes the patient to a person. Requires `patient_ref`." } ] }, "metadata": { "description": "Free JSON, stored and never evaluated." }, "mode_hint": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GovernMode", "description": "Advisory. The application's configured mode decides; a hint that\ndisagrees is ignored." } ] }, "model": { "type": [ "string", "null" ], "description": "The model the caller's application ran for this turn, as the caller\nnames it. Recorded, never interpreted: the platform does\nnot run this model and has nothing to check the name against." }, "model_version": { "type": [ "string", "null" ], "description": "That model's version, as the caller names it. Independent of `model`:\na caller that versions one and not the other is recorded as it is\nrather than refused." }, "patient_ref": { "type": [ "string", "null" ], "description": "The customer's opaque patient identifier. Stored only as a SHA-256." }, "retry_of": { "type": [ "string", "null" ], "format": "uuid", "description": "The decision this turn retries: a new draft written because that\ndecision came back `retryable`. It must name a decision of this\napplication and this conversation whose view says `retryable: true`,\nand that has not been retried already; anything else is refused with\n`400` (or `409` for a second retry of the same decision). The new\ndraft is judged exactly as any other turn. Send it with a NEW\n`turn_id`. When the retry is `allow`, the hand-off the stopped turn\nopened is resolved with the disposition `resolved_by_retry`, provided\nthat turn opened it, nothing else has joined it and nobody has claimed\nit or acted on it." }, "turn_id": { "type": "string", "description": "The idempotency key per application: a replay returns the stored\ndecision. Must not start with `govern:`, which is reserved for the\nrows the platform writes." } } }, "ExternalDecisionEvidence": { "type": "object", "description": "One Govern decision that opened or joined an external hand-off: the\nevidence a person works from. `inbound_content` is the patient's own\nmessage, PHI-visible on this staff-authorised surface only.", "required": [ "decision_id", "conversation_id", "turn_id", "inbound_flags", "created_at" ], "properties": { "conversation_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "decision_id": { "type": "string", "format": "uuid" }, "inbound_content": { "type": [ "string", "null" ] }, "inbound_flags": {}, "inbound_received_at": { "type": [ "string", "null" ], "format": "date-time" }, "turn_id": { "type": "string" } } }, "ExternalHandoffDetail": { "type": "object", "required": [ "environment_id", "handoff", "events", "subject", "decisions" ], "properties": { "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalDecisionEvidence" } }, "environment_id": { "type": "string", "format": "uuid" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CareHandoffEvent" } }, "handoff": { "$ref": "#/components/schemas/CareHandoff" }, "subject": { "$ref": "#/components/schemas/ExternalSubject" } } }, "ExternalSubject": { "type": "object", "description": "The subject of an external hand-off, for its readers.", "required": [ "application_id", "patient_ref_hash" ], "properties": { "application_id": { "type": "string", "format": "uuid" }, "patient_ref_hash": { "type": "string", "description": "SHA-256 of the customer's opaque patient reference." } } }, "FollowRatio": { "type": "object", "description": "Measure 3 over one period.", "required": [ "patients_followed", "staff" ], "properties": { "patients_followed": { "type": "integer", "format": "int64" }, "patients_per_staff": { "type": [ "number", "null" ], "format": "double", "description": "`patients_followed / staff`; `null` when no staff member recorded a\ntouch." }, "staff": { "type": "integer", "format": "int64", "description": "Staff members who recorded at least one coordinator touch." } } }, "FollowRatioMeasure": { "allOf": [ { "$ref": "#/components/schemas/MeasureAbout" }, { "type": "object", "properties": { "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FollowRatio", "description": "`null` when the program has no baseline recorded." } ] }, "period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FollowRatio" } ] } } } ] }, "FrequencyCap": { "type": "object", "description": "The application's per-patient cap: at most `max_messages` per fixed window\nof `window_seconds`, counted from the first message of the window.", "required": [ "max_messages", "window_seconds" ], "properties": { "max_messages": { "type": "integer", "format": "int32" }, "window_seconds": { "type": "integer", "format": "int64" } } }, "FrequencyView": { "type": "object", "required": [ "max_messages", "window_seconds", "window_count", "remaining" ], "properties": { "max_messages": { "type": "integer", "format": "int32" }, "remaining": { "type": "integer", "format": "int32", "description": "Messages left in the current window (the full cap once it has lapsed)." }, "window_count": { "type": "integer", "format": "int32" }, "window_seconds": { "type": "integer", "format": "int64" }, "window_started_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "GovernAudience": { "type": "string", "enum": [ "patient", "clinician" ] }, "GovernChannel": { "type": "string", "description": "The external channel vocabulary of the contract. The server maps each to the\ninternal typed channel; a customer never names an internal token.", "enum": [ "sms", "app_message", "web_chat", "voice", "email" ] }, "GovernDecision": { "type": "string", "description": "The contract's three answers.", "enum": [ "allow", "hold", "block" ] }, "GovernHandoffQuery": { "type": "object", "properties": { "application_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Staff may narrow to one application; an application key is always its\nown." }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "limit": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "offset": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "overdue": { "type": [ "boolean", "null" ] }, "sort": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "GovernMode": { "type": "string", "description": "Per policy, per application: is the gate consulted, and is its answer\nbinding? `Off` is not evaluated; `Observe` is evaluated and recorded as\n`would_have` while the caller is always told allow; `Enforce` returns the\ndecision and it binds.", "enum": [ "off", "observe", "enforce" ] }, "GrantPlatformRoleBody": { "type": "object", "description": "Body of the grant route. `platform_role` is required.", "required": [ "platform_role" ], "properties": { "platform_role": { "type": "string", "description": "One of `support`, `operator`, `root`.", "example": "operator" }, "reason": { "type": [ "string", "null" ], "description": "Free-text justification, stored on the audit row. Optional." } } }, "HandoffDetail": { "type": "object", "required": [ "environment_id", "handoff", "events", "patient", "recent_replies", "withheld_drafts" ], "properties": { "environment_id": { "type": "string", "format": "uuid" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CareHandoffEvent" } }, "handoff": { "$ref": "#/components/schemas/CareHandoff" }, "next_event_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "patient": { "$ref": "#/components/schemas/PatientSummary" }, "recent_replies": { "type": "array", "items": { "$ref": "#/components/schemas/PatientReply" } }, "withheld_drafts": { "type": "array", "items": { "$ref": "#/components/schemas/WithheldDraft" }, "description": "The drafts the gate stopped for this patient, which is what the item\nowes a reply for. Oldest first, as the replies are." } } }, "HandoffList": { "type": "object", "required": [ "environment_id", "items", "total", "patient_names", "awaiting_reply" ], "properties": { "awaiting_reply": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which of these items carry a stopped draft nobody has answered yet. An\nitem keeps the reason it was opened for; this lists the items that also\nowe the patient a reply." }, "environment_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CareHandoff" } }, "patient_names": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "HandoffRef": { "type": "object", "description": "The hand-off a decision opened or joined, as the contract shows it.", "required": [ "id", "state", "version", "queue_label", "pauses_automation" ], "properties": { "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "automation_resumed_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "escalation_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "pauses_automation": { "type": "boolean", "description": "Whether this hand-off also pauses automated messaging to the subject.\n`automation_resumed_at == null` says a person owns it;\nthis says whether the application should stop sending meanwhile. The\ntwo are read together: still paused is\n`automation_resumed_at == null && pauses_automation`." }, "queue_label": { "type": "string" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "type": "string", "description": "`queued` | `claimed` | `resolved`." }, "version": { "type": "integer", "format": "int32" } } }, "HeldReleases": { "type": "object", "description": "Measure 4 over one period. Counts only.", "required": [ "held", "awaiting_review", "reviewed", "released_unchanged", "released_rewritten", "rejected" ], "properties": { "awaiting_review": { "type": "integer", "format": "int64" }, "held": { "type": "integer", "format": "int64" }, "rejected": { "type": "integer", "format": "int64" }, "released_rewritten": { "type": "integer", "format": "int64" }, "released_unchanged": { "type": "integer", "format": "int64", "description": "Released with the original draft: the numerator." }, "reviewed": { "type": "integer", "format": "int64", "description": "Released or rejected: the denominator." } } }, "HeldReleasesMeasure": { "allOf": [ { "$ref": "#/components/schemas/MeasureAbout" }, { "type": "object", "properties": { "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HeldReleases", "description": "`null` when the program has no baseline recorded." } ] }, "period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HeldReleases" } ] } } } ] }, "InboundFlag": { "type": "object", "description": "One red-flag rule the inbound matched. Rule id and category only; never\nthe text.", "required": [ "rule_id", "category" ], "properties": { "category": { "type": "string" }, "rule_id": { "type": "string" } } }, "InboundMessage": { "type": "object", "description": "The patient's message this turn answers.", "required": [ "content", "received_at" ], "properties": { "content": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" } } }, "IngestSessionInfo": { "type": "object", "required": [ "id", "start_ts", "total_devices" ], "properties": { "battery_end": { "type": [ "integer", "null" ], "format": "int32" }, "battery_start": { "type": [ "integer", "null" ], "format": "int32" }, "end_ts": { "type": [ "string", "null" ] }, "firmware": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "sampling_profile": { "type": [ "string", "null" ] }, "start_ts": { "type": "string" }, "total_devices": { "type": "integer", "format": "int32" } } }, "ListAdminXUsersRequest": { "type": "object", "description": "The organization and environment whose patients to list, and an optional\nsearch. Both ids are required.", "required": [ "organization_id", "environment_id" ], "properties": { "environment_id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "integer", "format": "int32" }, "q": { "type": [ "string", "null" ], "description": "Optional case-insensitive substring filter on the patient's name or\nexternal identifier. Use it to reach patients beyond the listing cap." } } }, "ListEpisodesQuery": { "type": "object", "properties": { "attention_gte": { "type": [ "integer", "null" ], "format": "int32", "description": "Filter by minimum attention level (0-100)" }, "episode_profile_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Filter by episode profile ID" }, "limit": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "offset": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "project_id": { "type": [ "integer", "null" ], "format": "int32", "description": "Filter by project. When the UI has a project selector, pass this to scope results." }, "status": { "type": [ "string", "null" ], "description": "Filter by episode status (e.g., \"active\", \"completed\", \"cancelled\")" }, "xuser_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Filter by specific user. If not provided, returns episodes for all users in the org." } } }, "ListSessionsQuery": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "offset": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "paginated": { "type": [ "boolean", "null" ], "description": "Return `{data, total, has_more}` instead of a bare array. Without it,\n`limit` truncates with no total to show how many sessions match." }, "project_id": { "type": [ "integer", "null" ], "format": "int32" }, "xuser_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "LoginFormPayload": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "example": "user@example.com" }, "password": { "type": "string", "example": "password123" } } }, "LoginResult": { "type": "object", "required": [ "success", "message" ], "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "MeasureAbout": { "type": "object", "description": "A measure's definition as returned with its numbers.", "required": [ "key", "version", "definition", "available" ], "properties": { "available": { "type": "boolean", "description": "False when the records cannot answer the measure over the REQUESTED\nperiod; then `unavailable_reason` says why and `period` is null.\n\n`baseline` is answered separately, because answerability is a property\nof a period rather than of the program: a measure can carry numbers\nfor this month and none for a baseline period that ran before the\nprogram could record them. A null `baseline` beside a non-null\n`baseline` period at the top of the report means exactly that." }, "definition": { "type": "string", "description": "Exactly what counts." }, "key": { "type": "string" }, "unavailable_reason": { "type": [ "string", "null" ] }, "version": { "type": "string", "description": "The definition's version. A change to what the measure counts is a new\nversion." } } }, "MessageAllowance": { "type": "object", "description": "A program's own allowance: at most `max_messages` automated SMS in any\ntrailing `window_seconds`, counted per handset and per patient across every\nprogram and notification in the organization and environment. Every field\nis required and there is no default.", "required": [ "max_messages", "window_seconds" ], "properties": { "max_messages": { "type": "integer", "format": "int32" }, "window_seconds": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "MessagingPolicy": { "type": "object", "required": [ "max_messages", "window_seconds", "routing" ], "properties": { "max_messages": { "type": "integer", "format": "int32" }, "routing": { "$ref": "#/components/schemas/RoutingPolicy" }, "window_seconds": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "MintedKeyDto": { "allOf": [ { "$ref": "#/components/schemas/ApplicationKeyDto" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "The raw key. This is its only appearance; store it server-side." } } } ], "description": "A key at mint time: the metadata plus the secret, which is shown once." }, "MintedWebhookSecret": { "type": "object", "description": "A freshly minted signing secret: the plaintext, shown once, and when.", "required": [ "webhook_secret", "webhook_secret_hint", "rotated_at" ], "properties": { "rotated_at": { "type": "string", "format": "date-time" }, "webhook_secret": { "type": "string", "description": "The secret. This is its only appearance; store it server-side." }, "webhook_secret_hint": { "type": "string", "description": "Its last four characters, for telling secrets apart." } } }, "ModelBreakdown": { "allOf": [ { "$ref": "#/components/schemas/Counts" }, { "type": "object", "properties": { "model": { "type": [ "string", "null" ] }, "model_version": { "type": [ "string", "null" ] } } } ], "description": "The same counts, per model and model version the caller named, so the\nperiods before and after a model change can be compared in one window. A\nbucket with both fields null counts the turns whose caller named no model." }, "ObserveReport": { "allOf": [ { "$ref": "#/components/schemas/Counts" }, { "type": "object", "required": [ "application_id", "from", "to", "totals", "by_policy", "by_channel", "by_model", "rates" ], "properties": { "application_id": { "type": "string", "format": "uuid" }, "by_channel": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelBreakdown" } }, "by_model": { "type": "array", "items": { "$ref": "#/components/schemas/ModelBreakdown" } }, "by_policy": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyBreakdown" } }, "from": { "type": "string", "format": "date-time" }, "rates": { "$ref": "#/components/schemas/Rates" }, "to": { "type": "string", "format": "date-time" }, "totals": { "$ref": "#/components/schemas/Totals" } } } ] }, "ObserveReportQuery": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date-time", "description": "Inclusive, RFC 3339. Default: `to` minus fourteen days." }, "to": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive, RFC 3339. Default: now." } } }, "OmittedEnrollmentDto": { "type": "object", "description": "An enrollment on the program that produced no row for the selection,\nlisted so that no enrollment is silently missing.", "required": [ "enrollment_id", "xuser_id", "reason" ], "properties": { "enrollment_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "description": "`no_reading_yet` (first-transmission anchor, no reading),\n`no_period_in_selection` (program listing), or `no_current_period`\n(current-period listing)." }, "xuser_id": { "type": "string", "format": "uuid" } } }, "OptOutRequest": { "type": "object", "description": "`POST /api/v1/govern/patients/opt-out`. `opted_out: false` records the\npatient opting back in, which the application may do only for an opt-out\nit recorded itself.", "required": [ "patient_ref", "opted_out" ], "properties": { "at": { "type": [ "string", "null" ], "format": "date-time" }, "channel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GovernChannel" } ] }, "opted_out": { "type": "boolean" }, "patient_ref": { "type": "string" } } }, "OrderReferenceResponse": { "type": "object", "required": [ "enrollment_id", "order_reference_missing" ], "properties": { "enrollment_id": { "type": "string", "format": "uuid" }, "order_reference": { "type": [ "string", "null" ] }, "order_reference_missing": { "type": "boolean" } } }, "OrgListRow": { "type": "object", "description": "One organization with its tier and rollup counts, as the admin organization listing returns it.", "required": [ "id", "name", "tier", "created_at", "user_count", "project_count", "active_program_count" ], "properties": { "active_program_count": { "type": "integer", "format": "int64", "description": "Number of programs in the organization whose status is active. Condition\nand monitoring profiles are not counted." }, "builder_persona": { "type": [ "string", "null" ], "description": "The organization's default program-builder mode: `builder`, `prosumer` or\n`protocol_authoring`. Null uses `builder`. The stored value is returned as\nis, so an unrecognised value is shown rather than replaced." }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "project_count": { "type": "integer", "format": "int64", "description": "Number of projects in the organization." }, "tier": { "type": "string" }, "user_count": { "type": "integer", "format": "int64", "description": "Active (non-revoked) user count for the org." } } }, "Organization": { "type": "object", "required": [ "id", "name", "organization_type_id", "compliance_tier", "terminology_profile", "tier", "created_at", "updated_at" ], "properties": { "address": { "type": [ "string", "null" ] }, "billing_interval": { "type": [ "string", "null" ] }, "branding_accent_color": { "type": [ "string", "null" ] }, "branding_copy_overrides": {}, "branding_display_name": { "type": [ "string", "null" ] }, "branding_logo_url": { "type": [ "string", "null" ] }, "branding_primary_color": { "type": [ "string", "null" ] }, "branding_secondary_color": { "type": [ "string", "null" ] }, "branding_tone": { "type": [ "string", "null" ] }, "builder_persona": { "type": [ "string", "null" ], "description": "The organization's default program-builder mode: `builder`, `prosumer` or\n`protocol_authoring`. Null uses `builder`." }, "building_type": { "type": [ "string", "null" ] }, "compliance_tier": { "type": "string" }, "contact": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "current_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "developer_approach": { "type": [ "string", "null" ] }, "gbraid": { "type": [ "string", "null" ] }, "gclid": { "type": [ "string", "null" ] }, "gclid_captured_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "integer", "format": "int32" }, "identifier": { "type": [ "string", "null" ] }, "llm_budget_daily_usd": { "type": [ "number", "null" ], "format": "double" }, "name": { "type": "string" }, "onboarding_door": { "type": [ "string", "null" ] }, "organization_type_id": { "type": "integer", "format": "int32" }, "parent_organization_id": { "type": [ "integer", "null" ], "format": "int32" }, "preferred_ai_tool": { "type": [ "string", "null" ] }, "preferred_language": { "type": [ "string", "null" ] }, "sandbox_hard_deadline": { "type": [ "string", "null" ], "format": "date-time" }, "stripe_customer_id": { "type": [ "string", "null" ] }, "stripe_price_id": { "type": [ "string", "null" ] }, "stripe_subscription_id": { "type": [ "string", "null" ] }, "subscription_status": { "type": [ "string", "null" ] }, "terminology_profile": { "type": "string" }, "tier": { "type": "string" }, "trial_end_date": { "type": [ "string", "null" ], "format": "date-time" }, "trial_start_date": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_captured_at": { "type": [ "string", "null" ], "format": "date-time" }, "utm_content": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] }, "wbraid": { "type": [ "string", "null" ] }, "what_building": { "type": [ "string", "null" ] }, "writes_disabled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrganizationResponse": { "type": "object", "required": [ "id", "name", "compliance_tier", "terminology_profile", "tier", "slug", "created_at", "updated_at" ], "properties": { "builder_persona": { "type": [ "string", "null" ], "description": "The organization's default program-builder mode: `builder`, `prosumer` or\n`protocol_authoring`. Null uses `builder`." }, "building_type": { "type": [ "string", "null" ] }, "compliance_tier": { "type": "string", "description": "Data handling policy: \"standard\" or \"hipaa\"" }, "created_at": { "type": "string" }, "developer_approach": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "onboarding_door": { "type": [ "string", "null" ] }, "preferred_ai_tool": { "type": [ "string", "null" ] }, "preferred_language": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "terminology_profile": { "type": "string", "description": "UI terminology profile: \"default\", \"clinical\", or \"research\"" }, "tier": { "type": "string", "description": "Account tier: starter, sandbox, production, clinical_production, enterprise" }, "trial_end_date": { "type": [ "string", "null" ] }, "trial_start_date": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" }, "what_building": { "type": [ "string", "null" ] } } }, "OutcomeRequest": { "type": "object", "required": [ "delivered", "delivered_at" ], "properties": { "delivered": { "type": "boolean", "description": "The customer delivered a message for this turn." }, "delivered_at": { "type": "string", "format": "date-time" }, "delivered_content_hash": { "type": [ "string", "null" ], "description": "SHA-256, hex, of the UTF-8 text delivered. Required when `delivered`." }, "delivery_ref": { "type": [ "string", "null" ], "description": "The customer's own reference for the delivery." } } }, "OutcomeView": { "type": "object", "required": [ "delivered", "delivered_at", "recorded_at" ], "properties": { "delivered": { "type": "boolean" }, "delivered_at": { "type": "string", "format": "date-time" }, "delivered_content_hash": { "type": [ "string", "null" ] }, "delivery_ref": { "type": [ "string", "null" ] }, "hash_matches_release": { "type": [ "boolean", "null" ], "description": "Whether the delivered hash matches the content the record says was\ndeliverable. `null` when nothing was delivered or there was nothing to\ncompare against." }, "recorded_at": { "type": "string", "format": "date-time" } } }, "PaginatedChunkIssues": { "type": "object", "description": "Paginated envelope for a session's chunk-level decode problems.", "required": [ "data", "total", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChunkIssueRow" } }, "has_more": { "type": "boolean" }, "total": { "type": "integer", "format": "int64" } } }, "PaginatedEpisodeProfiles": { "type": "object", "description": "A page of programs: `data`, the `total` across all pages, and `has_more`.", "required": [ "data", "total", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminEpisodeProfileRow" } }, "has_more": { "type": "boolean" }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedOrgs": { "type": "object", "description": "A page of organizations: `data`, the `total` across all pages, and\n`has_more`.", "required": [ "data", "total", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgListRow" } }, "has_more": { "type": "boolean" }, "total": { "type": "integer", "format": "int64" } } }, "PaginatedProjects": { "type": "object", "description": "A page of projects with their organization fields: `data`, the `total`\nacross all pages, and `has_more`.", "required": [ "data", "total", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminProjectWithOrg" } }, "has_more": { "type": "boolean" }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedSessions": { "type": "object", "description": "Paginated envelope, returned only when `?paginated=true`.", "required": [ "data", "total", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionListItem" } }, "has_more": { "type": "boolean" }, "total": { "type": "integer", "format": "int64", "description": "Rows matching the filters, ignoring limit and offset.", "minimum": 0 } } }, "PatchApplicationRequest": { "type": "object", "description": "Every field optional; only the ones present change. `channel_policies`\nreplaces the whole map when present (send the full map back).", "properties": { "channel_policies": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/ChannelPolicy" }, "propertyNames": { "type": "string" } }, "default_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GovernMode" } ] }, "frequency_cap": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FrequencyCap", "description": "`null` removes the cap; omit to leave it unchanged." } ] }, "handoff_routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RoutingPolicy", "description": "`null` clears the routing; hand-offs then open with the\norganization's default queue and no deadlines." } ] }, "name": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ], "format": "int32", "description": "`null` clears the project scope back to the organization policy; omit to\nleave it unchanged." }, "red_flag_categories": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Replaces the whole list when present; must not be empty." }, "webhook_url": { "type": [ "string", "null" ] } } }, "PatientBillingPeriodsResponse": { "type": "object", "required": [ "environment_id", "xuser_id", "as_of", "enrollments" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "The instant the ledger was evaluated at." }, "enrollments": { "type": "array", "items": { "$ref": "#/components/schemas/EnrollmentLedgerDto" } }, "environment_id": { "type": "string", "format": "uuid" }, "xuser_id": { "type": "string", "format": "uuid" } } }, "PatientEventView": { "type": "object", "required": [ "id", "kind", "source", "occurred_at", "recorded_at" ], "properties": { "channel": { "type": [ "string", "null" ] }, "decision_id": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "recorded_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" } } }, "PatientRefs": { "type": "object", "description": "Staff-appropriate patient references: patient record ids, nothing else.", "properties": { "devices_stopped": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "open_handoff": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "resolved_without_person": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "routed_to_person": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "without_readings": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] } } }, "PatientReply": { "type": "object", "required": [ "id", "body", "received_at" ], "properties": { "body": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "received_at": { "type": "string", "format": "date-time" } } }, "PatientStateRequest": { "type": "object", "description": "`POST /api/v1/govern/patients/state`: a read, as a POST so the reference\nstays out of the URL.", "required": [ "patient_ref" ], "properties": { "patient_ref": { "type": "string" } } }, "PatientStateView": { "type": "object", "description": "The state as the contract shows it. The reference itself is never in it.", "required": [ "application_id", "patient_ref_hash", "consent_state", "opted_out", "events" ], "properties": { "application_id": { "type": "string", "format": "uuid" }, "consent_changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "consent_state": { "type": "string", "description": "`unknown` | `granted` | `revoked`." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/PatientEventView" }, "description": "The most recent transitions, newest first (at most twenty)." }, "frequency": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FrequencyView" } ] }, "last_contact_at": { "type": [ "string", "null" ], "format": "date-time" }, "opted_out": { "type": "boolean" }, "opted_out_changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "opted_out_source": { "type": [ "string", "null" ] }, "patient_ref_hash": { "type": "string" } } }, "PatientSummary": { "type": "object", "required": [ "id", "display_name" ], "properties": { "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" } } }, "PeriodDto": { "type": "object", "description": "One fixed period of one enrollment.", "required": [ "period_index", "period_start", "period_end", "unique_transmission_days", "tier", "device_identifiers", "device_classes", "device_replaced_in_period", "is_current" ], "properties": { "days_elapsed": { "type": [ "integer", "null" ], "format": "int32", "description": "Pace of the current period; `null` on every other period.\nDays of the period elapsed through today, today included." }, "days_needed_for_high_tier": { "type": [ "integer", "null" ], "format": "int32", "description": "Unique days still needed to reach the upper bar (zero once reached).\nCurrent period only." }, "days_remaining": { "type": [ "integer", "null" ], "format": "int32", "description": "Days of the period after today. Current period only." }, "device_classes": { "type": "array", "items": { "type": "string" }, "description": "Distinct device classes seen in the period (e.g. `blood_pressure_cuff`)." }, "device_identifiers": { "type": "array", "items": { "type": "string" }, "description": "Distinct device identifiers that reported in the period." }, "device_replaced_in_period": { "type": "boolean", "description": "More than one device identifier reported in the period." }, "first_reading_at": { "type": [ "string", "null" ], "format": "date-time" }, "high_tier_reachable": { "type": [ "boolean", "null" ], "description": "`days_needed_for_high_tier <= days_remaining`. Current period only." }, "high_tier_reached_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_current": { "type": "boolean", "description": "The period containing the as-of date." }, "last_reading_at": { "type": [ "string", "null" ], "format": "date-time" }, "low_tier_reached_at": { "type": [ "string", "null" ], "format": "date-time" }, "on_pace": { "type": [ "boolean", "null" ], "description": "Unique days so far are at or above the pro-rata share of the upper bar\nfor the days elapsed, rounded up. Current period only." }, "pace_state": { "type": [ "string", "null" ], "description": "`on_pace` / `behind_reachable` / `not_reachable`. Current period only." }, "period_end": { "type": "string", "format": "date", "description": "Last patient-local date of the period, inclusive." }, "period_index": { "type": "integer", "format": "int32", "description": "1-based; period one starts on the anchor date." }, "period_start": { "type": "string", "format": "date", "description": "First patient-local date of the period, inclusive." }, "tier": { "type": "string", "description": "`none` / `days_2_to_15` / `days_16_plus`." }, "tier_reached_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Device time of the reading that reached `tier`; absent when `none`." }, "unique_transmission_days": { "type": "integer", "format": "int32", "description": "Patient-local days in the period with at least one reading from the\ncellular device source." } } }, "PlatformRoleChangeResponse": { "type": "object", "description": "What the caller gets back. Tiers are the snake_case tokens; `null` means no\nplatform standing.", "required": [ "user_id", "changed" ], "properties": { "changed": { "type": "boolean", "description": "False when the row already held the requested standing: no UPDATE\nfired and no audit row was written." }, "platform_role": { "type": [ "string", "null" ], "example": "operator" }, "previous_platform_role": { "type": [ "string", "null" ], "example": "support" }, "user_id": { "type": "string", "format": "uuid" } } }, "PolicyBreakdown": { "allOf": [ { "$ref": "#/components/schemas/Counts" }, { "type": "object", "properties": { "policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "policy_name": { "type": [ "string", "null" ] }, "policy_version": { "type": [ "integer", "null" ], "format": "int32" } } } ] }, "PolicyRef": { "type": "object", "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "version": { "type": "integer", "format": "int32" } } }, "PolicyResponse": { "type": "object", "required": [ "environment_id" ], "properties": { "environment_id": { "type": "string", "format": "uuid" }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessagingPolicy" } ] } } }, "ProgramAllowanceResponse": { "type": "object", "description": "A program's own message allowance.", "required": [ "episode_profile_id", "environment_id" ], "properties": { "allowance": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessageAllowance", "description": "`null` when the program has none of its own: the organization policy's\nallowance governs its sends." } ] }, "environment_id": { "type": "string", "format": "uuid" }, "episode_profile_id": { "type": "string", "format": "uuid" } } }, "ProgramBaseline": { "type": "object", "description": "The baseline as the endpoint returns it: the period and who recorded it.", "required": [ "starts_at", "ends_at", "recorded_at" ], "properties": { "ends_at": { "type": "string", "format": "date-time", "description": "Exclusive." }, "recorded_at": { "type": "string", "format": "date-time" }, "recorded_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The staff user who recorded it; `null` when an Admin developer key\ndid (the audit trail names the key)." }, "starts_at": { "type": "string", "format": "date-time", "description": "Inclusive." } } }, "ProgramBillingPeriodsResponse": { "type": "object", "required": [ "environment_id", "episode_profile_id", "as_of", "selection", "count", "total", "rows", "omitted" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "description": "Rows on this page.", "minimum": 0 }, "environment_id": { "type": "string", "format": "uuid" }, "episode_profile_id": { "type": "string", "format": "uuid" }, "from": { "type": [ "string", "null" ], "format": "date" }, "omitted": { "type": "array", "items": { "$ref": "#/components/schemas/OmittedEnrollmentDto" } }, "period_index": { "type": [ "integer", "null" ], "format": "int32" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramPeriodRowDto" } }, "selection": { "type": "string", "description": "The selection that produced `rows`: `period_index`, `date_range` or\n`current`." }, "to": { "type": [ "string", "null" ], "format": "date" }, "total": { "type": "integer", "description": "Rows across all pages.", "minimum": 0 } } }, "ProgramDto": { "type": "object", "required": [ "id", "slug", "name", "category", "lifecycle_mode" ], "properties": { "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "lifecycle_mode": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "spec": {} } }, "ProgramMeasuresQuery": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date-time", "description": "Inclusive, RFC 3339. Default: `to` minus thirty days." }, "to": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive, RFC 3339. Default, and ceiling: the instant the report is\ncomputed. A later value is read as that instant." } } }, "ProgramMeasuresReport": { "type": "object", "required": [ "program_id", "as_of", "from", "to", "time_to_clinical_contact", "coordinator_touches_per_patient_month", "patients_followed_per_nurse", "held_items_released_unchanged" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "When the report was computed. An occurrence awaiting contact, a held\nitem awaiting review and an open episode are all as of this instant." }, "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProgramBaseline", "description": "The program's recorded baseline period; `null` when none is recorded." } ] }, "coordinator_touches_per_patient_month": { "$ref": "#/components/schemas/TouchRateMeasure" }, "from": { "type": "string", "format": "date-time" }, "held_items_released_unchanged": { "$ref": "#/components/schemas/HeldReleasesMeasure" }, "patients_followed_per_nurse": { "$ref": "#/components/schemas/FollowRatioMeasure" }, "program_id": { "type": "string", "format": "uuid" }, "time_to_clinical_contact": { "$ref": "#/components/schemas/ContactTimeMeasure" }, "to": { "type": "string", "format": "date-time" } } }, "ProgramPeriodRowDto": { "allOf": [ { "$ref": "#/components/schemas/EnrollmentContextDto" }, { "type": "object", "required": [ "period" ], "properties": { "period": { "$ref": "#/components/schemas/PeriodDto" } } } ], "description": "One (patient, period) row of a program listing, and of the current-period\nlisting (where `period` is always the current one and carries its pace)." }, "Project": { "type": "object", "required": [ "id", "organization_id", "environment_id", "project_key", "name", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the project was soft-deleted; null while it is live. A soft-deleted\nproject's name can be reused." }, "description": { "type": [ "string", "null" ] }, "environment_id": { "type": "string", "format": "uuid", "description": "The environment (sandbox or production) the project belongs to." }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "organization_id": { "type": "integer", "format": "int32" }, "project_key": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectAssignmentPayload": { "type": "object", "required": [ "xuser_ids" ], "properties": { "xuser_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "550e8400-e29b-41d4-a716-446655440000" ] } } }, "ProjectPayload": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "example": "A project for collecting biosignal data" }, "name": { "type": "string", "example": "My Research Project" } } }, "ProjectUpdatePayload": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "example": "Updated project description" }, "name": { "type": [ "string", "null" ], "example": "Updated Project Name" } } }, "ProjectWithOrgKey": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "type": "object", "properties": { "organization_api_key": { "type": [ "string", "null" ], "example": "org_abc123" } } } ], "description": "Extended project response that includes organization API key for SDK integration" }, "ProviderBinding": { "type": "object", "description": "The client-supplied part of a provider's patient-identity binding. The\nidentifier system is resolved by the server from the integration.", "required": [ "identifier_value", "binding_content", "capture_method" ], "properties": { "binding_content": { "type": "string", "description": "How the value is interpreted: `opaque_provider_translated |\nmrn_assigning_authority | fhir_patient_id`." }, "capture_method": { "type": "string", "description": "How the binding was captured: `per_patient_qr |\nprogram_qr_plus_provider_code`." }, "identifier_value": { "type": "string", "description": "The provider-issued identifier for the patient. It is the identifier\nwritten on records exported to the provider's EHR, not the patient's\n`identifier` here." } } }, "PublicBiosignalDto": { "type": "object", "description": "One biosignal in the public catalog: its name, abbreviation, unit,\ndescription, signal type, and `feature_aliases`, the other names the\nsignal is known by (for example \"heart rate variability\" for HRV).", "required": [ "id", "name", "signal_type", "feature_aliases" ], "properties": { "abbreviation": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "feature_aliases": { "type": "array", "items": { "type": "string" } }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "signal_type": { "type": "string" }, "unit": { "type": [ "string", "null" ] } } }, "PurgeResponse": { "type": "object", "required": [ "application_id", "patient_states_removed", "patient_events_removed" ], "properties": { "application_id": { "type": "string", "format": "uuid" }, "patient_events_removed": { "type": "integer", "format": "int64", "minimum": 0 }, "patient_states_removed": { "type": "integer", "format": "int64", "minimum": 0 } } }, "Rates": { "type": "object", "description": "Fractions in `[0, 1]`, never percentages: the share of decided observe\nturns the gate would have withheld, and of decided enforce turns it held.", "properties": { "enforced_held": { "type": [ "number", "null" ], "format": "double" }, "would_have_withheld": { "type": [ "number", "null" ], "format": "double" } } }, "RecordBaselineRequest": { "type": "object", "description": "`PUT /api/v1/episode-profiles/{id}/baseline`. Replaces any baseline the\nprogram has; the audit trail keeps the previous one.", "required": [ "starts_at", "ends_at" ], "properties": { "ends_at": { "type": "string", "format": "date-time", "description": "Exclusive, RFC 3339. May be in the future: a baseline can be fixed\nbefore the period it names has run." }, "starts_at": { "type": "string", "format": "date-time", "description": "Inclusive, RFC 3339." } } }, "RecordDisclosureRequest": { "type": "object", "required": [ "conversation_id", "channel", "text_shown", "at" ], "properties": { "application_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional; when present it must be the application the key is bound to." }, "at": { "type": "string", "format": "date-time", "description": "When it was shown." }, "channel": { "$ref": "#/components/schemas/GovernChannel" }, "conversation_id": { "type": "string" }, "text_shown": { "type": "string", "description": "The disclosure text the patient was shown, verbatim." } } }, "ResolveRequest": { "type": "object", "required": [ "expected_version", "disposition", "note", "resume_automation" ], "properties": { "disposition": { "type": "string" }, "expected_version": { "type": "integer", "format": "int32" }, "note": { "type": "string" }, "resume_automation": { "type": "boolean" } } }, "Resource": { "type": "object", "required": [ "details", "resource_type" ], "properties": { "details": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "string" }, { "type": "string" } ] } }, "resource_type": { "$ref": "#/components/schemas/ResourceType" } } }, "ResourceType": { "type": "string", "enum": [ "User", "File", "Session", "Message" ] }, "ResumeRequest": { "type": "object", "required": [ "expected_version", "note" ], "properties": { "expected_version": { "type": "integer", "format": "int32" }, "note": { "type": "string" } } }, "ReviewState": { "type": "string", "enum": [ "pending", "released", "rejected" ] }, "RevokePlatformRoleBody": { "type": "object", "description": "Body of the revoke route. Every field is optional, so `{}` is valid, but a\nbody is required.", "properties": { "reason": { "type": [ "string", "null" ], "description": "Free-text justification, stored on the audit row. Optional." } } }, "RotateKeyBody": { "type": "object", "properties": { "overlap_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "How long the previous keys keep authenticating after this rotation.\nDefault one day; at most seven. Zero refuses the previous keys at once." } } }, "RotateKeyResponse": { "type": "object", "required": [ "key", "previous_keys_expire_at" ], "properties": { "key": { "$ref": "#/components/schemas/MintedKeyDto" }, "previous_keys_expire_at": { "type": "string", "format": "date-time", "description": "When every previous key of the application stops authenticating." } } }, "RoutingPolicy": { "type": "object", "required": [ "queue_label", "primary_user_ids", "backup_user_ids", "response_seconds", "escalation_seconds", "coverage_note" ], "properties": { "backup_user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "coverage_note": { "type": "string", "description": "Operator-facing description; does not implement calendar scheduling." }, "escalation_seconds": { "type": "integer", "format": "int64", "description": "Additional elapsed time after the response deadline before backup routing." }, "primary_user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "queue_label": { "type": "string" }, "response_seconds": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "Schedule": { "type": "object", "required": [ "episode_profile_id", "cadence_hours", "period_start", "next_due_at", "program_active", "overdue", "failed_attempts", "updated_at" ], "properties": { "cadence_hours": { "type": "integer", "format": "int32" }, "episode_profile_id": { "type": "string", "format": "uuid" }, "failed_attempts": { "type": "integer", "format": "int32", "description": "Consecutive digest passes that failed to record anything, and when the\nlast one failed. A digest pass that is itself broken is readable here\nrather than only in a worker log." }, "last_failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_due_at": { "type": "string", "format": "date-time", "description": "Where the next digest's period ends; it goes out at this time." }, "overdue": { "type": "boolean", "description": "A whole cadence has passed since the digest was due and the program is\nactive: at least one digest did not go out. Visible here even when\nnothing is sent at all. Always false for an inactive program, whose\nschedule is dormant rather than late." }, "period_start": { "type": "string", "format": "date-time", "description": "Where the next digest's period begins." }, "program_active": { "type": "boolean", "description": "Whether the PROGRAM is active. The digest pass only picks up active\nprograms, so a schedule on one that has been drafted or deprecated\nproduces nothing, and that is not a digest that failed to go out. This\nis what tells a paused program from a broken one." }, "updated_at": { "type": "string", "format": "date-time" } } }, "ScheduleRequest": { "type": "object", "description": "`PUT /api/v1/episode-profiles/:id/digest-schedule`.", "required": [ "cadence_hours" ], "properties": { "cadence_hours": { "type": "integer", "format": "int32", "description": "Hours between digests. Required; there is no default." }, "first_due_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the first digest (after this change) goes out. Must be in the\nfuture and within one cadence; absent means one cadence from now." } }, "additionalProperties": false }, "ScheduleResponse": { "type": "object", "required": [ "environment_id" ], "properties": { "environment_id": { "type": "string", "format": "uuid" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Schedule", "description": "`null` when the program has no cadence: it sends no digest." } ] } } }, "ScheduledWork": { "type": "object", "description": "Whether the program's own scheduled work ran. `rules` are the active\nschedule and inactivity policies that apply to the program (scoped to it,\nto a project its episodes are in, or to its whole environment).", "properties": { "executions_with_failed_actions": { "type": "integer", "format": "int64", "description": "Evaluations of these rules during the period whose actions failed.", "default": 0 }, "last_pass_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The most recent completed pass over any of these rules.", "default": null }, "reading_rules": { "type": "integer", "format": "int64", "description": "Active rules of this program that trigger on a reading arriving. Zero\nmeans no rule was ever meant to look at this program's readings, so\nreadings nothing evaluated are the design, not a failure.", "default": 0 }, "rules": { "type": "integer", "format": "int64", "default": 0 }, "rules_checked": { "type": "integer", "format": "int64", "description": "Rules with a completed pass since the period began, whose latest pass\ndid not fail.", "default": 0 }, "rules_failing": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Rules whose most recent pass failed.", "default": [] }, "rules_new": { "type": "integer", "format": "int64", "description": "Rules created during the period that have not had a pass yet.", "default": 0 }, "rules_not_checked": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Rules the worker did not carry through this period: no recent completed\npass, or a recorded gap that ended inside the period.", "default": [] } } }, "SessionDeviceInfo": { "type": "object", "required": [ "ingest_device_id", "device_id" ], "properties": { "device_id": { "type": "string" }, "device_profile_id": { "type": [ "string", "null" ], "format": "uuid" }, "ingest_device_id": { "type": "string", "format": "uuid" }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "sampling_profile_name": { "type": [ "string", "null" ] } } }, "SessionDeviceSpec": { "type": "object", "required": [ "device_id" ], "properties": { "battery": { "type": [ "integer", "null" ], "format": "int32" }, "device_id": { "type": "string" }, "device_profile_id": { "type": [ "string", "null" ], "format": "uuid" }, "device_profile_key": { "type": [ "string", "null" ] }, "firmware": { "type": [ "string", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "sampling_profile_name": { "type": [ "string", "null" ] } } }, "SessionListItem": { "type": "object", "required": [ "id", "xuser_id", "project_id", "organization_id", "started_at", "total_devices", "total_chunks", "total_size_bytes", "compressed_size_bytes", "devices" ], "properties": { "compressed_size_bytes": { "type": "integer", "format": "int64" }, "description": { "type": [ "string", "null" ] }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/SessionDeviceInfo" } }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "metadata": { "description": "Session metadata (client_info provenance, etc.)" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "type": "integer", "format": "int32" }, "project_id": { "type": "integer", "format": "int32" }, "quality": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SessionQualitySummary", "description": "Quality figures, reduced to the session's weakest signal stream.\n\nAbsent when the session has no streams at all. Present-but-unassessed\n(`streams_assessed == 0`) is a distinct state and must not be read as a\nscore: a session not yet assessed is not a bad session." } ] }, "started_at": { "type": "string", "format": "date-time" }, "total_chunks": { "type": "integer", "format": "int32" }, "total_devices": { "type": "integer", "format": "int32" }, "total_size_bytes": { "type": "integer", "format": "int64" }, "xuser_id": { "type": "string", "format": "uuid" } } }, "SessionQualitySummary": { "type": "object", "description": "Compact quality figures for one session, safe to embed in a list row.", "required": [ "streams_total", "streams_assessed", "streams" ], "properties": { "pct_lost": { "type": [ "number", "null" ], "format": "double", "description": "Share lost in transit, by the device or the link. The patient can act on\nthis." }, "pct_undecodable": { "type": [ "number", "null" ], "format": "double", "description": "Share that arrived but could not be decoded: a platform-side defect,\nreported apart from `pct_lost` because the device and the link are not\nat fault." }, "pct_usable": { "type": [ "number", "null" ], "format": "double", "description": "Share of the expected signal present and readable, for that stream." }, "streams": { "type": "array", "items": { "$ref": "#/components/schemas/StreamQuality" }, "description": "Every stream, in worst-first order so a surface that truncates shows the\nproblem rather than hiding it below a fold." }, "streams_assessed": { "type": "integer", "format": "int32", "description": "Of those, how many have been assessed. Zero means \"not assessed yet\": the\npercentages are then absent and must not be read as a score." }, "streams_total": { "type": "integer", "format": "int32", "description": "Streams belonging to this session." }, "weakest_signal_type": { "type": [ "string", "null" ], "description": "The weakest stream's signal type, e.g. `ecg`. Absent when unassessed.\n`streams` carries the full detail." } } }, "SessionStartBody": { "type": "object", "required": [ "xuser_id", "devices" ], "properties": { "client_info": { "description": "Client provenance info (SDK version, app version, OS, device model),\nstored as the session's metadata." }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/SessionDeviceSpec" } }, "project_id": { "type": [ "integer", "null" ], "format": "int32" }, "project_key": { "type": [ "string", "null" ] }, "xuser_id": { "type": "string", "format": "uuid" } } }, "SessionStartConflictResp": { "type": "object", "required": [ "message", "active_session_id", "started_at" ], "properties": { "active_session_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" }, "started_at": { "type": "string" } } }, "SessionStartResp": { "type": "object", "required": [ "ingest_session_id", "devices" ], "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/SessionDeviceInfo" } }, "ingest_session_id": { "type": "string", "format": "uuid" } } }, "SetOrderReferenceBody": { "type": "object", "properties": { "order_reference": { "type": [ "string", "null" ], "description": "Free text or an identifier from the clinic's own system. `null` or\nblank clears it." } } }, "SmsDisclosurePreview": { "type": "object", "required": [ "version", "rendered_text", "text_hash" ], "properties": { "rendered_text": { "type": "string" }, "text_hash": { "type": "string" }, "version": { "type": "string" } } }, "SmsOptIn": { "type": "object", "required": [ "granted", "phone", "request_id", "disclosure_acknowledgment" ], "properties": { "captcha_token": { "type": [ "string", "null" ], "description": "Required to request an invitation; absent tokens fail closed without blocking enrollment." }, "disclosure_acknowledgment": { "$ref": "#/components/schemas/DisclosureAcknowledgment", "description": "The disclosure the patient actually saw. Its `acknowledged_at` may be\nretained unchanged across retries, exactly like `request_id`: an\nacknowledgment is accepted from up to 30 days in the past to up to 1\nhour ahead of server time, so a backoff retry, a queued offline capture,\nor a handset clock that drifted is never refused for being stale." }, "granted": { "type": "boolean" }, "phone": { "type": "string" }, "request_id": { "type": "string", "format": "uuid", "description": "Generate once per checkbox submission; retain unchanged across retries." } } }, "SmsOptInResult": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Uniform acknowledgment, never an address's consent or delivery state." } } }, "StaffMember": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "StaffResponse": { "type": "object", "required": [ "items", "environment_id" ], "properties": { "environment_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/StaffMember" } } } }, "StartSessionQuery": { "type": "object", "properties": { "resume_if_active": { "type": [ "boolean", "null" ] } } }, "StreamQuality": { "type": "object", "description": "Quality for one signal stream.", "required": [ "signal_type" ], "properties": { "pct_lost": { "type": [ "number", "null" ], "format": "double", "description": "Share lost in transit, by the device or the link. The patient can act on\nthis." }, "pct_undecodable": { "type": [ "number", "null" ], "format": "double", "description": "Share that arrived but could not be decoded: a platform-side defect, not\nthe device or the link." }, "pct_usable": { "type": [ "number", "null" ], "format": "double", "description": "Share of the expected signal present and readable. Absent when the\nstream has not been assessed yet, which is not the same as zero." }, "signal_type": { "type": "string" }, "snr_db": { "type": [ "number", "null" ], "format": "double", "description": "Signal-to-noise ratio in dB: fidelity, not completeness. Read it beside\n`pct_usable`, since a complete but noisy stream can read 100% usable." } } }, "Totals": { "type": "object", "required": [ "decisions", "observe", "enforce", "pending", "unavailable", "transcript" ], "properties": { "decisions": { "type": "integer", "format": "int64", "description": "Every decision record in the window, any mode or status." }, "enforce": { "type": "integer", "format": "int64" }, "observe": { "type": "integer", "format": "int64" }, "pending": { "type": "integer", "format": "int64" }, "transcript": { "type": "integer", "format": "int64", "description": "Records that came from a transcript batch rather than a\nlive call; always observe, counted in `observe` as well." }, "unavailable": { "type": "integer", "format": "int64" } } }, "TouchRate": { "type": "object", "description": "Measure 2 over one period.", "required": [ "touches", "patient_days" ], "properties": { "patient_days": { "type": "number", "format": "double" }, "per_patient_month": { "type": [ "number", "null" ], "format": "double", "description": "`touches * 30 / patient_days`; `null` when no patient was in the\nprogram during the period." }, "touches": { "type": "integer", "format": "int64" } } }, "TouchRateMeasure": { "allOf": [ { "$ref": "#/components/schemas/MeasureAbout" }, { "type": "object", "properties": { "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TouchRate", "description": "`null` when the program has no baseline recorded." } ] }, "period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TouchRate" } ] } } } ] }, "TranscriptBatch": { "type": "object", "required": [ "turns" ], "properties": { "application_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional; when present it must be the application the key is bound to." }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptTurn" }, "description": "One to 1000 turns; `turn_id` unique within the batch." } } }, "TranscriptJobStatus": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "TranscriptJobView": { "type": "object", "description": "A job as the contract presents it. Counts, never text.", "required": [ "job_id", "application_id", "status", "total", "processed", "evaluated", "duplicate", "abandoned", "unavailable", "would_have", "submitted_at" ], "properties": { "abandoned": { "type": "integer", "format": "int64", "description": "Turns a failed job gave up on: never evaluated, no decision, their\ntext cleared with the job. Only ever non-zero when `status` is\n`failed`." }, "application_id": { "type": "string", "format": "uuid" }, "duplicate": { "type": "integer", "format": "int64" }, "error": { "type": [ "string", "null" ], "description": "A code when `status` is `failed`." }, "evaluated": { "type": "integer", "format": "int64" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "job_id": { "type": "string", "format": "uuid" }, "processed": { "type": "integer", "format": "int64", "description": "Turns processed so far: `evaluated + duplicate`." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/TranscriptJobStatus" }, "submitted_at": { "type": "string", "format": "date-time" }, "total": { "type": "integer", "format": "int64", "description": "Turns in the batch." }, "unavailable": { "type": "integer", "format": "int64", "description": "Evaluated turns the gate did not answer for." }, "would_have": { "type": "object", "description": "Raw gate decisions over the evaluated turns that are decided:\n`allow`, `rewrite`, `block_and_review`, `policy_missing`,\n`unavailable`.", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } } } }, "TranscriptTurn": { "type": "object", "description": "One past turn as the customer posts it.", "required": [ "conversation_id", "turn_id", "channel", "audience", "content", "sent_at" ], "properties": { "audience": { "$ref": "#/components/schemas/GovernAudience" }, "channel": { "$ref": "#/components/schemas/GovernChannel" }, "content": { "type": "string", "description": "The text that went out." }, "conversation_id": { "type": "string" }, "model": { "type": [ "string", "null" ], "description": "The model that produced the turn, and its version, as the customer names\nthem. Optional; recorded on the decision, never interpreted. Use them to\ntell apart turns from before and after a model change." }, "model_version": { "type": [ "string", "null" ] }, "sent_at": { "type": "string", "format": "date-time", "description": "When it went out. The observe report windows on it." }, "turn_id": { "type": "string", "description": "The idempotency key per application: a turn the application already\nhas a decision for is a `duplicate`. Must not start with `govern:`,\nwhich is reserved for the rows the platform writes." } } }, "TranscriptTurnView": { "type": "object", "description": "One turn of a job, with the decision it produced or matched.", "required": [ "position", "conversation_id", "turn_id", "channel", "audience", "sent_at", "reasons" ], "properties": { "audience": { "type": "string" }, "channel": { "type": "string" }, "conversation_id": { "type": "string" }, "decision_id": { "type": [ "string", "null" ], "format": "uuid" }, "decision_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecisionStatus" } ] }, "disposition": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TurnDisposition", "description": "Absent until the turn is processed." } ] }, "position": { "type": "integer", "format": "int32" }, "reasons": { "type": "array", "items": { "type": "string" } }, "sent_at": { "type": "string", "format": "date-time" }, "turn_id": { "type": "string" }, "would_have": { "type": [ "string", "null" ] } } }, "TurnDisposition": { "type": "string", "enum": [ "evaluated", "duplicate", "abandoned" ] }, "UpdateOrganizationRequest": { "type": "object", "properties": { "builder_persona": { "type": [ "string", "null" ], "description": "The organization's default program-builder mode: `builder`, `prosumer` or\n`protocol_authoring`. Omit to leave the current value unchanged." }, "building_type": { "type": [ "string", "null" ], "description": "Developer self-declared intent: wellness, clinical, research, evaluating" }, "compliance_tier": { "type": [ "string", "null" ], "description": "Data handling policy: \"standard\" or \"hipaa\"" }, "developer_approach": { "type": [ "string", "null" ], "description": "\"code\" or \"ai_tools\"" }, "gbraid": { "type": [ "string", "null" ] }, "gclid": { "type": [ "string", "null" ], "description": "Google Ads click identifiers captured at landing. First write wins: once\nset, later values are ignored." }, "name": { "type": [ "string", "null" ] }, "onboarding_door": { "type": [ "string", "null" ], "description": "Which onboarding door: ble_device, wearable_cloud, ai_studio" }, "preferred_ai_tool": { "type": [ "string", "null" ], "description": "For AI-tool devs: claude, lovable, chatgpt, cursor, other" }, "preferred_language": { "type": [ "string", "null" ], "description": "For code-first devs: swift, kotlin, python, typescript, etc." }, "terminology_profile": { "type": [ "string", "null" ], "description": "UI terminology profile: \"default\", \"clinical\", or \"research\"" }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ], "description": "UTM campaign tags captured from the landing URL. First write wins, as\nfor `gclid`." }, "utm_term": { "type": [ "string", "null" ] }, "wbraid": { "type": [ "string", "null" ] }, "what_building": { "type": [ "string", "null" ], "description": "Free-text: \"What are you building?\"" } } }, "Value": {}, "VersionRequest": { "type": "object", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "format": "int32" } } }, "WebhookDeliveryView": { "type": "object", "description": "A delivery as the contract shows it on the decision. Counts and codes,\nnever the body.", "required": [ "id", "event", "subject_version", "status", "attempts", "created_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "decision_id": { "type": [ "string", "null" ], "format": "uuid" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "event": { "type": "string" }, "handoff_id": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "last_status_code": { "type": [ "integer", "null" ], "format": "int32" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`pending` | `delivered` | `exhausted` | `skipped`." }, "subject_version": { "type": "integer", "format": "int32", "description": "The revision of the subject this delivery is about: the hand-off's\n`version` at the change, or `0` for an event keyed to the subject's\nwhole lifetime. Two deliveries of one event differ here." } } }, "WithheldDraft": { "type": "object", "description": "One stopped draft, as the person working the item reads it: the draft's\nown text, written by the AI, never a patient's message.", "required": [ "check_id", "created_at", "reasons", "review_state" ], "properties": { "check_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "drafted": { "type": [ "string", "null" ], "description": "What the AI drafted. Null when no content was recorded, as for a\ndisclosure refusal." }, "policy_name": { "type": [ "string", "null" ], "description": "The policy that stopped it, and the version of it that was in force." }, "policy_version": { "type": [ "integer", "null" ], "format": "int32" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "The reason codes, in the Govern contract's vocabulary." }, "review_state": { "type": "string", "description": "`held_for_review` while it is still waiting on a reviewer, then the\nterminal state the reviewer's decision wrote." }, "stop_class": { "type": [ "string", "null" ], "description": "`never_sendable` or `uncertain`." } } }, "XUser": { "type": "object", "required": [ "id", "organization_id", "environment_id", "identifier", "name", "active", "created_at", "updated_at" ], "properties": { "active": { "type": "boolean" }, "address": { "type": [ "string", "null" ] }, "birth_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the patient was soft-deleted; null while the patient is live." }, "environment_id": { "type": "string", "format": "uuid" }, "gender_type_id": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "is_demo": { "type": "boolean", "description": "True for a throwaway demo patient created for testing." }, "last_data_sync_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache: When OAuth provider data was last synced (Fitbit, etc.)" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache: When xuser last authenticated (patient app login)" }, "last_session_end_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache: When most recent ingest session ended" }, "last_session_start_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache: When most recent ingest session started" }, "name": { "type": "string" }, "notification_preferences": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value", "description": "User's notification channel preferences\nJSON structure: { \"sdk\": { \"enabled\": true }, \"push\": { \"enabled\": true, \"token\": \"...\" }, ... }" } ] }, "organization_id": { "type": "integer", "format": "int32" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. \"America/New_York\"). Scheduled policies\nrun at local time in this zone. Defaults to `UTC` when none was supplied\nat enrollment." }, "updated_at": { "type": "string", "format": "date-time" } } }, "XUserFullResponse": { "type": "object", "required": [ "id", "organization_id", "identifier", "name", "contact_points", "project_ids", "total_sessions", "num_devices", "data_sent_mb", "organization", "project_biosignals", "has_active_session", "active_episodes_count", "highest_attention_level", "attention_level" ], "properties": { "active": { "type": [ "boolean", "null" ] }, "active_episodes_count": { "type": "integer", "format": "int32" }, "active_session_project_id": { "type": [ "integer", "null" ], "format": "int32" }, "active_session_project_name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "attention_level": { "type": "string" }, "birth_date": { "type": [ "string", "null" ], "format": "date" }, "contact_points": { "type": "array", "items": { "$ref": "#/components/schemas/ContactPoint" } }, "data_sent_mb": { "type": "integer", "format": "int64" }, "gender_type_id": { "type": [ "integer", "null" ], "format": "int32" }, "has_active_session": { "type": "boolean" }, "highest_attention_level": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_data_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_session_end_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_session_start_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "num_devices": { "type": "integer", "format": "int64" }, "organization": { "$ref": "#/components/schemas/XUserOrganization" }, "organization_id": { "type": "integer", "format": "int32" }, "phone": { "type": [ "string", "null" ], "description": "The number SMS messages to this patient are sent to, in E.164 form. Null\nwhen no number resolves, including when a stored number cannot be\nnormalized to E.164; the stored number stays in `contact_points` either\nway. Populated when reading a single patient." }, "project_biosignals": { "type": "array", "items": { "type": "string" } }, "project_ids": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "total_sessions": { "type": "integer", "format": "int64" } } }, "XUserOrganization": { "type": "object", "required": [ "id", "compliance_tier", "terminology_profile" ], "properties": { "compliance_tier": { "type": "string" }, "id": { "type": "integer", "format": "int32" }, "terminology_profile": { "type": "string" } } }, "XUserPayload": { "type": "object", "required": [ "identifier", "name" ], "properties": { "address": { "type": [ "string", "null" ] }, "birth_date": { "type": [ "string", "null" ], "format": "date" }, "gender_type_id": { "type": [ "integer", "null" ], "format": "int32" }, "identifier": { "type": "string", "example": "patient-12345" }, "is_demo": { "type": "boolean", "description": "Mark this patient as a throwaway demo participant (default false)." }, "name": { "type": "string", "example": "John Doe" }, "project_id": { "type": [ "string", "null" ], "description": "The project, as a numeric id or a project key: `\"project_id\": 123` or\n`\"project_id\": \"proj_abc123\"`. Prefer `project_key`." }, "project_key": { "type": [ "string", "null" ], "description": "Explicit project_key field (preferred)" } } }, "XUserResolvedResponse": { "type": "object", "description": "What `POST /api/v1/xusers` returns (HTTP 200) when the identifier matched\nan existing patient rather than creating one.\n\nOnly `id` describes the stored patient. `identifier` and `name` are echoed\nfrom the request, `organization_id` is the caller's own, and the remaining\nfields are fixed values. The body has the same keys as the patient record,\nso a client can decode 200 and 201 with one type. `gender_type_id`,\n`birth_date` and `address` are absent. Read the patient with\n`GET /api/v1/xusers/{xuser_id}`.", "required": [ "id", "created", "organization_id", "identifier", "name", "contact_points", "active", "project_ids", "total_sessions", "num_devices", "data_sent_mb" ], "properties": { "active": { "type": "boolean", "description": "Always `true`, not the stored flag." }, "contact_points": { "type": "array", "items": { "$ref": "#/components/schemas/ContactPoint" }, "description": "Always empty." }, "created": { "type": "boolean", "description": "Always `false`, so a client that does not read the status code can tell a\nmatch from a create." }, "data_sent_mb": { "type": "integer", "format": "int64", "description": "Always `0`, exactly as the 201 arm reports for a freshly created row." }, "id": { "type": "string", "format": "uuid", "description": "Id of the patient the identifier matched." }, "identifier": { "type": "string", "description": "Echoed from the request." }, "name": { "type": "string", "description": "Echoed from the request, not the stored name. Read the stored name with\n`GET /api/v1/xusers/{xuser_id}`." }, "num_devices": { "type": "integer", "format": "int64", "description": "Always `0`, exactly as the 201 arm reports for a freshly created row." }, "organization_id": { "type": "integer", "format": "int32", "description": "The caller's own organization. Identifiers are matched only within the\ncaller's organization and environment." }, "project_ids": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Always empty." }, "total_sessions": { "type": "integer", "format": "int64", "description": "Always `0`, exactly as the 201 arm reports for a freshly created row." } } }, "XUserUpdatePayload": { "type": "object", "required": [ "name" ], "properties": { "active": { "type": [ "boolean", "null" ] }, "address": { "type": [ "string", "null" ] }, "birth_date": { "type": [ "string", "null" ], "format": "date" }, "gender_type_id": { "type": [ "integer", "null" ], "format": "int32" }, "identifier": { "type": [ "string", "null" ] }, "name": { "type": "string", "example": "Jane Doe" }, "organization_id": { "type": [ "integer", "null" ], "format": "int32" }, "project_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32" } }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone (e.g. \"America/New_York\"), overriding the value captured at\nenrollment. An unrecognised zone is a 400." } } }, "XuserInfo": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } } }, "securitySchemes": { "bearer_token": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "platform_app_key": { "type": "http", "scheme": "bearer", "bearerFormat": "Platform app key" }, "session_cookie": { "type": "apiKey", "in": "cookie", "name": "auth_session" } } }, "tags": [ { "name": "Authentication", "description": "User authentication endpoints" }, { "name": "Projects", "description": "Project management endpoints" }, { "name": "Organizations", "description": "Organization management endpoints" }, { "name": "XUsers", "description": "Extended user (patient/participant) management endpoints" }, { "name": "Developer", "description": "Developer API key management endpoints" }, { "name": "Ingest", "description": "Biosignal data ingestion and session management endpoints" }, { "name": "Episodes", "description": "Episode data and analytics endpoints" }, { "name": "FHIR", "description": "FHIR-compatible healthcare data endpoints" }, { "name": "Admin", "description": "Internal SuperAdmin endpoints" }, { "name": "Billing Periods", "description": "Fixed-period unique-transmission-day evidence per program enrollment (staff only)" }, { "name": "Govern", "description": "Run a third party's patient-facing AI through the communication compliance gate: applications, application keys, modes, decisions" } ] }