Real-time event notifications delivered as HTTP POST callbacks to a URL you configure, firing when relevant Coviu events occur (for example a patient arriving in the waiting room or a call concluding). Supports OAuth/custom-header authentication of your endpoint.
{
"openapi": "3.0.0",
"info": {
"title": "Coviu REST API",
"version": "1.0"
},
"servers": [
{
"url": "https://api.coviu.com"
}
],
"paths": {
"/v1/auth/token": {
"post": {
"tags": [
"Auth"
],
"summary": "Request access token",
"description": "Request an access token using one of the supported OAuth2 grant types:\n## Client Credentials \n\n - HTTP Basic Auth, passing the Client ID and Client Secret as the username and password\n\n - `application/x-www-form-urlencoded` data, containing:\n\n - `{ grant_type: \"client_credentials\" }`\n\n\n## Authorization Code\n\n - HTTP Basic Auth, passing the Client ID and Client Secret as the username and password\n\n - `application/x-www-form-urlencoded` data, containing:\n\n - ```\n { \n grant_type: \"authorization_code\", \n code: \"eyJ0eXAi....\" \n }\n ```\n\n\n## Refresh Token\n\n - HTTP Basic Auth, passing the Client ID and Client Secret as the username and password\n\n - `application/x-www-form-urlencoded` data, containing:\n\n - ```\n { \n grant_type: \"refresh_token\", \n refresh_token: \"eyJ0eXAi....\" \n }\n ```\n",
"operationId": "access-token",
"security": [
{
"Basic": []
}
],
"requestBody": {
"content": {
"application/x-www-form-url-encoded": {
"schema": {
"oneOf": [
{
"type": "object",
"required": [
"grant_type"
],
"properties": {
"grant_type": {
"type": "string",
"enum": [
"client_credentials"
]
}
}
},
{
"type": "object",
"required": [
"grant_type",
"code"
],
"properties": {
"grant_type": {
"type": "string",
"enum": [
"authorization_code"
]
},
"code": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"grant_type",
"refresh_token"
],
"properties": {
"grant_type": {
"type": "string",
"enum": [
"refresh_token"
]
},
"refresh_token": {
"type": "string"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Token"
}
}
}
},
"400": {
"description": "400"
}
}
}
},
"/v1/sessions": {
"post": {
"tags": [
"Sessions"
],
"summary": "Create a Session",
"operationId": "createSession",
"description": "There are some further options you are able to pass through a \"feature_flags\" field when creating a session. These allow some customisation of the interface\n\n## Custom features for Sessions\n\nCustom feature can be added while creating a Session and it can be done by passing values into the feature_flags array.\n\n**Example Feature Flags option** \n\n```text\nfeature_flags: [\n\n '-plugin;coviu-waiting-room-plugin',\n\n '-plugin;coviu-stripe-payments-resource-plugin',\n\n 'customisation;disable-menu',\n\n 'customisation;exit-url;https://your-exit-url',\n\n 'customisation;return-url;https://your-return-url',\n\n 'customisation;return-label;Your return label',\n\n 'customisation;auto-return',\n\n 'session;enforce-participant-uniqueness',\n\n 'customisation;favicon-url;https://yourdomain.com/favicon.ico'\n]\n```\n\n**What do they do?** \n\n| Feature Flag | What it does ? |\n| :------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| \\-plugin | Removes standard Coviu plugins from the session room |\n| customisation;disable-menu | Removes the menu from the session room |\n| customisation;exit-url | Add a specific URL to wherever you would like to redirect to if the user exits the call interface using the \"Exit call interface\" button prior to other participants joining |\n| customisation;return-url | Add a specific URL to wherever you would like to redirect to after the call has completed from the exit screen |\n| customisation;return-label | To label the button that does the return URL navigation. |\n| customisation;auto-return | Automatically redirect to the return-url after hitting the \"end call\" button |\n| session;enforce-participant-uniqueness | Allow for the unique use of the participant's URL - it can't be re-used after first entry |\n| customisation;favicon-url;<https://yourdomain.com/favicon.ico> | Allow for the use of your favicon in the call |\n| customisation;background-color;{value} | Allows for using a custom background colour in the Coviu call window |\n| customisation;button-primary;{value} | Allows for using a custom button colour in the Coviu call window |\n| customisation;button-secondary;{value} | Allows for using a custom colour for the content inside the button in the Coviu call window |\n",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSession"
}
}
}
},
"responses": {
"200": {
"description": "Session created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Session"
}
}
}
},
"400": {
"description": "400"
}
}
},
"get": {
"tags": [
"Sessions"
],
"summary": "List Sessions",
"operationId": "listSessions",
"parameters": [
{
"name": "page",
"in": "query",
"description": "Zero based index",
"schema": {
"type": "integer"
}
},
{
"name": "page_size",
"in": "query",
"description": "Number of entries to return",
"schema": {
"type": "integer"
}
},
{
"name": "start_time",
"in": "query",
"description": "Include sessions whose start time falls after the given start time",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "end_time",
"in": "query",
"description": "Include sessions whose end time falls before the given end time",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "order",
"in": "query",
"description": "Orders the returned sessions",
"schema": {
"type": "string",
"enum": [
"forward",
"reverse"
]
}
},
{
"name": "include_canceled",
"in": "query",
"description": "Include sessions that have been cancelled.",
"schema": {
"type": "string"
}
},
{
"name": "deleted_participants",
"in": "query",
"description": "Include participants that have been removed from the session.",
"schema": {
"type": "string"
}
},
{
"name": "state",
"in": "query",
"description": "Limit the response to sessions with participants with specific state value.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "List of sessions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
},
"page": {
"type": "integer"
},
"page_size": {
"type": "integer"
},
"more": {
"type": "boolean"
}
}
}
}
}
}
}
}
},
"/v1/sessions/{session_id}": {
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"get": {
"tags": [
"Sessions"
],
"summary": "Get a Session",
"operationId": "getSession",
"responses": {
"200": {
"description": "Session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Session"
}
}
}
}
}
},
"put": {
"tags": [
"Sessions"
],
"summary": "Update a Session",
"operationId": "updateSession",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSession"
}
}
}
},
"responses": {
"200": {
"description": "Session updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Session"
}
}
}
},
"400": {
"description": "400"
}
}
},
"delete": {
"tags": [
"Sessions"
],
"summary": "Cancel a Session",
"operationId": "cancelSession",
"responses": {
"200": {
"description": "Cancelled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
}
}
}
}
}
}
}
},
"/v1/sessions/{session_id}/summary": {
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"get": {
"tags": [
"Sessions"
],
"summary": "Get Session Summary",
"operationId": "getSessionSummary",
"description": "Here is some further information on the timestamps provided in the response:\n\n- Start time - Scheduled start time for the session\n- End time - Scheduled end time for the session\n- Actual start time - Creation time of the call, typically when host has joined\n- Actual end time - Call recorded as complete, last participant has left\n- Participant entry time - Earliest recorded entry time for the participant, does not include time in Waiting Room\n- Participant exit time - Latest recorded exit time for the participant.\n",
"responses": {
"200": {
"description": "Session Summary",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionSummary"
}
}
}
}
}
}
},
"/v1/sessions/{session_id}/participants": {
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "deleted_participants",
"in": "query",
"description": "Include participants that have been removed from the session.",
"schema": {
"type": "string"
}
}
],
"get": {
"tags": [
"Participants"
],
"summary": "List Participants",
"operationId": "listParticipants",
"description": "By default, the returned order is paginated with the first page containing the created sessions in chronological order (oldest created first). If you set the \"order\" parameter to \"reverse\", the newest created sessions will be returned.\n\nYou can filter sessions by start and end time, at which stage the returned result list is ordered by start time in chronological order (rather than by creation time). The \"order\" parameter allows you to reverse this order to retrieve sessions by start time with the newest start time first.\n",
"responses": {
"200": {
"description": "List of participants",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Participant"
}
}
}
}
}
}
},
"post": {
"tags": [
"Participants"
],
"summary": "Add Participant",
"operationId": "addParticipant",
"description": "It is sometimes useful to add a participant to a session after the session has been created. It is possible to add a participant to a session that has already started, but not to a session that has already finished.\n",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateParticipant"
}
}
}
},
"responses": {
"200": {
"description": "Participant added",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Participant"
}
}
}
},
"400": {
"description": "400"
}
}
}
},
"/v1/participants/{participant_id}": {
"parameters": [
{
"name": "participant_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"get": {
"tags": [
"Participants"
],
"summary": "Get Participant",
"operationId": "getParticipant",
"responses": {
"200": {
"description": "Participant details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Participant"
}
}
}
}
}
},
"put": {
"tags": [
"Participants"
],
"summary": "Update Participant",
"operationId": "updateParticipant",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateParticipant"
}
}
}
},
"responses": {
"200": {
"description": "Participant updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Participant"
}
}
}
},
"400": {
"description": "400"
}
}
},
"delete": {
"tags": [
"Participants"
],
"summary": "Cancel a Participant",
"operationId": "cancelParticipant",
"description": "A session that is scheduled for the future may be canceled. No participants will be able to join the session after it has been canceled, and it can not be uncanceled once it has been canceled. A session that has already started may not be canceled.\n",
"responses": {
"200": {
"description": "Participant cancelled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
}
}
}
}
}
}
}
},
"/v1/waiting/{teamId}": {
"get": {
"tags": [
"Waiting Area"
],
"summary": "Get Currently Waiting Calls",
"operationId": "getCurrentlyWaitingCalls",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "List of waiting calls",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Call"
}
}
}
}
}
}
}
},
"/v1/waiting/{teamId}/queue/{waitingQueueId}": {
"get": {
"tags": [
"Waiting Area"
],
"summary": "Get Currently Waiting Calls for a Queue",
"operationId": "getCurrentlyWaitingCallsForQueue",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "waitingQueueId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "List of waiting calls",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Call"
}
}
}
}
}
}
}
},
"/v1/waiting/{teamId}/calls/{callId}": {
"get": {
"tags": [
"Waiting Area"
],
"summary": "Get a Call",
"operationId": "getCall",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "callId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Call",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Call"
}
}
}
}
}
}
},
"/v1/collections/{teamId}": {
"get": {
"tags": [
"Collections"
],
"summary": "Retrieve the Collections for a Team",
"operationId": "getCollections",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Collection",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Collection"
}
}
}
}
}
}
}
},
"/v1/collections/{teamId}/collection/{collectionId}": {
"get": {
"tags": [
"Collections"
],
"summary": "List the Submissions for a Collection",
"operationId": "listSubmissions",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "collectionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "from",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "ISO 8601 format: 1970-01-01T01:00:00Z"
},
{
"name": "until",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "ISO 8601 format: 1970-01-01T01:00:00Z"
},
{
"name": "filter",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "orderBy",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "created_at"
}
}
],
"responses": {
"200": {
"description": "Collection",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Submission"
}
},
"total": {
"type": "number"
}
}
}
}
}
}
}
}
},
"/v1/collections/{teamId}/collection/{collectionId}/submission/{submissionId}": {
"get": {
"tags": [
"Collections"
],
"summary": "Get a Submission",
"operationId": "getSubmission",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "collectionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "submissionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Submission",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmissionDetail"
}
}
}
}
}
}
},
"/v1/collections/{teamId}/collection/{collectionId}/submission/{submissionId}/file/{fileId}": {
"get": {
"tags": [
"Collections"
],
"summary": "Get the binary file for a SubmissionFile",
"operationId": "getSubmissionFile",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "collectionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "submissionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "fileId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "quality",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"480p"
]
}
}
],
"responses": {
"200": {
"description": "Video Recording",
"content": {
"video/webm": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"206": {
"description": "Video Recording",
"content": {
"video/webm": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/v1/collections/{teamId}/collection/{collectionId}/recording/{submissionId}": {
"get": {
"tags": [
"Collections"
],
"summary": "Get the binary file for an Audio Recording",
"operationId": "getAudioRecording",
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "collectionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "submissionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Audio Recording",
"content": {
"audio/webm": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"206": {
"description": "Audio Recording",
"content": {
"audio/webm": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/webhook": {
"post": {
"tags": [
"Webhook Requests"
],
"description": "The events and payloads documented in this section are webhooks \u2014 they are not endpoints your system should call, but rather requests that will be sent from our servers to your system when relevant events occur. These webhook payloads are delivered as HTTP POST requests to a URL you configure during integration.\n\n\nThis page documents all events the webhooks can be configured to fire, and the structure of the payloads your system should expect to receive. Your system must expose an endpoint to receive these POST requests, and handle the incoming JSON payload according to the schema.\n\n\nNote: You should respond with a 2xx HTTP status code to acknowledge receipt. The system will not retry requests upon failure.\n",
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/WaitingAreaJoin"
},
{
"$ref": "#/components/schemas/WaitingAreaAnswer"
},
{
"$ref": "#/components/schemas/WaitingAreaLeave"
},
{
"$ref": "#/components/schemas/Waitin
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coviu/refs/heads/main/openapi/coviu-rest-api-openapi.json