Download OpenAPI specification:
The COSI API provides endpoints for managing a hearing assessment. The API handles authentication through magic links and JWT tokens, with different access levels for Super Admins, Admins, and Care Team members across various resources like clients, team members, content blocks, and organizations. The core functionality revolves around COSI (Client Oriented Scale of Improvement) assessments, which include managing questions, needs, and outcomes for clients' hearing situations, along with supporting features like email/SMS communications, reporting capabilities, and organization-specific branding.
This API documentation should be used in conjunction with the COSI 2.0 Integration Guide, which provides essential context about the system's workflow and business logic. The Integration Guide explains the two main organization types (In Person and Remote OTC) and their distinct assessment timelines, while this API documentation details the specific endpoints needed to implement those workflows. Together, these resources enable developers to properly sequence API calls through the complete COSI lifecycle - from client creation through assessment and outcomes stages.
Authentication and authorization operations. Only the management of end users and related COSI operations are subject to authentication. Authentication for resources is handled via magic links and JWT tokens.
Operations:
Roles:
Super Admin: Full access
Admin: Full access
Care Team: Full access
Requests a magic link for password-less authentication.
The process:
The magic link:
| email required | string <email> (Email) Email address to send magic link to |
{- "email": "user@example.com"
}{- "message": "If your email is registered, you will receive a magic link"
}Verifies a magic link token and creates an authentication session.
The verification:
Returns:
| magic_link_token required | string (Magic Link Token) |
{- "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
- "refresh_token": "8f7d3f45-9f1a-4a5b-8e6c-7d2c3b1a9f0e",
- "user": {
- "id": "123",
- "email": "user@example.com",
- "role": "admin",
- "organization": {
- "name": "Example Clinic",
- "organization_type": "IN_PERSON"
}
}
}Verifies a JWT token.
The verification:
- Validates token authenticity
- Checks token expiration
- Confirms user status
- Does NOT authenticate user yet
Returns:
- 200 if token is valid and user can set password
- 400 if token is invalid or expired
| token required | string (Token) |
nullSets the user's password after verifying the password setup JWT token and logs them in.
The process:
- Verifies password setup token
- Encrypts the provided password using bcrypt
- Saves encrypted password to user record
- Activates user if they were invited
- Creates access and refresh tokens
Returns:
- Access token (15 minute validity)
- Refresh token (14 day validity)
- User information
- Organization details (if applicable)
| password required | string (Password) New password to set for the user (must contain at least 8 characters, 1 uppercase letter, 1 lowercase letter, 1 number, and 1 special character) |
| token required | string (Token) Token from the password setup link |
{- "password": "SecurePass123!",
- "token": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}{- "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
- "refresh_token": "8f7d3f45-9f1a-4a5b-8e6c-7d2c3b1a9f0e",
- "user": {
- "id": "123",
- "email": "user@example.com",
- "role": "admin",
- "organization": {
- "name": "Example Clinic",
- "organization_type": "IN_PERSON"
}
}
}Authenticates a user using their email and password.
The process:
- Validates email and password format
- Finds user by email with proper role and status checks
- Verifies password using bcrypt
- Creates access and refresh tokens
- Activates invited users upon successful login
Security:
- Password is verified using bcrypt hashing
- Only active or invited users can login
- Only non-client users can login (superadmins or users with non-client roles)
- Returns same error for invalid email or password (for security)
Returns:
- Access token (15 minute validity)
- Refresh token (14 day validity)
- User information
- Organization details (if applicable)
| email required | string <email> (Email) User's email address |
| password required | string (Password) User's password |
{- "email": "user@example.com",
- "password": "securepassword123"
}{- "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
- "refresh_token": "8f7d3f45-9f1a-4a5b-8e6c-7d2c3b1a9f0e",
- "user": {
- "id": "123",
- "email": "user@example.com",
- "role": "admin",
- "organization": {
- "name": "Example Clinic",
- "organization_type": "IN_PERSON"
}
}
}Generates a new access token using a valid refresh token.
The process:
The refresh token:
| refresh_token required | string (Refresh Token) Valid refresh token from previous authentication |
{- "refresh_token": "8f7d3f45-9f1a-4a5b-8e6c-7d2c3b1a9f0e"
}{- "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
- "user": {
- "id": "123",
- "email": "user@example.com",
- "role": "admin"
}
}Invalidates the current refresh token, effectively logging out the user.
The process:
Note: Access tokens will still be valid until expiration (15 minutes).
| refresh_token required | string (Refresh Token) Valid refresh token from previous authentication |
{- "refresh_token": "8f7d3f45-9f1a-4a5b-8e6c-7d2c3b1a9f0e"
}{- "message": "Successfully logged out"
}Looks up a user by email and returns their organization and authentication method.
Used by the frontend to determine which authentication method to use for a user.
Users must authenticate with their configured auth_provider - no fallbacks.
Security: Returns the same response structure regardless of whether the email exists
to prevent user enumeration attacks.
Returns:
- Organization information (if user exists)
- User's configured auth_provider (if user exists and has one)
| email required | string (Email) |
{- "organization": {
- "id": 123,
- "name": "Example Org"
}, - "auth_provider": "entra_id"
}Initiates the OAuth 2.0 authentication flow for a specific organization.
The process:
Returns:
| auth_provider required | string (Auth Provider) |
| organization_id required | integer (Organization Id) |
{- "state": "random-state-string"
}Handles the callback from OAuth 2.0 authentication.
The process:
Query Parameters:
Returns:
| auth_provider required | string (Auth Provider) |
| code required | string (Code) |
| state required | string (State) |
nullRetrieves access and refresh tokens from a temporary SSO token. Used after OAuth callback to securely deliver tokens to frontend.
The session:
| token required | string (Token) |
{- "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
- "refresh_token": "8f7d3f45-9f1a-4a5b-8e6c-7d2c3b1a9f0e",
- "user": {
- "id": "123",
- "email": "user@example.com",
- "role": "admin"
}
}Initiates a password reset process by sending a reset link to the user's email.
The process:
- Validates email format
- Checks if user exists with password authentication
- Sends password reset email with secure token
- Returns same response regardless of user existence (for security)
The reset link:
- Is valid for 15 minutes
- Contains a JWT token with user email
- Links to frontend password reset page
Security:
- Returns same response for valid and invalid emails (prevents user enumeration)
- Only users with password authentication can reset passwords
- Reset tokens are time-limited and single-use
| email required | string <email> (Email) User's email address |
{- "email": "user@example.com"
}{- "message": "If an account with that email exists, you will receive a password reset link shortly."
}Resets a user's password using a valid reset token from the forgot-password email.
The process:
- Validates the reset token (JWT with email and expiration)
- Verifies token hasn't expired (15 minute validity)
- Finds user by email from token
- Encrypts and saves the new password
- Returns success confirmation
Security:
- Token must be valid and not expired
- Only users with password authentication can reset
- New password must meet security requirements
- User must log in separately after reset
Returns:
- 200 if password reset successfully
- 400 if token is invalid or expired
| token required | string (Token) Reset token from the password reset email |
| password required | string (Password) >= 8 characters New password to set (must contain at least 8 characters, 1 uppercase letter, 1 lowercase letter, 1 number, and 1 special character) |
{- "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
- "password": "NewSecurePass123!"
}{- "message": "Password reset successfully"
}Accessible By: Super Admins
Read only User operations. All operations are restricted to Super Admins.
Roles:
Super Admin: Full access on Users across all Organizations
Admin: No access
Care Team: No access ,
Retrieves a list of users with pagination and search support. Only accessible by Super Admins.
Users include:
Supports filtering by:
Results include:
| _start | integer ( Start) Default: 0 Starting index for pagination |
| _end | integer ( End) Ending index for pagination |
| _sort | string ( Sort) Default: "last_name" Field to sort by. Valid options: id, first_name, last_name, email, status, created_at |
| _order | string ( Order) Default: "ASC" Sort order: ASC or DESC |
Q (string) or Q (null) (Q) |
[- {
- "id": 123,
- "email": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "status": "ACTIVE",
- "role": "CLIENT",
- "organizations": [
- {
- "id": 456,
- "name": "Example Clinic",
- "role": "CLIENT"
}
], - "user_organizations": [
- {
- "id": 789,
- "organization_id": 456,
- "user_id": 123,
- "role": "CLIENT"
}
]
}
]Retrieves detailed information about a specific user. Only accessible by Super Admins.
The response includes:
| user_id required | integer (User Id) |
{- "id": 123,
- "email": "user@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "status": "active",
- "role": "client",
- "organizations": [
- {
- "id": 456,
- "name": "Example Clinic",
- "role": "client"
}
], - "jobs": [
- {
- "id": 789,
- "type": "send_email",
- "status": "completed",
- "created_at": "2024-01-01T00:00:00Z"
}
], - "phone": "+61412345678",
- "sms_enabled": true,
- "last_login": "2024-01-01T00:00:00Z"
}Clients are Users that are the end users of the COSI application.
Operations:
Roles:
Super Admin: Full access on Clients across all Organizations
Admin: Access to Clients in their Organization
Care Team: Access to Clients in their Organization
Lists clients with optional filtering, sorting, and pagination.
Different users have different access levels:
Supports filtering by:
Supports sorting by:
| _start | integer ( Start) Default: 0 Starting index for pagination |
| _end | integer ( End) Ending index for pagination |
Q (string) or Q (null) (Q) Search term to filter clients by name or email | |
OrganizationType (string) or Organization Type (null) (Organization Type) Filter by in_person or remote_otc organization type | |
CosiStatus (string) or Status (null) (Status) Filter by created, assessment_scheduled, assessment_done, assessment_done, outcomes_scheduled, outcomes_sent, outcomes_done, or archived status | |
| order_date | string (Order Date) Default: "all" Filter by order date range: all, last_7_days, last_14_days, last_30_days, last_100_days, past, today |
| evaluation_date | string (Evaluation Date) Default: "all" Filter by evaluation date range: all, last_7_days, last_14_days, last_30_days, last_100_days, past, today |
| outcomes_date | string (Outcomes Date) Default: "all" Filter by outcomes date range: all, last_7_days, last_14_days, last_30_days, last_100_days, past, today |
| _sort | string ( Sort) Default: "last_name" Field to sort by. Valid options: first_name, last_name, email, mobile_phone_number, status, evaluation_date, order_date, outcomes_date |
| _order | string ( Order) Default: "ASC" Sort order: ASC or DESC |
[- {
- "id": 123,
- "email": "client@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "mobile_phone_number": "+15105551212",
- "cosi": {
- "id": 456,
- "organization_type": "in_person",
- "evaluation_date": "2024-01-01T00:00:00Z",
- "outcomes_date": "2024-01-15T00:00:00Z",
- "status": "assessment_scheduled",
- "created_at": "2024-01-01T00:00:00Z"
}
}
]Creates a new client and associated COSI.
The client will be associated with:
For In Person organizations:
For Remote OTC organizations:
Returns the created client with their COSI details.
First Name (string) or First Name (null) (First Name) Client's first name | |
Last Name (string) or Last Name (null) (Last Name) Client's last name | |
Email Address (string) or Email Address (null) (Email Address) Client's email address for notifications and communication | |
Mobile Phone (string) or Mobile Phone (null) (Mobile Phone) Client's mobile phone number in E.164 format (e.g., +15105551212) for SMS notifications | |
Organization (string) or Organization (null) (Organization) Organization name - required for Super Admins, ignored for Admins and Care Team members | |
Evaluation Date (string) or Evaluation Date (null) (Evaluation Date) Evaluation date - required for In Person organizations | |
Order Date (string) or Order Date (null) (Order Date) Order date - required for Remote OTC organizations | |
External ID (string) or External ID (null) (External ID) External Id - optional |
{- "first_name": "string",
- "last_name": "string",
- "email": "string",
- "mobile_phone_number": "string",
- "organization_name": "string",
- "evaluation_date": "2019-08-24T14:15:22Z",
- "order_date": "2019-08-24T14:15:22Z",
- "external_id": "string"
}{- "id": 123,
- "first_name": "John",
- "last_name": "Doe",
- "email": "john@example.com",
- "external_id": "ABC1234567890",
- "mobile_phone_number": "+15105551212",
- "status": "active",
- "created_at": "2024-01-01T00:00:00Z",
- "cosi": {
- "id": 456,
- "organization_type": "in_person",
- "evaluation_date": "2024-01-01T00:00:00Z",
- "outcomes_date": "2024-01-15T00:00:00Z",
- "status": "assessment_scheduled",
- "created_at": "2024-01-01T00:00:00Z"
}
}Retrieves detailed information about a specific client including their COSI data.
Different users have different access levels:
| user_id required | integer (User Id) |
{- "id": 123,
- "first_name": "John",
- "last_name": "Doe",
- "email": "john@example.com",
- "mobile_phone_number": "+15105551212",
- "external_id": "ABC1234567890",
- "status": "active",
- "created_at": "2024-01-01T00:00:00Z",
- "cosi": {
- "id": 456,
- "organization_type": "in_person",
- "evaluation_date": "2024-01-01T00:00:00Z",
- "outcomes_date": "2024-01-15T00:00:00Z",
- "status": "assessment_scheduled",
- "created_at": "2024-01-01T00:00:00Z"
}
}Updates a client's personal information and/or COSI details.
Different users have different access levels:
Supports updating:
Note: Date updates will trigger appropriate COSI status changes and email notifications.
| user_id required | integer (User Id) |
First Name (string) or First Name (null) (First Name) Client's first name | |
Last Name (string) or Last Name (null) (Last Name) Client's last name | |
Email (string) or Email (null) (Email) Client's email address for notifications | |
Mobile Phone Number (string) or Mobile Phone Number (null) (Mobile Phone Number) Client's mobile phone number in E.164 format (e.g., +15105551212) for SMS notifications | |
Outcomes Date (string) or Outcomes Date (null) (Outcomes Date) Date for In Person outcomes - updates COSI status to outcomes_scheduled | |
Evaluation Date (string) or Evaluation Date (null) (Evaluation Date) Date for In Person evaluation - updates COSI status to assessment_scheduled | |
Order Date (string) or Order Date (null) (Order Date) Date for Remote OTC order - updates COSI status based on current stage | |
Archive (boolean) or Archive (null) (Archive) When true, archives the client's COSI | |
Archive Reason (string) or Archive Reason (null) (Archive Reason) Reason for archiving the COSI | |
External Id (string) or External Id (null) (External Id) External Id - optional |
{- "first_name": "string",
- "last_name": "string",
- "email": "string",
- "mobile_phone_number": "string",
- "outcomes_date": "2019-08-24T14:15:22Z",
- "evaluation_date": "2019-08-24T14:15:22Z",
- "order_date": "2019-08-24T14:15:22Z",
- "archive": true,
- "archive_reason": "string",
- "external_id": "string"
}{- "id": 123,
- "email": "updated@example.com",
- "first_name": "Updated",
- "last_name": "Name",
- "mobile_phone_number": "+15105551212",
- "cosi": {
- "id": 456,
- "organization_type": "in_person",
- "evaluation_date": "2024-01-01T00:00:00Z",
- "outcomes_date": "2024-01-15T00:00:00Z",
- "status": "assessment_scheduled",
- "created_at": "2024-01-01T00:00:00Z"
}
}Team Members are Users that are administrators or care team members for a particular Organization.
Operations:
Roles:
Super Admin: Full access on Team Members across all Organizations
Admin: Access to Team Members in their Organization
Care Team: Access to Team Members in their Organization
Retrieves a list of team members with pagination and search support.
Access levels:
Team members include:
Supports filtering by:
Results include:
| _start | integer ( Start) Default: 0 Starting index for pagination |
| _end | integer ( End) Ending index for pagination |
Q (string) or Q (null) (Q) Search term |
[- {
- "id": 123,
- "email": "team@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "status": "active",
- "organizations": [
- {
- "id": 456,
- "name": "Example Clinic"
}
], - "user_organizations": [
- {
- "id": 789,
- "organization_id": 456,
- "user_id": 123,
- "role": "care_team"
}
]
}
]Creates a new team member and sends an invitation email.
Required fields:
The team member will receive:
| first_name required | string (First Name) Team member's first name |
| last_name required | string (Last Name) Team member's last name |
| email required | string (Email) Team member's email address for login and notifications |
Role (string) or Role (null) (Role) Team member's role (admin, care_team, super_admin) | |
Organization Name (string) or Organization Name (null) (Organization Name) Organization name (required for Super Admins creating team members) |
{- "first_name": "string",
- "last_name": "string",
- "email": "string",
- "role": "string",
- "organization_name": "string"
}{- "id": 123,
- "email": "newteam@example.com",
- "first_name": "Jane",
- "last_name": "Smith",
- "status": "invited",
- "organizations": [
- {
- "id": 456,
- "name": "Example Clinic"
}
], - "user_organizations": [
- {
- "id": 789,
- "organization_id": 456,
- "user_id": 123,
- "role": "admin"
}
]
}Updates a team member's status. Only accessible by Organization Admins and Super Admins.
Available statuses:
| id required | integer (Id) |
Status (string) or Status (null) (Status) New status for the team member (e.g., 'inactive' to disable access) | |
Email (string) or Email (null) (Email) Team member's email address for login and notifications | |
First Name (string) or First Name (null) (First Name) Team member's first name | |
Last Name (string) or Last Name (null) (Last Name) Team member's last name | |
Role (string) or Role (null) (Role) Team member's role (admin, care_team, super_admin) | |
Auth Provider (string) or Auth Provider (null) (Auth Provider) Team member's auth provider (okta, google, magic_link) | |
Organization Name (string) or Organization Name (null) (Organization Name) Team member's organization name. Only Super Admins can change this. |
{- "status": "string",
- "email": "string",
- "first_name": "string",
- "last_name": "string",
- "role": "string",
- "auth_provider": "string",
- "organization_name": "string"
}{- "id": 123,
- "email": "team@example.com",
- "first_name": "John",
- "last_name": "Doe",
- "status": "inactive",
- "organizations": [
- {
- "id": 456,
- "name": "Example Clinic"
}
], - "user_organizations": [
- {
- "id": 789,
- "organization_id": 456,
- "user_id": 123,
- "role": "care_team"
}
]
}Retrieves detailed information for a specific team member.
Access levels:
Returns:
| id required | integer (Id) |
{- "first_name": "John",
- "last_name": "Doe",
- "email": "john.doe@example.com",
- "status": "active",
- "organization_name": "Example Clinic",
- "role": "care_team",
- "auth_provider": "magic_link",
- "created_at": "2024-01-01T00:00:00Z"
}Resends the invitation email to a team member. Only accessible by Organization Admins and Super Admins.
The new invitation will:
| id required | integer (Id) |
nullJobs are scheduled tasks such as sending email and SMS messages.
Operations:
Roles:
API: Execution of jobs on a peridoic basis.
Super Admins: Run individual jobs manually.
Admins: No access
Care Team: No access
Manually triggers execution of a specific job. Only accessible by Super Admins.
Jobs can include:
| job_id required | integer (Job Id) |
{- "message": "Job completed"
}Organizations are top-level entities that use the COSI application. Organization can be configured with a logo, name, and other branding elements.
Operations:
Roles:
Super Admin: Full access
Admin: No access
Care Team: No access
Get list of countries that have configured Twilio numbers for SMS notifications.
Each country entry includes:
[- {
- "code": "AU",
- "name": "Australia"
}, - {
- "code": "NZ",
- "name": "New Zealand"
}
]Retrieves a list of organizations with pagination and search support.
Access levels:
Supports filtering by:
| _start | integer ( Start) Default: 0 Starting index for pagination |
| _end | integer ( End) Ending index for pagination |
Q (string) or Q (null) (Q) Search term | |
Archived (boolean) or Archived (null) (Archived) Filter by archived status (true/false) |
[- {
- "id": 123,
- "name": "Example Clinic",
- "organization_type": "in_person",
- "assessment_send_days": 7,
- "outcomes_send_days": 30,
- "primary_color": "#FF0000",
- "button_text_color": "#FFFFFF",
- "compact_display": false,
- "country": "AU",
- "mail_from_name": "Example Clinic Support",
- "auth_provider": "magic_link",
- "store_pii": false
}
]Creates a new organization. Only accessible by Super Admins.
Required fields:
Optional fields:
| name required | string (Name) Organization's name |
| organization_type required | string (Organization Type) Type of organization (in_person or remote_otc) |
Assessment Send Days (integer) or Assessment Send Days (null) (Assessment Send Days) Number of days after which to send assessment reminders (optional; null when send_communications is false) | |
Outcomes Send Days (integer) or Outcomes Send Days (null) (Outcomes Send Days) Number of days after which to send outcomes reminders (optional; null when send_communications is false) | |
Country (string) or Country (null) (Country) Country code where organization operates | |
Mail From Name (string) or Mail From Name (null) (Mail From Name) Display name used in email communications | |
Primary Color (string) or Primary Color (null) (Primary Color) Primary brand color in hex format (e.g., #FF0000) | |
Button Text Color (string) or Button Text Color (null) (Button Text Color) Button text color in hex format (e.g., #FFFFFF) | |
| compact_display | boolean (Compact Display) Default: false Whether to use compact display mode for mobile web views |
Auth Provider (string) or Auth Provider (null) (Auth Provider) Authentication provider for the organization (okta, magic_link) | |
| store_pii required | boolean (Store Pii) Whether the organization stores PII |
| send_communications | boolean (Send Communications) Default: true Whether the organization sends communications (emails, SMS) |
Routing Email (string) or Routing Email (null) (Routing Email) Email address used for routing emails when store_pii is false |
{- "name": "string",
- "organization_type": "string",
- "assessment_send_days": 0,
- "outcomes_send_days": 0,
- "country": "string",
- "mail_from_name": "string",
- "primary_color": "string",
- "button_text_color": "string",
- "compact_display": false,
- "auth_provider": "string",
- "store_pii": true,
- "send_communications": true,
- "routing_email": "string"
}{- "id": 123,
- "name": "New Clinic",
- "organization_type": "in_person",
- "assessment_send_days": 7,
- "outcomes_send_days": 30,
- "primary_color": "#FF0000",
- "button_text_color": "#FFFFFF",
- "compact_display": false,
- "country": "AU",
- "mail_from_name": "New Clinic Support",
- "auth_provider": "magic_link",
- "store_pii": false
}Updates an existing organization's details. Only accessible by Super Admins.
Updatable fields:
| organization_id required | integer (Organization Id) |
Name (string) or Name (null) (Name) Organization's name | |
Organization Type (string) or Organization Type (null) (Organization Type) Type of organization (in_person or remote_otc) | |
Assessment Send Days (integer) or Assessment Send Days (null) (Assessment Send Days) Number of days after which to send assessment reminders | |
Outcomes Send Days (integer) or Outcomes Send Days (null) (Outcomes Send Days) Number of days after which to send outcomes reminders | |
Country (string) or Country (null) (Country) Country code where organization operates | |
Mail From Name (string) or Mail From Name (null) (Mail From Name) Display name used in email communications | |
Primary Color (string) or Primary Color (null) (Primary Color) Primary brand color in hex format (e.g., #FF0000) | |
Button Text Color (string) or Button Text Color (null) (Button Text Color) Button text color in hex format (e.g., #FFFFFF) | |
Compact Display (boolean) or Compact Display (null) (Compact Display) Whether to use compact display mode for mobile web views | |
Auth Provider (string) or Auth Provider (null) (Auth Provider) Authentication provider for the organization (okta, magic_link) | |
Store Pii (boolean) or Store Pii (null) (Store Pii) Whether the organization stores PII | |
Send Communications (boolean) or Send Communications (null) (Send Communications) Whether the organization sends communications (emails, SMS) | |
Archived (boolean) or Archived (null) (Archived) Whether the organization is archived | |
Routing Email (string) or Routing Email (null) (Routing Email) Email address used for routing emails when store_pii is false | |
Websocket Stt Enabled (boolean) or Websocket Stt Enabled (null) (Websocket Stt Enabled) Whether to use the Deepgram WebSocket STT path (true) or the HTTP fallback (false) |
{- "name": "string",
- "organization_type": "string",
- "assessment_send_days": 0,
- "outcomes_send_days": 0,
- "country": "string",
- "mail_from_name": "string",
- "primary_color": "string",
- "button_text_color": "string",
- "compact_display": true,
- "auth_provider": "string",
- "store_pii": true,
- "send_communications": true,
- "archived": true,
- "routing_email": "string",
- "websocket_stt_enabled": true
}{- "id": 123,
- "name": "Updated Clinic Name",
- "organization_type": "in_person",
- "assessment_send_days": -14,
- "outcomes_send_days": 45,
- "primary_color": "#00FF00",
- "button_text_color": "#000000",
- "compact_display": true,
- "country": "AU",
- "mail_from_name": "Updated Clinic Support",
- "auth_provider": "okta",
- "store_pii": true,
- "routing_email": "email_routing@example.com"
}Retrieves detailed information about a specific organization. Only accessible by Super Admins.
| organization_id required | integer (Organization Id) |
{- "id": 123,
- "name": "Example Clinic",
- "organization_type": "in_person",
- "assessment_send_days": 7,
- "outcomes_send_days": 30,
- "primary_color": "#FF0000",
- "button_text_color": "#FFFFFF",
- "compact_display": false,
- "country": "AU",
- "mail_from_name": "Example Clinic Support",
- "auth_provider": "magic_link",
- "store_pii": false
}Uploads a logo image for an organization. Only accessible by Super Admins.
Requirements:
| organization_id required | integer (Organization Id) |
| logo required | string <binary> (Logo) |
{- "id": 123,
- "name": "Example Clinic",
- "organization_type": "IN_PERSON",
- "assessment_send_days": 7,
- "outcomes_send_days": 30,
- "primary_color": "#FF0000",
- "button_text_color": "#FFFFFF",
- "compact_display": false,
- "country": "AU",
- "mail_from_name": "Example Clinic Support",
- "auth_provider": "magic_link",
- "store_pii": false
}Creates multiple clients for a specific organization in bulk. Only accessible by Super Admins.
This endpoint creates clients with:
Parameters:
Generated clients will have:
| organization_id required | integer (Organization Id) |
| identifier_prefix required | string (Identifier Prefix) Prefix for the client identifiers (e.g., 'AB', 'DM') |
| count required | integer (Count) [ 1 .. 1000 ] Number of clients to create (1-1000) |
{- "identifier_prefix": "string",
- "count": 1
}{- "created_count": 3
}Content Blocks are reusable blocks of text that are used in the COSI application. These blocks of text can be Organization specific or global (default) to all Organizations. Supports HTML formatting.
Operations:
Roles:
Super Admin: Full access
Admin: No access
Care Team: No access
Retrieves a list of content blocks with pagination and search support. Only accessible by Super Admins.
Content blocks are templates used for:
Supports filtering by:
| _start | integer ( Start) Default: 0 Starting index for pagination |
| _end | integer ( End) Ending index for pagination |
Q (string) or Q (null) (Q) Search query string | |
Organization Type (string) or Organization Type (null) (Organization Type) Filter by organization type |
[- {
- "id": 123,
- "name": "COSI_OUTCOMES_SUMMARY_EMAIL",
- "content": "Your outcomes summary....",
- "description": "Email sent to clients with their outcomes summary",
- "language": "en",
- "organization_type": "in_person",
- "organization": {
- "id": 456,
- "name": "Example Org"
}, - "is_default": false
}
]Creates a new content block template. Only accessible by Super Admins.
Content blocks can be:
Organization-specific blocks override default blocks for that organization.
| name required | string (Name) Template identifier (e.g., COSI_OUTCOMES_SUMMARY_EMAIL) |
| content required | string (Content) The actual template content |
Description (string) or Description (null) (Description) Human-readable description of the template's purpose | |
Organization Type (string) or Organization Type (null) (Organization Type) Type of organization this template is for (in_person, remote_otc, or None for global templates) | |
Organization Name (string) or Organization Name (null) (Organization Name) Name of organization this template belongs to. If not provided, creates a default template | |
| language required | string (Language) Language code for this template (e.g., 'en') |
{- "name": "string",
- "content": "string",
- "description": "string",
- "organization_type": "string",
- "organization_name": "string",
- "language": "string"
}{- "id": 123,
- "name": "COSI_OUTCOMES_SUMMARY_EMAIL",
- "content": "Your outcomes summary....",
- "description": "Email sent to clients with their outcomes summary",
- "language": "en",
- "organization_type": "in_person",
- "organization": {
- "id": 456,
- "name": "Example Org"
}, - "is_default": false
}Updates an existing content block's details. Only accessible by Super Admins.
Updatable fields:
Note: Changing organization may affect which clients see this content.
| content_block_id required | integer (Content Block Id) |
Name (string) or Name (null) (Name) Template identifier (e.g., COSI_OUTCOMES_SUMMARY_EMAIL) | |
Content (string) or Content (null) (Content) The actual template content | |
Description (string) or Description (null) (Description) Human-readable description of the template's purpose | |
Organization Type (string) or Organization Type (null) (Organization Type) Type of organization this template is for (in_person, remote_otc, or None for global templates) | |
Organization Name (string) or Organization Name (null) (Organization Name) Name of organization this template belongs to. If not provided, creates a default template | |
Language (string) or Language (null) (Language) Language code for this template (e.g., 'en') |
{- "name": "string",
- "content": "string",
- "description": "string",
- "organization_type": "string",
- "organization_name": "string",
- "language": "string"
}{- "id": 123,
- "name": "COSI_OUTCOMES_SUMMARY_EMAIL",
- "content": "Updated instructions...",
- "description": "Email sent to clients with their outcomes summary",
- "language": "en",
- "organization_type": "in_person",
- "organization": {
- "id": 456,
- "name": "Example Org"
}, - "is_default": false
}Retrieves details of a specific content block by ID. Only accessible by Super Admins.
| content_block_id required | integer (Content Block Id) |
{- "id": 123,
- "name": "COSI_OUTCOMES_SUMMARY_EMAIL",
- "content": "Your outcomes summary....",
- "description": "Email sent to clients with their outcomes summary",
- "language": "en",
- "organization_type": "in_person",
- "organization": {
- "id": 456,
- "name": "Example Org"
}, - "is_default": false
}COSI Questions are the questions that are asked of the Client during the assessment stage. Every COSI Need is associated with a series of related COSI Questions.
Operations:
Roles:
Client: Full access
Retrieves the next question in the assessment stage of the COSI.
The sequence is determined by:
The response includes:
| slug required | string (Slug) |
| situation required | integer (Situation) |
| position required | integer (Position) |
{- "id": 123,
- "situation": 1,
- "position": 2,
- "question": "In what situations do you experience the most difficulty?",
- "created_at": "2024-01-01T00:00:00Z"
}Records a client's answer to a specific COSI question.
The submission:
Required fields:
The response includes validation results and any error messages.
| slug required | string (Slug) |
| answer required | string (Answer) Client's response text |
| position required | integer (Position) Question number within the situation |
| situation required | integer (Situation) Current situation number |
{- "answer": "string",
- "position": 0,
- "situation": 0
}{- "id": 123,
- "situation": 1,
- "position": 2,
- "question": "In what situations do you experience the most difficulty?",
- "answer": "Noisy restaurants and social gatherings",
- "is_valid": true,
- "is_last": false,
- "created_at": "2024-01-01T00:00:00Z"
}Streaming variant of POST /cosies/{slug}/questions.
Records the client's answer and streams the AI-generated next question back as Server-Sent Events. Frames are discriminated by key presence (matching the vp-api convention):
data: {"message": "<text fragment>"}\n\n — incremental delta of the
next question text. Multiple frames per response.data: {"done": true, "question_id": ..., "is_last": ..., "next_action": ..., ...}\n\n
— terminal success frame carrying the same fields as the non-streaming
endpoint's CosiQuestionResponse, so the client can drive its existing
branching logic without a follow-up GET.data: {"error": "..."}\n\n — terminal error frame on validation
failure or unexpected exception.The response media type is text/plain. The endpoint is intentionally
public for the same reasons as the non-streaming endpoint (partner-gated
COSI assessment flow).
| slug required | string (Slug) |
| answer required | string (Answer) Client's response text |
| position required | integer (Position) Question number within the situation |
| situation required | integer (Situation) Current situation number |
{- "answer": "string",
- "position": 0,
- "situation": 0
}nullCOSI Needs are the needs that are associated with a COSI during assessment.
Operations:
Roles:
Client: Full access
Retrieves the COSI need (question) for a specific situation number.
Situations represent different hearing needs in a COSI.
The response includes:
| slug required | string (Slug) |
| situation required | integer (Situation) |
{- "cosi_id": 456,
- "need": "How often do you experience difficulty hearing in noisy situations?",
- "situation": 1,
- "is_last": false
}Records a client's answer for a specific COSI need situation.
The submission:
Required fields:
| slug required | string (Slug) |
| outcome required | string (Outcome) Client's selected answer. Must be one of: 'Much better', 'Better', 'Slightly better', 'No difference', or 'Worse' |
| situation required | integer (Situation) Sequence number of the situation being answered |
{- "outcome": "string",
- "situation": 0
}{- "cosi_id": 456,
- "need": "How often do you experience difficulty hearing in noisy situations?",
- "situation": 1,
- "is_last": false
}A COSI is the main entity in the COSI application. It represents several COSI Needs and the outcomes for each.
Operations:
Roles:
Client: Full access
Sends an assessment invitation (email and SMS) to a client. Only accessible by Super Admins and team members of the client's organization.
The invitation includes:
| cosi_id required | integer (Cosi Id) |
nullSends an outcomes invitation (email and SMS) to a client. Only accessible by Super Admins and team members of the client's organization.
The invitation includes:
| cosi_id required | integer (Cosi Id) |
nullSaves the overall outcome rating for a COSI. This represents the client's final assessment of their progress.
| slug required | string (Slug) |
Token (string) or Token (null) (Token) |
| outcome required | string (Outcome) Client's overall rating of their progress |
{- "outcome": "string"
}nullRetrieves the content and configuration for a specific COSI stage (assessment or outcomes).
The response includes:
| slug required | string (Slug) |
| stage required | string (Stage) |
Token (string) or Token (null) (Token) |
{- "slug": "john-doe-123",
- "created_at": "2024-01-01T00:00:00Z",
- "status": "assessment_scheduled",
- "organization_name": "Example Org",
- "intro_text": "Welcome to your COSI assessment...",
- "instructions_text": "<div>Before you start...</div>",
- "logo_and_company_text": "<div><img src='...'/>Example Org</div>",
- "terms_text": "Terms and conditions...",
- "last_question_text": "Final question...",
- "primary_color": "#FF0000",
- "button_text_color": "#FFFFFF",
- "compact_display": false
}Retrieves the summary of completed COSI stage (assessment or outcomes). Only available after the respective stage is completed.
The summary includes:
| slug required | string (Slug) |
| stage required | string (Stage) |
Token (string) or Token (null) (Token) |
{- "needs": [
- {
- "need": "To be able to hear my family at home more easily."
}, - {
- "need": "To follow conversations in restaurants more clearly."
}
]
}Marks the start of a COSI stage (assessment or outcomes). Records the timestamp when the client begins the process.
| slug required | string (Slug) |
| stage required | string (Stage) |
Src (string) or Src (null) (Src) | |
Token (string) or Token (null) (Token) |
nullMarks the completion of a COSI stage (assessment or outcomes).
Actions taken:
| slug required | string (Slug) |
| stage required | string (Stage) |
Token (string) or Token (null) (Token) |
nullGenerates clinical goal summaries for all situations in the assessment.
This endpoint should be called after the conversation is complete (i.e., after the last answer submission returns next_action: 'completed').
It runs summary generation, evaluation, and refinement for all situations in parallel, saves the finalized goals to the database, and returns the assessment summary.
| slug required | string (Slug) |
Token (string) or Token (null) (Token) |
{- "needs": [
- {
- "need": "string",
- "outcome": "string"
}
]
}Records the client's rating of their experience for a COSI stage.
The rating is stored as the human-readable label verbatim (e.g. "Very useful", "Somewhat useful"), matching how the outcomes fields are stored.
| slug required | string (Slug) |
| stage required | string (Stage) |
| rating required | string (Rating) [ 1 .. 100 ] characters |
Token (string) or Token (null) (Token) |
nullRecords the client's feedback about their experience for a COSI stage.
The feedback is stored as free-form text and can be used for:
| slug required | string (Slug) |
| stage required | string (Stage) |
Token (string) or Token (null) (Token) |
| feedback required | string (Feedback) [ 1 .. 2500 ] characters Client's feedback about their experience |
{- "feedback": "The assessment was very helpful and easy to understand."
}nullRetrieves detailed information about a specific COSI by ID or slug. Only accessible by team members of the client's organization.
The identifier can be either:
The response includes:
| identifier required | string (Identifier) |
{- "id": 123,
- "user_id": 456,
- "first_name": "John",
- "last_name": "Doe",
- "external_id": "1234567890",
- "overall_outcome": "Very much",
- "cosi_needs": [
- {
- "situation": 1,
- "question": "How often...",
- "outcome": "Often"
}
], - "status": "assessment_done",
- "assessment_feedback": "The assessment was very helpful and easy to understand.",
- "outcomes_feedback": "The outcomes assessment provided valuable insights into my progress.",
- "slug": "john-doe-123"
}Saves the conversation state for a COSI and updates the last accessed timestamp. Used to persist chat messages for potential recreation after page refresh.
| slug required | string (Slug) |
Token (string) or Token (null) (Token) |
{ }nullLoads the conversation state for a COSI if it was accessed within the last 5 minutes. If more than 5 minutes have passed, the conversation state is cleared and null is returned.
| slug required | string (Slug) |
Token (string) or Token (null) (Token) |
{- "state": {
- "messages": [
- {
- "html": "<p>Hello</p>",
- "sender": "user",
- "timestamp": "2024-01-01T00:00:00Z"
}
]
}
}Retrieves all COSIs for a specific user, ordered by most recent first.
Only accessible by Super Admins.
The response includes:
| user_id required | integer (User Id) User ID to filter COSIs by |
[- {
- "id": 123,
- "organization_type": "in_person",
- "status": "assessment_done",
- "slug": "abc123",
- "estimated_cost": "0.042000",
- "created_at": "2024-01-01T00:00:00Z"
}
]Audit logs are records of actions taken in the COSI application.
Operations:
Roles:
Super Admin: Full access
Admin: No access
Care Team: No access
Retrieves a list of audit logs with pagination and search support. Only accessible by Super Admins.
Audit logs track all API requests including:
Supports filtering by:
| _start | integer ( Start) Default: 0 Starting index for pagination |
| _end | integer ( End) Ending index for pagination |
Q (string) or Q (null) (Q) Search query string | |
Context (string) or Context (null) (Context) Filter by context. Available values: all, none, cosi_detail, auth, content_block |
[- {
- "id": 123,
- "method": "POST",
- "path": "/api/v1/clients",
- "status_code": 200,
- "user_id": "456",
- "user_email": "admin@example.com",
- "context": "user",
- "context_id": "789",
- "created_at": "2024-01-01T00:00:00Z",
- "request_body": {
- "email": "client@example.com"
}, - "response_body": {
- "id": "789",
- "email": "client@example.com"
}
}
]SMS management operations.
Operations:
Roles:
API: Full access
Super Admin: No access
Admin: No access
Care Team: No access
Report management operations.
Operations:
Roles:
Super Admin: Full access
Admin: No access
Care Team: No access
Downloads an Excel report of team member interactions with clients. Only accessible by Super Admins.
The report includes:
Optional filters:
Organization Id (string) or Organization Id (null) (Organization Id) Filter by organization |
nullDownloads an Excel report of client interactions and engagement. Accessible by Organization Admins and Super Admins.
The report includes:
Optional filters:
Organization Admins can only access data for their organization.
Organization Id (string) or Organization Id (null) (Organization Id) Filter by organization |
nullDownloads an Excel report of client COSI questions. Accessible by Organization Admins and Super Admins.
Optional filters:
Organization Admins can only access data for their organization.
Organization Id (string) or Organization Id (null) (Organization Id) Filter by organization |
nullDownloads an Excel report of client funnel events. Accessible by Organization Admins and Super Admins.
The report includes:
Optional filters:
Organization Admins can only access data for their organization.
Organization Id (string) or Organization Id (null) (Organization Id) Filter by organization |
nullDownloads an Excel report of client status history. Accessible by Organization Admins and Super Admins.
The report includes:
Optional filters:
Organization Admins can only access data for their organization.
Organization Id (string) or Organization Id (null) (Organization Id) Filter by organization |
nullDownloads an Excel report of message delivery logs and status. Accessible by Organization Admins and Super Admins.
The report includes:
Optional filters:
Organization Admins can only access message logs for their organization. Super Admins can access all message logs or filter by specific organization.
This report helps track:
Organization Id (string) or Organization Id (null) (Organization Id) Filter by organization |
nullDownloads an Excel report of client link for assessment adn outcomes and status. Accessible by Organization Admins and Super Admins.
The report includes:
Optional filters:
Organization Admins can only access records for their organization. Super Admins can access all records or filter by specific organization.
Organization Id (string) or Organization Id (null) (Organization Id) Filter by organization |
nullRedirects a short URL to its original destination.
Short URLs are used for:
The URL format is /{code}/hearing_needs where code is a unique identifier.
| code required | string (Code) |
Redirecting to https://example.com/original-url
Processes incoming SMS messages from Twilio. Handles client responses to SMS notifications.
Available commands:
The endpoint:
Response messages are customized based on:
| body required | string (Body) |
| from_number required | string (From Number) |
| to_number required | string (To Number) |
| message_sid required | string (Message Sid) |
nullProcesses status updates for SMS messages sent via Twilio. Updates MessageLog records with current delivery status.
Status types include:
The endpoint:
This webhook is called automatically by Twilio when message status changes, allowing real-time tracking of SMS delivery status.
| from_number required | string (From Number) |
| to_number required | string (To Number) |
| message_sid required | string (Message Sid) |
| message_status required | string (Message Status) |
nullProcesses email event notifications from SendGrid. Updates MessageLog records with email delivery and engagement status.
Event types include:
The endpoint:
SendGrid sends this webhook automatically when email events occur, enabling real-time tracking of email delivery and engagement metrics.
Security: Uses SendGrid's webhook signature verification with public key to ensure webhooks are authentic and haven't been tampered with.
nullRetrieves a list of webhooks. Only accessible by Super Admins.
Optionally filter by organization_id.
Organization Id (integer) or Organization Id (null) (Organization Id) |
[- {
- "id": 1,
- "event_name": "status_changed",
- "organization_id": 123,
- "method": "POST",
- "headers": "{\"Authorization\": \"Bearer token123\"}",
- "created_at": "2024-01-01T00:00:00Z"
}
]Creates a new webhook for an organization. Only accessible by Super Admins.
Webhooks receive notifications when specific events occur, such as when a client's COSI status changes. The webhook will be called with the specified HTTP method (GET or POST) to the provided URL.
Required fields:
Optional fields:
| url required | string (Url) URL where webhook events will be sent |
| event_name required | string (Event Name) Name of the event that triggers this webhook (e.g., 'status_changed') |
| organization_id required | integer (Organization Id) ID of the organization this webhook belongs to |
| method required | string (Method) HTTP method to use when sending webhook (GET or POST) |
Headers (string) or Headers (null) (Headers) JSON string of custom headers to include in webhook requests |
{- "url": "string",
- "event_name": "string",
- "organization_id": 0,
- "method": "string",
- "headers": "string"
}{- "id": 1,
- "event_name": "status_changed",
- "organization_id": 123,
- "method": "POST",
- "headers": "{\"Authorization\": \"Bearer token123\"}",
- "created_at": "2024-01-01T00:00:00Z"
}Retrieves detailed information about a specific webhook. Only accessible by Super Admins.
| webhook_id required | integer (Webhook Id) |
{- "id": 1,
- "event_name": "status_changed",
- "organization_id": 123,
- "method": "POST",
- "headers": "{\"Authorization\": \"Bearer token123\"}",
- "created_at": "2024-01-01T00:00:00Z"
}Updates an existing webhook's details. Only accessible by Super Admins.
All fields are optional to support partial updates.
Updatable fields:
| webhook_id required | integer (Webhook Id) |
Url (string) or Url (null) (Url) URL where webhook events will be sent | |
Event Name (string) or Event Name (null) (Event Name) Name of the event that triggers this webhook (e.g., 'status_changed') | |
Organization Id (integer) or Organization Id (null) (Organization Id) ID of the organization this webhook belongs to | |
Method (string) or Method (null) (Method) HTTP method to use when sending webhook (GET or POST) | |
Headers (string) or Headers (null) (Headers) JSON string of custom headers to include in webhook requests |
{- "url": "string",
- "event_name": "string",
- "organization_id": 0,
- "method": "string",
- "headers": "string"
}{- "id": 1,
- "event_name": "status_changed",
- "organization_id": 123,
- "method": "GET",
- "created_at": "2024-01-01T00:00:00Z"
}Deletes a webhook. Only accessible by Super Admins.
Once deleted, the webhook will no longer receive event notifications.
| webhook_id required | integer (Webhook Id) |
{- "detail": "User does not have admin access to delete webhooks"
}Retrieves a list of SSO provider configurations. Only accessible by Super Admins.
Optionally filter by organization_id.
Organization Id (integer) or Organization Id (null) (Organization Id) |
[- {
- "id": 1,
- "organization_id": 123,
- "provider_type": "entra_id",
- "client_id": "your-client-id",
- "tenant_id": "your-tenant-id",
- "name": "Partner Entra ID",
- "archived": false,
- "created_at": "2024-01-01T00:00:00Z"
}
]Creates a new SSO provider configuration for an organization. Only accessible by Super Admins.
SSO providers store OAuth configuration for an organization's authentication flow.
The client_secret is encrypted at rest and is never returned by this API.
Required fields:
Optional fields:
Important constraints:
| organization_id required | integer (Organization Id) ID of the organization this SSO provider belongs to |
| provider_type required | string (Provider Type) SSO provider type (e.g., 'okta', 'google', 'entra_id') |
| client_id required | string (Client Id) OAuth client ID |
| client_secret required | string (Client Secret) OAuth client secret (will be encrypted at rest) |
| redirect_uri required | string (Redirect Uri) OAuth redirect URI |
Domain (string) or Domain (null) (Domain) Provider-specific domain (Okta) | |
Tenant Id (string) or Tenant Id (null) (Tenant Id) Provider-specific tenant ID (Entra ID) | |
Name (string) or Name (null) (Name) Friendly name |
{- "organization_id": 0,
- "provider_type": "string",
- "client_id": "string",
- "client_secret": "string",
- "redirect_uri": "string",
- "domain": "string",
- "tenant_id": "string",
- "name": "string"
}{- "id": 1,
- "organization_id": 123,
- "provider_type": "entra_id",
- "client_id": "your-client-id",
- "tenant_id": "your-tenant-id",
- "name": "Partner Entra ID",
- "archived": false,
- "created_at": "2024-01-01T00:00:00Z"
}Retrieves detailed information about a specific SSO provider configuration. Only accessible by Super Admins.
| sso_provider_id required | integer (Sso Provider Id) |
{- "id": 1,
- "organization_id": 123,
- "provider_type": "entra_id",
- "client_id": "your-client-id",
- "tenant_id": "your-tenant-id",
- "name": "Partner Entra ID",
- "archived": false,
- "created_at": "2024-01-01T00:00:00Z"
}Updates an existing SSO provider configuration. Only accessible by Super Admins.
All fields are optional to support partial updates.
Updatable fields:
Important constraints:
| sso_provider_id required | integer (Sso Provider Id) |
Organization Id (integer) or Organization Id (null) (Organization Id) ID of the organization this SSO provider belongs to | |
Provider Type (string) or Provider Type (null) (Provider Type) SSO provider type (e.g., 'okta', 'google', 'entra_id') | |
Client Id (string) or Client Id (null) (Client Id) OAuth client ID | |
Client Secret (string) or Client Secret (null) (Client Secret) OAuth client secret (will be encrypted at rest) | |
Redirect Uri (string) or Redirect Uri (null) (Redirect Uri) OAuth redirect URI | |
Domain (string) or Domain (null) (Domain) Provider-specific domain (Okta) | |
Tenant Id (string) or Tenant Id (null) (Tenant Id) Provider-specific tenant ID (Entra ID) | |
Name (string) or Name (null) (Name) Friendly name | |
Archived (boolean) or Archived (null) (Archived) Whether this provider is archived (inactive) |
{- "organization_id": 0,
- "provider_type": "string",
- "client_id": "string",
- "client_secret": "string",
- "redirect_uri": "string",
- "domain": "string",
- "tenant_id": "string",
- "name": "string",
- "archived": true
}{- "id": 1,
- "organization_id": 123,
- "provider_type": "entra_id",
- "client_id": "your-client-id-updated",
- "tenant_id": "your-tenant-id",
- "name": "Partner Entra ID",
- "archived": false,
- "created_at": "2024-01-01T00:00:00Z"
}Retrieves a list of partner auths. Only accessible by Super Admins.
Optionally filter by organization_id.
Organization Id (integer) or Organization Id (null) (Organization Id) |
[- {
- "id": 1,
- "organization_id": 123,
- "jwt_algorithm": "HS256",
- "enabled": true,
- "created_at": "2024-01-01T00:00:00Z"
}
]Creates a new partner auth for an organization. Only accessible by Super Admins.
Each organization can have at most one partner auth. The JWT secret is encrypted before storage.
| organization_id required | integer (Organization Id) ID of the organization this belongs to |
| jwt_secret required | string (Jwt Secret) JWT secret for verifying partner tokens |
| jwt_algorithm | string (Jwt Algorithm) Default: "HS256" JWT algorithm used for token verification |
{- "organization_id": 0,
- "jwt_secret": "string",
- "jwt_algorithm": "HS256"
}{- "id": 1,
- "organization_id": 123,
- "jwt_algorithm": "HS256",
- "enabled": true,
- "created_at": "2024-01-01T00:00:00Z"
}Retrieves details of a specific partner auth. Only accessible by Super Admins.
| partner_auth_id required | integer (Partner Auth Id) |
{- "id": 1,
- "organization_id": 123,
- "jwt_algorithm": "HS256",
- "enabled": true,
- "created_at": "2024-01-01T00:00:00Z"
}Updates an existing partner auth. Only accessible by Super Admins.
All fields are optional to support partial updates. If jwt_secret is provided, it will be re-encrypted before storage.
| partner_auth_id required | integer (Partner Auth Id) |
Jwt Secret (string) or Jwt Secret (null) (Jwt Secret) JWT secret for verifying partner tokens | |
Jwt Algorithm (string) or Jwt Algorithm (null) (Jwt Algorithm) JWT algorithm used for token verification | |
Enabled (boolean) or Enabled (null) (Enabled) Whether this is enabled |
{- "jwt_secret": "string",
- "jwt_algorithm": "string",
- "enabled": true
}{- "id": 1,
- "organization_id": 123,
- "jwt_algorithm": "HS256",
- "enabled": true,
- "created_at": "2024-01-01T00:00:00Z"
}Retrieves the HTML content for a specific policy document. Accessible by all users.
Available policies:
The content is returned as formatted HTML ready for display.
| policy_name required | string (Policy Name) |
{- "html": "<div><h1>Privacy Policy</h1><p>This privacy policy describes how we collect...</p></div>"
}Retrieves all service usage records for a specific COSI.
Only accessible by Super Admins.
Returns usage records ordered by ID descending (most recent first), including token counts, rates, and estimated costs per agent operation.
| slug required | string (Slug) |
[- {
- "id": 123,
- "cosi_id": 456,
- "service": "openai",
- "model": "gpt-4.1",
- "operation": "situations_analyst",
- "direction": "input",
- "unit_type": "tokens",
- "units": 5000,
- "rate": "2.000000",
- "rate_per": 1000000,
- "estimated_cost": "0.010000",
- "created_at": "2024-01-01T00:00:00Z"
}
]Records service usage reported by the client (e.g. Deepgram STT seconds captured during the assessment chat).
Public endpoint — partner token required when the organization has partner auth enabled.
| slug required | string (Slug) |
Token (string) or Token (null) (Token) |
| service required | string (Service) The service name (currently only 'deepgram' is supported) Value: "deepgram" |
| model required | string (Model) The model used (must be valid for the service) |
| units required | number (Units) > 0 Usage amount (must be positive) |
{- "service": "deepgram",
- "model": "string",
- "units": 0
}{- "message": "Usage recorded",
- "units": 46
}Calculates the total cost for a COSI by looking up pricing for all service usage records and updating estimated costs.
Only accessible by Super Admins.
Updates each ServiceUsage record with the current rate and estimated cost, and sets the COSI's estimated_cost and cost_calculated_at fields.
| slug required | string (Slug) |
{- "message": "Cost calculated",
- "estimated_cost": "0.042000"
}Mints a short-lived, scoped Deepgram API key (90-minute TTL, usage:write)
for use in the cosi assessment chat's client-side WebSocket STT.
Public endpoint — partner token required when the organization has partner auth enabled.
| slug required | string (Slug) |
Token (string) or Token (null) (Token) |
{- "api_key": "abcdef0123456789..."
}HTTP fallback for the cosi assessment chat's STT — used by clients on networks that block WebSockets to Deepgram. Accepts an uploaded audio file, calls Deepgram's REST API server-side, records usage, and returns the transcript.
Public endpoint — partner token required when the organization has partner auth enabled.
| slug required | string (Slug) |
Token (string) or Token (null) (Token) |
| audio_file required | string <binary> (Audio File) |
{- "transcript": "Hello, how are you?"
}