{ "openapi": "3.0.1", "info": { "title": "Attention Service V2", "description": "Attention Service API V2", "termsOfService": "https://www.attention.com/terms-of-use", "contact": { "name": "Attention Team", "url": "https://docs.attention.com/welcome", "email": "support@attention.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.8.0" }, "servers": [ { "url": "https://api.attention.tech/v2" } ], "security": [ { "APIKeyHeader": [] } ], "paths": { "/gi/history": { "get": { "tags": [ "General Insights" ], "summary": "List GI History", "description": "Retrieves the history of generalized insights for a specific user. This endpoint allows you to track and analyze the evolution of insights over time, with options to control the response format and pagination.", "operationId": "listGIHistory", "parameters": [ { "name": "user_uuid", "in": "query", "description": "Unique identifier of the user whose insight history is being requested", "required": true, "schema": { "type": "string" } }, { "name": "withoutEnhancingResults", "in": "query", "description": "When set to true, returns raw insight data without additional processing or enhancement", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Maximum number of history entries to return", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of entries to skip before starting to collect the result set", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved the insight history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GIHistoryResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/GIHistoryResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while processing the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/list": { "get": { "tags": [ "Conversation" ], "summary": "List Conversations (Optimized)", "description": "Optimized alias for GET /conversations. Uses a batch query path that pre-fetches edges in a single pass, making it significantly faster for large result sets. Behavioural differences from /conversations: (1) extractedIntelligence and confirmedExtractedIntelligence are omitted by default — pass with_crm_records=true to include them; (2) empty conversations are not excluded; All filter parameters are identical to /conversations.", "operationId": "listConversationsV2", "parameters": [ { "name": "fromDateTime", "in": "query", "description": "Start date and time for filtering conversations (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "toDateTime", "in": "query", "description": "End date and time for filtering conversations (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (starts from 1)", "schema": { "type": "integer" } }, { "name": "size", "in": "query", "description": "Number of items per page (max 50)", "schema": { "type": "integer" } }, { "name": "filter[owner.id]", "in": "query", "description": "Filter conversations by owner IDs", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[owner.email]", "in": "query", "description": "Filter conversations by owner email addresses", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[title]", "in": "query", "description": "Filter conversations by title using case-insensitive partial matching", "schema": { "type": "string" } }, { "name": "filter[participants.email]", "in": "query", "description": "Filter conversations by participant email addresses", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[external_opportunity.id]", "in": "query", "description": "Filter conversations by external opportunity IDs", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[crm_field.entity_code]", "in": "query", "description": "CRM platform entity code to filter linked CRM records", "schema": { "type": "string", "enum": [ "companies", "contacts", "deals", "owners", "pipelines", "users", "account", "contact", "lead", "opportunity", "user" ] } }, { "name": "filter[crm_field.field_name]", "in": "query", "description": "CRM record field name (from org_crm_records.record_data) to match on linked CRM records", "schema": { "type": "string" } }, { "name": "filter[crm_field.values]", "in": "query", "description": "Exact values to match for the given CRM field. Values are OR-ed together. Maximum 10 entries.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[team.id]", "in": "query", "description": "Filter conversations by team IDs", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[hide_internal]", "in": "query", "description": "Exclude internal conversations from results", "schema": { "type": "boolean" } }, { "name": "filter[hide_non_analyzed]", "in": "query", "description": "Exclude conversations that have not been analyzed", "schema": { "type": "boolean" } }, { "name": "filter[analyzed]", "in": "query", "description": "Filter conversations by analysis status (deprecated, use filter[hide_non_analyzed] instead)", "schema": { "type": "boolean" } }, { "name": "filter[hide_pending]", "in": "query", "description": "Exclude conversations that are pending processing", "schema": { "type": "boolean" } }, { "name": "filter[hide_transcript]", "in": "query", "description": "Exclude conversations without transcripts", "schema": { "type": "boolean" } }, { "name": "filter[hide_failed]", "in": "query", "description": "Exclude conversations that failed processing", "schema": { "type": "boolean" } }, { "name": "filter[include_internal_participants]", "in": "query", "description": "Include internal participants in the response", "schema": { "type": "boolean" } }, { "name": "filter[include_zoom_metadata]", "in": "query", "description": "Include Zoom-specific metadata in the response", "schema": { "type": "boolean" } }, { "name": "filter[include_import_metadata]", "in": "query", "description": "Include import metadata in the response", "schema": { "type": "boolean" } }, { "name": "detailedTranscript", "in": "query", "description": "Include detailed transcript information in the response", "schema": { "type": "boolean", "default": false } }, { "name": "withCrmRecords", "in": "query", "description": "Include CRM records in the response. Also re-enables extractedIntelligence and confirmedExtractedIntelligence fields that are otherwise stripped on this endpoint.", "schema": { "type": "boolean", "default": false } }, { "name": "withIntelligenceItems", "in": "query", "description": "Include intelligence items in the response", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConversationsResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations": { "get": { "tags": [ "Conversation" ], "summary": "List Conversations", "description": "Retrieves a paginated list of conversations with their transcriptions. Supports various filtering options to narrow down the results based on date ranges, participants, teams, and conversation status.", "operationId": "listConversations", "parameters": [ { "name": "fromDateTime", "in": "query", "description": "Start date and time for filtering conversations (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "toDateTime", "in": "query", "description": "End date and time for filtering conversations (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (starts from 1)", "schema": { "type": "integer" } }, { "name": "size", "in": "query", "description": "Number of items per page", "schema": { "type": "integer" } }, { "name": "filter[owner.id]", "in": "query", "description": "Filter conversations by owner IDs", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[owner.email]", "in": "query", "description": "Filter conversations by owner email addresses", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[title]", "in": "query", "description": "Filter conversations by title using case-insensitive partial matching", "schema": { "type": "string" } }, { "name": "filter[participants.email]", "in": "query", "description": "Filter conversations by participant email addresses", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[external_opportunity.id]", "in": "query", "description": "Filter conversations by external opportunity IDs", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[crm_field.entity_code]", "in": "query", "description": "CRM platform entity code to filter linked CRM records (e.g. companies, contacts, deals, owners, pipelines, users, account, contact, lead, opportunity, user)", "schema": { "type": "string", "enum": [ "companies", "contacts", "deals", "owners", "pipelines", "users", "account", "contact", "lead", "opportunity", "user" ] } }, { "name": "filter[crm_field.field_name]", "in": "query", "description": "CRM record field name (from org_crm_records.record_data) to match on linked CRM records", "schema": { "type": "string" } }, { "name": "filter[crm_field.values]", "in": "query", "description": "Exact values to match for the given CRM field. Values are OR'ed together.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[team.id]", "in": "query", "description": "Filter conversations by team IDs", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[hide_internal]", "in": "query", "description": "Exclude internal conversations from results", "schema": { "type": "boolean" } }, { "name": "filter[hide_non_analyzed]", "in": "query", "description": "Exclude conversations that haven't been analyzed", "schema": { "type": "boolean" } }, { "name": "filter[analyzed]", "in": "query", "description": "Filter conversations by analysis status (deprecated, use filter[hide_non_analyzed] instead)", "schema": { "type": "boolean" } }, { "name": "filter[hide_pending]", "in": "query", "description": "Exclude conversations that are pending processing", "schema": { "type": "boolean" } }, { "name": "filter[hide_transcript]", "in": "query", "description": "Exclude conversations without transcripts", "schema": { "type": "boolean" } }, { "name": "filter[hide_failed]", "in": "query", "description": "Exclude conversations that failed processing", "schema": { "type": "boolean" } }, { "name": "filter[include_internal_participants]", "in": "query", "description": "Include internal participants in the response", "schema": { "type": "boolean" } }, { "name": "filter[include_zoom_metadata]", "in": "query", "description": "Include Zoom-specific metadata in the response", "schema": { "type": "boolean" } }, { "name": "filter[include_import_metadata]", "in": "query", "schema": { "type": "boolean" } }, { "name": "detailedTranscript", "in": "query", "description": "Include detailed transcript information in the response", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConversationsResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true } }, "/conversations/{id}": { "get": { "tags": [ "Conversation" ], "summary": "Get Conversation", "description": "Retrieves detailed information about a specific conversation, including its transcription, participants, and metadata. The response can be customized to include or exclude certain details based on the query parameters.", "operationId": "conversationById", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the conversation", "required": true, "schema": { "type": "string" } }, { "name": "by", "in": "query", "description": "Specify how to lookup the conversation: 'id' for internal conversation ID (default), 'external_id' for external application ID from imports", "schema": { "type": "string", "default": "id", "enum": [ "id", "external_id" ] } }, { "name": "filter[include_internal_participants]", "in": "query", "description": "Include internal participants in the response", "schema": { "type": "boolean" } }, { "name": "filter[include_zoom_metadata]", "in": "query", "description": "Include Zoom-specific metadata in the response", "schema": { "type": "boolean" } }, { "name": "filter[include_import_metadata]", "in": "query", "description": "Include import metadata in the response", "schema": { "type": "boolean" } }, { "name": "detailedTranscript", "in": "query", "description": "Include detailed transcript information in the response", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved conversation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Conversation" ], "summary": "Update Conversation", "description": "Updates the metadata and properties of an existing conversation. This endpoint allows modification of conversation details such as title and labels.", "operationId": "updateConversation", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the conversation to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Conversation fields to update", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title for the conversation" }, "labels": { "type": "object", "additionalProperties": true, "description": "Labels/metadata for the conversation as key-value pairs" } } } }, "application/vnd.api+json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title for the conversation" }, "labels": { "type": "object", "additionalProperties": true, "description": "Labels/metadata for the conversation as key-value pairs" } } } } }, "required": false }, "responses": { "200": { "description": "Successfully updated conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" }, "delete": { "tags": [ "Conversation" ], "summary": "Archive Conversation", "description": "Archive a conversation, marking it as no longer active.", "operationId": "archiveConversation", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the conversation to archive", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully archived conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{id}/change_privacy": { "put": { "tags": [ "Conversation" ], "summary": "Change Conversation Privacy", "description": "Change the privacy of a conversation from private to public and vice versa", "operationId": "changeConversationPrivacy", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the conversation to update", "required": true, "schema": { "type": "string" } }, { "name": "privacy", "in": "query", "description": "Privacy of the conversation: public or private", "required": true, "schema": { "type": "string", "enum": [ "public", "private" ] } } ], "responses": { "200": { "description": "Successfully updated conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{id}/media/download": { "post": { "tags": [ "Conversation" ], "summary": "Generate Conversation Media Download URL", "description": "Generate a presigned URL for downloading the media file of a conversation. Organization-level authentication only.", "operationId": "generateConversationMediaDownload", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the conversation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully generated download URL", "content": { "application/json": { "schema": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "Presigned URL for downloading the conversation media" } } } }, "application/vnd.api+json": { "schema": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "Presigned URL for downloading the conversation media" } } } } } }, "401": { "description": "Authentication failed - valid organization API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - conversation is private or archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found or does not belong to organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/upload-url": { "get": { "tags": [ "Conversation" ], "summary": "Get Signed Upload Conversation URL", "description": "Generate a signed URL for uploading a conversation file", "operationId": "beginConversationUpload", "responses": { "200": { "description": "signed upload url successfully generated", "content": { "application/json": { "schema": { "required": [ "downloadUrl", "key", "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "Signed URL for uploading the file" }, "key": { "type": "string", "description": "Unique key identifier for the upload" }, "downloadUrl": { "type": "string", "description": "URL to download the file after upload" } } } }, "application/vnd.api+json": { "schema": { "required": [ "downloadUrl", "key", "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "Signed URL for uploading the file" }, "key": { "type": "string", "description": "Unique key identifier for the upload" }, "downloadUrl": { "type": "string", "description": "URL to download the file after upload" } } } } } }, "401": { "description": "valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/import": { "post": { "tags": [ "Conversation" ], "summary": "Import Conversation", "description": "Import a conversation from a media file. This endpoint creates a new conversation from an external source (e.g., Gong, Salesforce) and processes it through the Attention platform's transcription and analysis pipeline.", "operationId": "importConversation", "requestBody": { "description": "Conversation import data including media URL, user information, and optional metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportConversationRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ImportConversationRequest" } } }, "required": true }, "responses": { "200": { "description": "Conversation successfully imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportConversationResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ImportConversationResponse" } } } }, "400": { "description": "Invalid request parameters or user does not belong to organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "User does not belong to the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/conversations/workflow-logs": { "get": { "tags": [ "Conversation" ], "summary": "List Conversation Workflow Logs", "description": "Retrieves a paginated list of conversation workflow execution logs. Supports filtering by date range, conversation UUIDs, and success status.", "operationId": "listConversationWorkflowLogs", "parameters": [ { "name": "fromDateTime", "in": "query", "description": "Start date and time for filtering logs (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "toDateTime", "in": "query", "description": "End date and time for filtering logs (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "conversationUUIDs", "in": "query", "description": "Filter logs by specific conversation UUIDs", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "success", "in": "query", "description": "Filter logs by success status (true for successful, false for failed)", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Maximum number of logs to return (default: 100, max: 1000)", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of logs to skip for pagination", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved workflow logs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationWorkflowLogsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConversationWorkflowLogsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while processing the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams": { "get": { "tags": [ "Team" ], "summary": "List Teams", "description": "Retrieves a list of all teams in the system. The response includes team details such as name, UUID, parent team information, and team hierarchy.", "operationId": "listTeams", "responses": { "200": { "description": "Teams successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving teams", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}": { "get": { "tags": [ "Team" ], "summary": "Get Team", "description": "Retrieves detailed information about a specific team by its ID. The response includes team details, members, and hierarchical information.", "operationId": "getTeam", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the team (UUID format)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "401": { "description": "Authentication required. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Team not found with the provided ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving the team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/members": { "get": { "tags": [ "Team" ], "summary": "Get Team Members", "description": "Retrieves all members of a specific team. The response includes user details and their roles within the team.", "operationId": "getTeamMembers", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the team (UUID format)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team members successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/TeamMemberResponse" } } } }, "401": { "description": "Authentication required. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Team not found with the provided ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving team members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api_keys": { "get": { "tags": [ "API Key" ], "summary": "List API Keys", "description": "Lists all API keys for the current user", "operationId": "listApiKeys", "responses": { "200": { "description": "Successfully retrieved API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } } }, "application/vnd.api+json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "API Key" ], "summary": "Create API Key", "description": "Creates a new API key. This endpoint allows you to generate an API key that can be used to authenticate requests to the Attention service.", "operationId": "createApiKey", "requestBody": { "description": "Details of the application for which to generate the API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAPIKeyRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateAPIKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully created API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKey" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/APIKey" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" }, "delete": { "tags": [ "API Key" ], "summary": "Delete API Key", "description": "Deletes an API key. This endpoint allows you to delete an API key that is no longer needed.", "operationId": "deleteApiKey", "parameters": [ { "name": "uuid", "in": "query", "description": "Id of the API key to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfully deleted API key", "content": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users": { "get": { "tags": [ "User" ], "summary": "List Users", "description": "Returns a list of users, you can also filter by id, email and teamUUID", "operationId": "listUsers", "parameters": [ { "name": "filter[id]", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[email]", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "teamUUID", "in": "query", "schema": { "type": "string" } }, { "name": "includeDeleted", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "users successfully returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } } }, "401": { "description": "valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email-templates": { "get": { "tags": [ "Email" ], "summary": "List email templates", "description": "List email templates grouped by scope", "operationId": "listEmailTemplates", "parameters": [ { "name": "filter[user_id]", "in": "query", "schema": { "type": "string" } }, { "name": "filter[user_email]", "in": "query", "schema": { "type": "string" } }, { "name": "filter[owner_id]", "in": "query", "schema": { "type": "string" } }, { "name": "filter[owner_email]", "in": "query", "schema": { "type": "string" } }, { "name": "filter[team_id]", "in": "query", "schema": { "type": "string" } }, { "name": "filter[organization_id]", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "email templates successfully returned", "content": { "application/json": { "schema": { "type": "object" } }, "application/vnd.api+json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails": { "get": { "tags": [ "Email" ], "summary": "List emails", "description": "Returns a list of emails", "operationId": "listEmails", "parameters": [ { "name": "subject", "in": "query", "description": "Filter emails by subject using case-insensitive partial matching", "schema": { "type": "string" } }, { "name": "crm_account_id", "in": "query", "description": "Filter emails by CRM account id", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "deal_uuid", "in": "query", "description": "Filter emails by deal uuid", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "from_date_time", "in": "query", "description": "Start date and time for filtering emails (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date_time", "in": "query", "description": "End date and time for filtering emails (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "Page number for pagination (starts from 1)", "schema": { "minimum": 1, "type": "integer", "default": 1 } }, { "name": "size", "in": "query", "description": "Number of items per page (min 1, max 50)", "schema": { "maximum": 50, "minimum": 1, "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "emails successfully returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEmailsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListEmailsResponse" } } } }, "401": { "description": "valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/snippets": { "post": { "tags": [ "Tool", "Snippet" ], "summary": "Create Snippet", "description": "Creates a new conversation snippet that can be used for reference, analysis, or sharing. This endpoint allows you to capture and store important parts of conversations for future use.", "operationId": "createSnippet", "requestBody": { "description": "Snippet creation request containing the conversation content and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnippetRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateSnippetRequest" } } }, "required": true }, "responses": { "200": { "description": "Snippet successfully created and stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedSnippetResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreatedSnippetResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while creating the snippet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/createScorecardResult": { "post": { "tags": [ "Scorecard" ], "summary": "Create Scorecard Result", "description": "Create Scorecard Result for a conversation", "operationId": "createScorecardResult", "requestBody": { "description": "Scorecard result creation request containing the conversation UUID, scorecard UUID, and scorecard result details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createScorecardResultRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/createScorecardResultRequest" } } }, "required": true }, "responses": { "200": { "description": "Scorecard result successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createScorecardResultResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/createScorecardResultResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while creating the scorecard result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/changeConversationOpportunity": { "post": { "tags": [ "Conversation" ], "summary": "Change Conversation Opportunity", "description": "Links, updates, or removes an opportunity associated with a conversation. When an opportunity is linked, CRM intelligence fields may be recalculated unless explicitly skipped.", "operationId": "changeConversationOpportunity", "requestBody": { "description": "Request body with the conversation ID and opportunity details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/changeConversationOpportunityRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/changeConversationOpportunityRequest" } } }, "required": true }, "responses": { "200": { "description": "Opportunity changed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/changeConversationOpportunityResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/changeConversationOpportunityResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/organizations/users": { "get": { "tags": [ "Organization" ], "summary": "List Organization Users", "description": "Returns a list of users in the organization. You can optionally filter the results by teamUUID to get users from a specific team. The response includes user details such as name, email, and role information.", "operationId": "listOrganizationUsers", "parameters": [ { "name": "teamUUID", "in": "query", "description": "Optional UUID of the team to filter users by. If not provided, returns all users in the organization.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users successfully returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Organization" ], "summary": "Create User", "description": "Creates a new user in the specified organization. Requires a valid API key and proper permissions to create users. The user will be assigned to the specified team and given the specified role. Returns the created user's details including their UUID.", "operationId": "createUser", "requestBody": { "description": "The details of the user to be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } }, "required": true }, "responses": { "200": { "description": "User successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateUserResponse" } } } }, "400": { "description": "Team does not exist or is not part of the organization", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } }, "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "422": { "description": "Missing required fields in body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_422_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_422_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/organizations/users/{userId}": { "delete": { "tags": [ "Organization" ], "summary": "Delete User", "description": "Deletes an existing user from the organization. This operation is permanent and cannot be undone. The user will be removed from all teams and their access will be revoked. Requires proper permissions to delete users.", "operationId": "deleteUser", "parameters": [ { "name": "userId", "in": "path", "description": "UUID of the user to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User successfully deleted", "content": {} }, "400": { "description": "User not a member of the organization or cannot be deleted", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } }, "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Organization" ], "summary": "Update User", "description": "Updates an existing user's information in the organization. You can modify the user's name, email, team assignment, and role. Requires proper permissions to update user details.", "operationId": "updateUser", "parameters": [ { "name": "userId", "in": "path", "description": "UUID of the user to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The updated user information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } }, "required": true }, "responses": { "200": { "description": "User successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateUserResponse" } } } }, "400": { "description": "Failed to fetch user or invalid update parameters", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } }, "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "422": { "description": "Missing or invalid body parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_422_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_422_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/organizations/teams": { "get": { "tags": [ "Organization" ], "summary": "List Teams", "description": "Returns a list of all teams in the organization. The response includes team details such as name, UUID, and parent team information if applicable.", "operationId": "listOrganizationTeams", "responses": { "200": { "description": "Teams successfully returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/TeamResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } } } }, "post": { "tags": [ "Organization" ], "summary": "Create Team", "description": "Creates a new team in the organization. You can optionally specify a parent team to create a hierarchical team structure. The team will be created with default permissions and settings.", "operationId": "createTeam", "requestBody": { "description": "The details of the team to be created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } }, "required": true }, "responses": { "200": { "description": "Team successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateTeamResponse" } } } }, "400": { "description": "Parent Team does not exist or is not part of the organization", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } }, "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "409": { "description": "A team with the same name already exists in the organization", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } }, "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/organizations/teams/{teamId}": { "patch": { "tags": [ "Organization" ], "summary": "Update Team", "description": "Updates an existing team's information. You can modify the team's name and parent team assignment. This operation can be used to restructure the team hierarchy within the organization.", "operationId": "updateTeam", "parameters": [ { "name": "teamId", "in": "path", "description": "UUID of the team to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The updated team information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRequest" } } }, "required": true }, "responses": { "200": { "description": "Team successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateTeamResponse" } } } }, "400": { "description": "Failed to fetch team or invalid update parameters", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } }, "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "409": { "description": "A team with the same name already exists in the organization", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } }, "application/vnd.api+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ] } } } }, "422": { "description": "Missing or invalid body parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_422_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_422_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/organizations/roles": { "get": { "tags": [ "Organization" ], "summary": "List Roles", "description": "Returns a list of roles", "operationId": "listOrganizationRoles", "responses": { "200": { "description": "Roles successfully returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationRolesResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListOrganizationRolesResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask_attention": { "post": { "tags": [ "Tool", "AskAttention" ], "summary": "Ask Attention", "description": "Analyzes conversations or prompts to provide insights and attention points. This endpoint helps identify key information, sentiment, and important details in the provided content.", "operationId": "askAttention", "requestBody": { "description": "Request containing the content to be analyzed and analysis parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskAttentionRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AskAttentionRequest" } } }, "required": true }, "responses": { "200": { "description": "Content successfully analyzed with attention points identified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskAttentionResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AskAttentionResponse" } } } }, "400": { "description": "Bad request - invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - the API key does not have the necessary permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred during analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "x-codegen-request-body-name": "body" } }, "/ask_attention/v2": { "post": { "tags": [ "Tool", "AskAttention" ], "summary": "Ask Attention V2", "description": "Analyzes conversations or prompts to provide insights and attention points. This endpoint helps identify key information, sentiment, and important details in the provided content.", "operationId": "askAttentionV2", "parameters": [ { "name": "include_timestamps", "in": "query", "description": "When true, return timestamped segments (start/end seconds + excerpt) for each conversation alongside the textual answer.", "schema": { "type": "boolean" } }, { "name": "summarize", "in": "query", "description": "When true, synthesize all per-conversation outputs into a single combined response appended with conversation_id \"summary\".", "schema": { "type": "boolean" } } ], "requestBody": { "description": "Request containing the content to be analyzed and analysis parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskAttentionRequestV2" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AskAttentionRequestV2" } } }, "required": true }, "responses": { "200": { "description": "Content successfully analyzed with attention points identified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskAttentionResponseV2" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AskAttentionResponseV2" } } } }, "400": { "description": "Bad request - invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - the API key does not have the necessary permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred during analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/calendar_events/{user_uuid}": { "get": { "tags": [ "Calendar" ], "summary": "List Calendar Events", "description": "Returns a paginated list of calendar events from a specific user", "operationId": "getCalendarEventsPage", "parameters": [ { "name": "user_uuid", "in": "path", "description": "User UUID", "required": true, "schema": { "type": "string" } }, { "name": "dateFrom", "in": "query", "description": "Filter events starting from this date-time (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "description": "Filter events until this date-time (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": true, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "description": "Number of items per page", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved calendar events page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEventsPage" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CalendarEventsPage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/create_deck": { "post": { "tags": [ "Tool", "CreateDeck" ], "summary": "Create Deck", "description": "Generates presentation decks based on conversations, deals, or other content. This endpoint creates structured presentations with key insights and data visualizations.", "operationId": "createDeck", "requestBody": { "description": "Request containing the content and parameters for deck generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeckRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateDeckRequest" } } }, "required": true }, "responses": { "200": { "description": "Deck successfully generated and ready for use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeckResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateDeckResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred during deck generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/chats": { "get": { "tags": [ "Chat" ], "summary": "List Chats", "description": "Returns a paginated list of chats with optional filters. Org-level API keys return all chats; user-level keys return only chats accessible to the user.", "operationId": "listChats", "parameters": [ { "name": "filter[external_id]", "in": "query", "description": "Filter by external ID (exact match)", "schema": { "type": "string" } }, { "name": "filter[type]", "in": "query", "description": "Filter by chat type (chat or email)", "schema": { "type": "string", "enum": [ "chat", "email" ] } }, { "name": "filter[title]", "in": "query", "description": "Filter by title (case-insensitive partial match)", "schema": { "type": "string" } }, { "name": "filter[participant_name]", "in": "query", "description": "Filter by participant name (case-insensitive partial match)", "schema": { "type": "string" } }, { "name": "filter[scorecard_id]", "in": "query", "description": "Filter by scorecard UUID(s) — returns chats evaluated with any of the given scorecards", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user UUID(s)", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[team_id]", "in": "query", "description": "Filter by team UUID(s)", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "from_date_time", "in": "query", "description": "Start of date range filter (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date_time", "in": "query", "description": "End of date range filter (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "exclude_transcript", "in": "query", "description": "If true, omit transcript data from response to reduce payload size", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "description": "Page number for pagination (starts from 1)", "schema": { "minimum": 1, "type": "integer", "default": 1 } }, { "name": "size", "in": "query", "description": "Number of items per page (min 1, max 50)", "schema": { "maximum": 50, "minimum": 1, "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Chats successfully returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChatsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListChatsResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scim/ServiceProviderConfigs": { "get": { "tags": [ "Scim" ], "summary": "Get SCIM Service Provider Config", "description": "Returns SCIM service provider capabilities. Required by SCIM clients like Okta to determine feature support.", "operationId": "getServiceProviderConfig", "responses": { "200": { "description": "Service Provider Configuration returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceProviderConfigResponse" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ServiceProviderConfigResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scim/Users": { "get": { "tags": [ "Scim", "User" ], "summary": "List SCIM Users", "description": "Retrieves a list of users, supports filtering and pagination. Used by SCIM clients like Okta.", "operationId": "listScimUsers", "parameters": [ { "name": "filter", "in": "query", "description": "Filter expression to retrieve matching users", "schema": { "type": "string" } }, { "name": "startIndex", "in": "query", "description": "The 1-based index of the first result", "schema": { "type": "integer", "default": 1 } }, { "name": "count", "in": "query", "description": "Desired maximum number of query results per page", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "User list retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScimUsersResponse" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ListScimUsersResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } } }, "post": { "tags": [ "Scim", "User" ], "summary": "Create SCIM User", "description": "Creates a new user. Used by SCIM clients like Okta to provision users.", "operationId": "createScimUser", "requestBody": { "description": "SCIM user creation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScimUserRequest" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/CreateScimUserRequest" } } }, "required": true }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/scim/Users/{id}": { "get": { "tags": [ "Scim", "User" ], "summary": "Get SCIM User", "description": "Retrieves a single user by ID. Used by SCIM clients like Okta.", "operationId": "listScimUser", "parameters": [ { "name": "id", "in": "path", "description": "SCIM user ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SCIM user returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } } }, "put": { "tags": [ "Scim", "User" ], "summary": "Update SCIM User", "description": "Updates user. Used by SCIM clients like Okta to provision users.", "operationId": "updateScimUser", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "SCIM user update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScimUserRequest" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/UpdateScimUserRequest" } } }, "required": true }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } }, "x-codegen-request-body-name": "body" }, "patch": { "tags": [ "Scim", "User" ], "summary": "Patch SCIM User", "description": "Partially updates a user.", "operationId": "patchScimUser", "parameters": [ { "name": "id", "in": "path", "description": "SCIM ID of the user", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchScimUserRequest" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/PatchScimUserRequest" } } }, "required": true }, "responses": { "200": { "description": "User patched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "400": { "description": "Invalid SCIM patch request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/scim/Groups": { "get": { "tags": [ "Scim", "Group" ], "summary": "List SCIM Groups", "description": "Retrieves a list of groups, supports filtering and pagination. Used by SCIM clients like Okta.", "operationId": "listScimGroups", "parameters": [ { "name": "startIndex", "in": "query", "description": "The 1-based index of the first result", "schema": { "type": "integer", "default": 1 } }, { "name": "count", "in": "query", "description": "Desired maximum number of query results per page", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "User list retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScimGroupsResponse" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ListScimGroupsResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } } }, "post": { "tags": [ "Scim", "Group" ], "summary": "Create SCIM Group", "operationId": "createScimGroup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimCreateGroupRequest" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimCreateGroupRequest" } } }, "required": true }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimCreateGroupResponse" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimCreateGroupResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/scim/Groups/{id}": { "get": { "tags": [ "Scim", "Group" ], "summary": "Get SCIM Group", "description": "Retrieves a single group by ID. Used by SCIM clients like Okta.", "operationId": "listScimGroup", "parameters": [ { "name": "id", "in": "path", "description": "SCIM group ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Group retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "404": { "description": "Group not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } } }, "put": { "tags": [ "Scim", "Group" ], "summary": "Update SCIM Group", "description": "Updates group. Used by SCIM clients like Okta to provision groups.", "operationId": "updateScimGroup", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "SCIM group update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScimGroupRequest" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/UpdateScimGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } }, "x-codegen-request-body-name": "body" }, "patch": { "tags": [ "Scim", "Group" ], "summary": "Patch SCIM Group", "description": "Partially updates a group using SCIM patch semantics.", "operationId": "patchScimGroup", "parameters": [ { "name": "id", "in": "path", "description": "SCIM ID of the group", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchScimGroupRequest" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/PatchScimGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "Group patched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "400": { "description": "Invalid SCIM patch request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "404": { "description": "Group not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/Base_Scim_Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/usageReport": { "get": { "tags": [ "Tool", "UsageReport" ], "summary": "Get Usage Report", "description": "Retrieves detailed usage statistics for specified users or teams within a given time period. This endpoint helps track API consumption, feature usage, and user activity patterns.", "operationId": "getUsageReport", "parameters": [ { "name": "user-uuids", "in": "query", "description": "List of user UUIDs to include in the report", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "team-uuids", "in": "query", "description": "List of team UUIDs to include in the report", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "startDate", "in": "query", "description": "Start date for the usage report period (inclusive)", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "End date for the usage report period (inclusive)", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Usage report successfully generated with detailed statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReportResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UsageReportResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while generating the usage report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scorecards/summary": { "post": { "tags": [ "Scorecard" ], "summary": "Get Scorecards Summary", "description": "Retrieves detailed usage statistics for specified users or teams within a given time period.", "operationId": "getScorecardsSummary", "requestBody": { "description": "Request containing the content to be analyzed and analysis parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardsSummaryRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardsSummaryRequest" } } }, "required": true }, "responses": { "200": { "description": "Scorecards summary successfully generated with detailed statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardsSummaryResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardsSummaryResponse" } } } }, "400": { "description": "Bad request - invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while generating the usage report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/scorecards": { "get": { "tags": [ "Scorecard" ], "summary": "List Scorecards", "description": "Retrieves scorecards visible to the caller. User-scoped API keys see scorecards for their allowed teams; org-scoped API keys see every scorecard in the organization. Pagination is optional: when both page and size are omitted, the full result set is returned to preserve backward compatibility.", "operationId": "listScorecards", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination (1-indexed). If omitted, pagination is not applied and every visible scorecard is returned.", "schema": { "minimum": 1, "type": "integer" } }, { "name": "size", "in": "query", "description": "Number of scorecards per page (min 1, max 200). Ignored when page is omitted.", "schema": { "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "Scorecards successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "application/vnd.api+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "size must be between 1 and 200" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving scorecards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Scorecard" ], "summary": "Create Scorecard", "description": "Creates a new scorecard template in the caller's organization. Requires an org-scoped API key (admin-equivalent). The new scorecard has no items on creation — use POST /scorecards/{id}/items to add scoring criteria.", "operationId": "createScorecard", "requestBody": { "description": "Scorecard creation payload. Title is required; teamId / allTeams / interactionType / enabled are optional.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScorecardRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateScorecardRequest" } } }, "required": true }, "responses": { "201": { "description": "Scorecard successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardResponse" } } } }, "400": { "description": "Invalid request body (missing title, title too long, conflicting teamId+allTeams, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "title must be between 1 and 128 characters" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller's API key does not have permission to create scorecards in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "forbidden", "status": "403", "code": "403", "title": "Forbidden", "detail": "This endpoint requires an organization-scoped API key" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request body failed schema-level validation (missing required field, string shorter than minLength, value outside declared range, etc.). Emitted by the swagger validation layer before handler code runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 604, "message": "title in body should be at least 1 chars long" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while creating the scorecard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/connectionReport": { "get": { "tags": [ "Tool" ], "summary": "Get Connection Report", "description": "Simple report showing which users have connected their calendar and email. No parameters needed - shows all users in the organization.", "operationId": "getConnectionReport", "responses": { "200": { "description": "Connection report successfully generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionReportResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConnectionReportResponse" } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while generating the connection report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/library/folders": { "get": { "tags": [ "Library" ], "summary": "List Library Folder Structure", "description": "Retrieves the folder structure for the library. If folderUUID is provided, returns only the direct subfolders of that folder. If folderUUID is not provided, returns the root folder structure. This endpoint supports lazy loading of folder hierarchies for workflow builders.", "operationId": "listLibraryFolders", "parameters": [ { "name": "userUUID", "in": "query", "description": "UUID of the user. Required to fetch folder structure.", "required": true, "schema": { "type": "string" } }, { "name": "folderUUID", "in": "query", "description": "UUID of the folder to fetch subfolders from. If not provided, returns root folder structure. When provided, returns only direct subfolders of the specified folder.", "schema": { "type": "string" } }, { "name": "myLibrary", "in": "query", "description": "If true, returns only the user's personal library folders. If false, returns organization-level library folders.", "schema": { "type": "boolean", "default": false } }, { "name": "includeHidden", "in": "query", "description": "If true, includes hidden folders in the response. Default is false.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Folder structure successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryFolderStructureResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/LibraryFolderStructureResponse" } } } }, "401": { "description": "Authentication required. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Base_500_Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/super-agent/messages": { "post": { "tags": [ "Super Agent" ], "summary": "Send Super Agent Message", "description": "Sends a message to the super agent. If session_id is not provided, creates a new session. Returns synchronously if completed within 15 seconds, otherwise returns 202 Accepted with session ID for polling. Optionally accepts a callback_url for webhook notification when the assistant response is ready.", "operationId": "sendSuperAgentMessage", "parameters": [ { "name": "callback_url", "in": "query", "description": "Optional webhook URL to receive the assistant's response when processing completes", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSuperAgentMessageRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SendSuperAgentMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "Message processed successfully with assistant response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuperAgentMessageResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SuperAgentMessageResponse" } } } }, "202": { "description": "Message accepted, processing in background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuperAgentMessageAcceptedResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SuperAgentMessageAcceptedResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Valid user-level API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Session does not belong to user's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/super-agent/sessions": { "get": { "tags": [ "Super Agent" ], "summary": "List Super Agent Sessions", "description": "Retrieves a list of super agent chat sessions for the authenticated user. Supports optional filtering by title search and pagination.", "operationId": "listSuperAgentSessions", "parameters": [ { "name": "search", "in": "query", "description": "Optional search term to filter sessions by title", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of sessions to return (default: 50)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sessions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuperAgentSessionsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SuperAgentSessionsResponse" } } } }, "401": { "description": "Valid user-level API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/super-agent/sessions/{sessionId}/messages": { "get": { "tags": [ "Super Agent" ], "summary": "Get Super Agent Session History", "description": "Retrieves all messages for a given super agent chat session. Session must belong to user's organization.", "operationId": "getSuperAgentSessionHistory", "parameters": [ { "name": "sessionId", "in": "path", "description": "The session ID to retrieve messages for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session messages retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuperAgentSessionHistoryResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SuperAgentSessionHistoryResponse" } } } }, "401": { "description": "Valid user-level API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Session does not belong to user's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/super-agent/sessions/{sessionId}": { "delete": { "tags": [ "Super Agent" ], "summary": "Delete Super Agent Session", "description": "Deletes a super agent chat session and all its messages. Session must belong to user's organization.", "operationId": "deleteSuperAgentSession", "parameters": [ { "name": "sessionId", "in": "path", "description": "The session ID to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session deleted successfully", "content": {} }, "401": { "description": "Valid user-level API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Session does not belong to user's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/crm/query": { "post": { "tags": [ "CRM" ], "summary": "Execute CRM Query", "description": "Executes a query against the connected CRM platform (e.g., Salesforce SOQL). The query is validated for security before execution.", "operationId": "executeCRMQuery", "requestBody": { "description": "Query request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteCRMQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Query executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteCRMQueryResponse" } } } }, "400": { "description": "Invalid query or request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base_401_Error" } } } }, "404": { "description": "No CRM account configured for this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "APIKeyHeader": [] } ], "x-codegen-request-body-name": "body" } }, "/conversations/{id}/title": { "put": { "tags": [ "Conversation" ], "summary": "Change Conversation Title", "description": "Updates the title of an existing conversation. The conversation is re-indexed in search after the title change.", "operationId": "changeConversationTitle", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the conversation to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "New title for the conversation", "content": { "application/json": { "schema": { "required": [ "title" ], "type": "object", "properties": { "title": { "type": "string", "description": "The new title for the conversation", "example": "Q4 Sales Review with Acme Corp" } } } }, "application/vnd.api+json": { "schema": { "required": [ "title" ], "type": "object", "properties": { "title": { "type": "string", "description": "The new title for the conversation", "example": "Q4 Sales Review with Acme Corp" } } } } }, "required": true }, "responses": { "200": { "description": "Title updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/conversations/{id}/labels": { "put": { "tags": [ "Conversation" ], "summary": "Change Conversation Labels", "description": "Replaces the labels (key-value metadata) on a conversation. When labels change, the label-changed workflow is triggered and CRM intelligence may be refreshed unless analysis is explicitly skipped.", "operationId": "changeConversationLabels", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the conversation to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Labels to set on the conversation", "content": { "application/json": { "schema": { "required": [ "labels" ], "type": "object", "properties": { "labels": { "type": "object", "additionalProperties": true, "description": "Key-value map of labels to set on the conversation. Replaces all existing labels.", "example": { "deal_stage": "negotiation", "priority": "high" } }, "skip_analysis": { "type": "boolean", "description": "When true, skips CRM intelligence refresh after the label change. Defaults to false.", "default": false } } } }, "application/vnd.api+json": { "schema": { "required": [ "labels" ], "type": "object", "properties": { "labels": { "type": "object", "additionalProperties": true, "description": "Key-value map of labels to set on the conversation. Replaces all existing labels.", "example": { "deal_stage": "negotiation", "priority": "high" } }, "skip_analysis": { "type": "boolean", "description": "When true, skips CRM intelligence refresh after the label change. Defaults to false.", "default": false } } } } }, "required": true }, "responses": { "200": { "description": "Labels updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/conversations/{id}/crm/confirm": { "post": { "tags": [ "Conversation", "CRM" ], "summary": "Confirm CRM Intelligence", "description": "Confirms user-reviewed CRM intelligence extracted from a conversation. After confirmation, the intelligence data is persisted, CRM fields are updated, and a CRM export workflow trigger is executed.", "operationId": "confirmCRM", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the conversation whose CRM intelligence is being confirmed", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "CRM intelligence items to confirm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmCRMRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConfirmCRMRequest" } } }, "required": true }, "responses": { "200": { "description": "CRM intelligence confirmed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/conversations/{id}/linked-crm-records": { "put": { "tags": [ "Conversation", "CRM" ], "summary": "Update Linked CRM Records", "description": "Updates the CRM records (accounts, contacts, etc.) linked to a conversation. Replaces the current set of linked records with the provided list.", "operationId": "updateLinkedCrmRecords", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the conversation to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Linked CRM records to set on the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLinkedCrmRecordsRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateLinkedCrmRecordsRequest" } } }, "required": true }, "responses": { "200": { "description": "Linked CRM records updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLinkedCrmRecordsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateLinkedCrmRecordsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/teams/{id}/opportunity": { "put": { "tags": [ "Team", "Opportunity" ], "summary": "Update Team Opportunity", "description": "Creates or updates an opportunity record associated with a team. If an opportunity with the given ID already exists for the team, it is updated; otherwise a new one is created.", "operationId": "updateTeamOpportunity", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the team", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Opportunity details to upsert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamOpportunityRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateTeamOpportunityRequest" } } }, "required": true }, "responses": { "200": { "description": "Opportunity created or updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamOpportunityResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateTeamOpportunityResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/conversations/by-external-id/{externalId}": { "get": { "tags": [ "Conversation" ], "summary": "Get Conversation by External ID", "description": "Looks up a conversation by its external application ID (the ID from the source system that originally imported the conversation). Returns the Attention conversation UUID if found.", "operationId": "conversationByExternalId", "parameters": [ { "name": "externalId", "in": "path", "description": "The external application ID used when the conversation was imported", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversation found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationByExternalIdResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConversationByExternalIdResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No conversation found for the given external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integration-workflows": { "get": { "tags": [ "Integration" ], "summary": "List Integration Workflows", "description": "Returns all integration workflows for the authenticated organization.", "operationId": "listIntegrationWorkflows", "responses": { "200": { "description": "List of integration workflows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIntegrationWorkflowsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListIntegrationWorkflowsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/conversations/{id}/trigger-native-integration": { "post": { "tags": [ "Conversation" ], "summary": "Trigger Native Integration", "description": "Triggers CRM integration workflows for a conversation (fire-and-forget). Uses deterministic workflow IDs for deduplication.", "operationId": "triggerNativeIntegration", "parameters": [ { "name": "id", "in": "path", "description": "Conversation ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerNativeIntegrationRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/TriggerNativeIntegrationRequest" } } }, "required": false }, "responses": { "200": { "description": "Workflows triggered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerNativeIntegrationResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/TriggerNativeIntegrationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "APIKeyHeader": [] } ], "x-codegen-request-body-name": "body" } }, "/knowledge-base/sources": { "get": { "tags": [ "Knowledge Base" ], "summary": "List KB Sources", "description": "Returns all knowledge base sources for the organization. Content is excluded from list view — use the get endpoint for full content.", "operationId": "listKBSources", "responses": { "200": { "description": "List of KB sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKBSourcesResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListKBSourcesResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Knowledge Base" ], "summary": "Create KB Source", "description": "Creates a new knowledge base source with inline content. Automatically triggers indexing for vector search. For file uploads, use the upload endpoint instead.", "operationId": "createKBSource", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKBSourceRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateKBSourceRequest" } } }, "required": true }, "responses": { "201": { "description": "KB source created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/knowledge-base/sources/{sourceId}": { "get": { "tags": [ "Knowledge Base" ], "summary": "Get KB Source", "description": "Returns a single knowledge base source with full content.", "operationId": "getKBSource", "parameters": [ { "name": "sourceId", "in": "path", "description": "The unique identifier of the KB source", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "KB source details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "KB source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Knowledge Base" ], "summary": "Delete KB Source", "description": "Deletes a knowledge base source, its indexed chunks, and associated S3 objects.", "operationId": "deleteKBSource", "parameters": [ { "name": "sourceId", "in": "path", "description": "The unique identifier of the KB source", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "KB source deleted successfully", "content": {} }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "KB source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Knowledge Base" ], "summary": "Update KB Source", "description": "Updates the title and/or content of a KB source. If content is changed, triggers re-indexing.", "operationId": "updateKBSource", "parameters": [ { "name": "sourceId", "in": "path", "description": "The unique identifier of the KB source", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKBSourceRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateKBSourceRequest" } } }, "required": true }, "responses": { "200": { "description": "KB source updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "KB source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/labels": { "get": { "tags": [ "Label" ], "summary": "List Labels", "description": "Retrieves a paginated list of labels for the authenticated organization. Labels are used to categorize conversations and drive AI flows, scorecard criteria, and intelligence-item-collection criteria. Only labels belonging to the caller's organization are returned.", "operationId": "listLabels", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number to return. Defaults to 1.", "schema": { "minimum": 1, "type": "integer", "default": 1 } }, { "name": "size", "in": "query", "description": "Number of labels per page. Defaults to 50. Maximum 200.", "schema": { "maximum": 200, "minimum": 1, "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Labels successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLabelsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListLabelsResponse" } } } }, "400": { "description": "Invalid pagination parameters (page < 1, size < 1, or size > 200)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "size must be between 1 and 200" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid organization-scoped API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Valid organization-scoped API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving labels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Label" ], "summary": "Create Label", "description": "Creates a new label in the caller's organization. The label name must be unique within the organization; attempting to create a duplicate returns 409. On a network retry after a successful first request, clients may observe a 409 and should fetch the label by name to confirm creation.", "operationId": "createLabel", "requestBody": { "description": "Details of the label to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateLabelRequest" } } }, "required": true }, "responses": { "201": { "description": "Label successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } } } }, "400": { "description": "Invalid request body (missing name, name too long, description too long, or invalid option shape)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "name must be between 1 and 128 characters" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid organization-scoped API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Valid organization-scoped API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A label with the same name already exists in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "conflict", "status": "409", "code": "409", "title": "Conflict", "detail": "A label with this name already exists in the organization" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema-level validation failure (e.g. body fails minLength/maxLength). Returned before handler-level business rules are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 604, "message": "name in body should be at least 1 chars long" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while creating the label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/labels/{id}": { "get": { "tags": [ "Label" ], "summary": "Get Label", "description": "Retrieves a single label by its UUID. The label must belong to the caller's organization; cross-organization lookups return 404 (not 403) to avoid leaking existence of resources in other organizations.", "operationId": "getLabel", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the label to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Label successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } } } }, "401": { "description": "Authentication failed. Please provide a valid organization-scoped API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Valid organization-scoped API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Label not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Label not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving the label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Label" ], "summary": "Delete Label", "description": "Permanently deletes a label from the caller's organization. This is a hard delete. References to the label from scorecard criteria and intelligence-item-collection criteria are not rewritten; callers that need a clean cascade should rename to a tombstone value first. Cross-organization deletes return 404.", "operationId": "deleteLabel", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the label to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Label successfully deleted. Response body is empty.", "content": {} }, "401": { "description": "Authentication failed. Please provide a valid organization-scoped API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Valid organization-scoped API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Label not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Label not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while deleting the label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Label" ], "summary": "Update Label", "description": "Partially updates a label. Only fields present in the request body are applied (pointer-nil merge semantics). Renaming a label cascades updates to scorecard criteria and intelligence-item-collection criteria that reference the old label name. Cross-organization updates return 404.", "operationId": "updateLabel", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the label to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update. Omit a field to leave it unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLabelRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateLabelRequest" } } }, "required": true }, "responses": { "200": { "description": "Label successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } } } }, "400": { "description": "Invalid request body (empty update, name too long, description too long, or invalid option shape)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "description must be 0 to 2000 characters" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid organization-scoped API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Valid organization-scoped API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Label not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Label not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another label in the organization already uses the requested name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "conflict", "status": "409", "code": "409", "title": "Conflict", "detail": "A label with this name already exists in the organization" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema-level validation failure (e.g. body fails minLength/maxLength). Returned before handler-level business rules are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 604, "message": "name in body should be at least 1 chars long" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while updating the label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/field-configurations": { "get": { "tags": [ "Field Configuration" ], "summary": "List Field Configurations", "description": "Returns a paginated list of field configurations owned by the authenticated organization.", "operationId": "listFieldConfigurations", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number. Defaults to 1.", "schema": { "type": "integer" } }, { "name": "size", "in": "query", "description": "Page size. Defaults to 50; maximum 200.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Field configurations successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFieldConfigurationsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListFieldConfigurationsResponse" } } } }, "400": { "description": "Invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Field Configuration" ], "summary": "Create Field Configuration", "description": "Creates a new field configuration owned by the authenticated organization. The owning organization is inferred from the API key and any organization UUID supplied on the body is ignored.", "operationId": "createFieldConfiguration", "requestBody": { "description": "Field configuration to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFieldConfigurationRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateFieldConfigurationRequest" } } }, "required": true }, "responses": { "201": { "description": "Field configuration created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationResponse" } } } }, "400": { "description": "Invalid or missing fields on the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A field configuration with the same name already exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema-level validation failure on the request body (e.g. required field missing or value outside the allowed length range).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/field-configurations/{id}": { "get": { "tags": [ "Field Configuration" ], "summary": "Get Field Configuration", "description": "Returns a single field configuration by UUID. Field configurations belonging to other organizations return 404 - the API never leaks cross-organization existence.", "operationId": "getFieldConfiguration", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Field configuration successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationResponse" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No field configuration with the provided UUID exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Field Configuration" ], "summary": "Delete Field Configuration", "description": "Hard-deletes a field configuration owned by the authenticated organization. All `IntelligenceItemAssignment` rows pointing at the configuration are cleaned up in the same request (cascading cleanup). Field configurations belonging to other organizations return 404.", "operationId": "deleteFieldConfiguration", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Field configuration and all dependent assignment rows were successfully deleted.", "content": {} }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No field configuration with the provided UUID exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Field Configuration" ], "summary": "Update Field Configuration", "description": "Partially updates a field configuration. Only properties present on the body are modified (PATCH semantics). Field configurations belonging to other organizations return 404.", "operationId": "updateFieldConfiguration", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update on the configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFieldConfigurationRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateFieldConfigurationRequest" } } }, "required": true }, "responses": { "200": { "description": "Field configuration successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationResponse" } } } }, "400": { "description": "Invalid body parameters or nothing mutable supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No field configuration with the provided UUID exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A field configuration with the same name already exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema-level validation failure on the request body (e.g. value outside the allowed length range).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/field-configurations/{id}/items": { "get": { "tags": [ "Field Configuration" ], "summary": "List Field Configuration Items", "description": "Returns a paginated list of items belonging to a field configuration.", "operationId": "listFieldConfigurationItems", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "1-indexed page number. Defaults to 1.", "schema": { "type": "integer" } }, { "name": "size", "in": "query", "description": "Page size. Defaults to 50; maximum 200.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Items successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFieldConfigurationItemsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListFieldConfigurationItemsResponse" } } } }, "400": { "description": "Invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No field configuration with the provided UUID exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Field Configuration" ], "summary": "Create Field Configuration Item", "description": "Creates a single new item inside a field configuration. The REST endpoint wraps the singular request around the underlying bulk creation path (ADR-9). Creating an item fans out into one `IntelligenceItemAssignment` per team the parent configuration is assigned to - the response body includes both the new item and the list of created assignments under `data.assignments` (explicit fan-out).", "operationId": "createFieldConfigurationItem", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Item to create inside the field configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFieldConfigurationItemRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateFieldConfigurationItemRequest" } } }, "required": true }, "responses": { "201": { "description": "Item created successfully. The response body contains the new item and the fan-out assignment rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationItemCreateResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationItemCreateResponse" } } } }, "400": { "description": "Invalid or missing fields on the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No field configuration with the provided UUID exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "An item with the same title already exists in this field configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema-level validation failure on the request body (e.g. required field missing or value outside the allowed length range).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/field-configurations/{id}/items/{itemId}": { "get": { "tags": [ "Field Configuration" ], "summary": "Get Field Configuration Item", "description": "Returns a single field-configuration item by UUID. Items belonging to a field configuration in another organization return 404.", "operationId": "getFieldConfigurationItem", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "UUID of the field-configuration item.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Item successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationItemResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationItemResponse" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No item with the provided UUID exists in the specified field configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Field Configuration" ], "summary": "Delete Field Configuration Item", "description": "Hard-deletes a field-configuration item and every `IntelligenceItemAssignment` row that referenced it. Items belonging to a field configuration in another organization return 404.", "operationId": "deleteFieldConfigurationItem", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "UUID of the field-configuration item.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Item and all dependent assignment rows were successfully deleted.", "content": {} }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No item with the provided UUID exists in the specified field configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Field Configuration" ], "summary": "Update Field Configuration Item", "description": "Partially updates a field-configuration item (PATCH semantics). Items belonging to a field configuration in another organization return 404.", "operationId": "updateFieldConfigurationItem", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the field configuration.", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "UUID of the field-configuration item.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update on the item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFieldConfigurationItemRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateFieldConfigurationItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Item successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationItemResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FieldConfigurationItemResponse" } } } }, "400": { "description": "Invalid body parameters or nothing mutable supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed. Please provide a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No item with the provided UUID exists in the specified field configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another item with the same title already exists in this field configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema-level validation failure on the request body (e.g. value outside the allowed length range).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/scorecards/{id}": { "get": { "tags": [ "Scorecard" ], "summary": "Get Scorecard", "description": "Retrieves a single scorecard by its UUID, scoped to the caller's organization. Cross-organization lookups return 404 to prevent existence leaks.", "operationId": "getScorecard", "parameters": [ { "name": "id", "in": "path", "description": "Scorecard UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scorecard successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scorecard not found in the caller's organization (returned for both missing and cross-org IDs)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Scorecard not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving the scorecard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Scorecard" ], "summary": "Update Scorecard", "description": "Partially updates a scorecard. Only fields present in the request body are modified; omitted fields retain their current values. Requires an org-scoped API key.", "operationId": "updateScorecard", "parameters": [ { "name": "id", "in": "path", "description": "Scorecard UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update. All fields are optional; at least one must be provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScorecardRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateScorecardRequest" } } }, "required": true }, "responses": { "200": { "description": "Scorecard successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardResponse" } } } }, "400": { "description": "Invalid request body (empty patch, title out of range, conflicting teamId+allTeams)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "request body must contain at least one field to update" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller's API key does not have permission to modify this scorecard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "forbidden", "status": "403", "code": "403", "title": "Forbidden", "detail": "Insufficient permissions to update this scorecard" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scorecard not found in the caller's organization (returned for both missing and cross-org IDs)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Scorecard not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request body failed schema-level validation (string shorter than minLength, value outside declared range, etc.). Emitted by the swagger validation layer before handler code runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 604, "message": "title in body should be at least 1 chars long" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while updating the scorecard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/scorecards/{id}/items": { "get": { "tags": [ "Scorecard" ], "summary": "List Scorecard Items", "description": "Retrieves all items (scoring criteria) for a given scorecard, ordered by position ascending.", "operationId": "listScorecardItems", "parameters": [ { "name": "id", "in": "path", "description": "Parent scorecard UUID", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "minimum": 1, "type": "integer", "default": 1 } }, { "name": "size", "in": "query", "description": "Number of items per page (min 1, max 200, default 50)", "schema": { "maximum": 200, "minimum": 1, "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Scorecard items successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScorecardItemsResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ListScorecardItemsResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Parent scorecard not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Scorecard not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while listing scorecard items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Scorecard" ], "summary": "Create Scorecard Item", "description": "Adds a single item (scoring criterion) to the given scorecard. The new item is appended at the next position. Requires an org-scoped API key.", "operationId": "createScorecardItem", "parameters": [ { "name": "id", "in": "path", "description": "Parent scorecard UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Scorecard item creation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScorecardItemRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CreateScorecardItemRequest" } } }, "required": true }, "responses": { "201": { "description": "Scorecard item successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardItemResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardItemResponse" } } } }, "400": { "description": "Invalid request body (missing title, weight out of range, numeric min > max, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "weight must be between 0 and 100" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller's API key does not have permission to add items to this scorecard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "forbidden", "status": "403", "code": "403", "title": "Forbidden", "detail": "Insufficient permissions to add items to this scorecard" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Parent scorecard not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Scorecard not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request body failed schema-level validation (missing required field, string shorter than minLength, value outside declared range, etc.). Emitted by the swagger validation layer before handler code runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 604, "message": "title in body should be at least 1 chars long" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while creating the scorecard item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/scorecards/{id}/items/{itemId}": { "get": { "tags": [ "Scorecard" ], "summary": "Get Scorecard Item", "description": "Retrieves a single scorecard item. Both the parent scorecard and the item must belong to the caller's organization.", "operationId": "getScorecardItem", "parameters": [ { "name": "id", "in": "path", "description": "Parent scorecard UUID", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "Scorecard item UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scorecard item successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardItemResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardItemResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scorecard or item not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Scorecard item not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while retrieving the scorecard item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Scorecard" ], "summary": "Delete Scorecard Item", "description": "Deletes a scorecard item. Sibling items are automatically re-ordered so their positions remain contiguous. Requires an org-scoped API key.", "operationId": "deleteScorecardItem", "parameters": [ { "name": "id", "in": "path", "description": "Parent scorecard UUID", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "Scorecard item UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Scorecard item successfully deleted", "content": {} }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller's API key does not have permission to delete items from this scorecard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "forbidden", "status": "403", "code": "403", "title": "Forbidden", "detail": "Insufficient permissions to delete this scorecard item" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scorecard or item not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Scorecard item not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while deleting the scorecard item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Scorecard" ], "summary": "Update Scorecard Item", "description": "Partially updates a scorecard item. Only fields present in the body are modified; omitted fields retain current values. Requires an org-scoped API key.", "operationId": "updateScorecardItem", "parameters": [ { "name": "id", "in": "path", "description": "Parent scorecard UUID", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "Scorecard item UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update. All fields optional; at least one required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScorecardItemRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/UpdateScorecardItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Scorecard item successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorecardItemResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ScorecardItemResponse" } } } }, "400": { "description": "Invalid request body (empty patch, title out of range, weight out of range, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "invalid_parameter", "status": "400", "code": "400", "title": "Invalid Parameter", "detail": "weight must be between 0 and 100" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "unauthorized", "status": "401", "code": "401", "title": "Unauthorized", "detail": "Authentication failed - valid API key required" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller's API key does not have permission to modify this scorecard item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "forbidden", "status": "403", "code": "403", "title": "Forbidden", "detail": "Insufficient permissions to update this scorecard item" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scorecard or item not found in the caller's organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "not_found", "status": "404", "code": "404", "title": "Not Found", "detail": "Scorecard item not found" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request body failed schema-level validation (string shorter than minLength, value outside declared range, etc.). Emitted by the swagger validation layer before handler code runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 604, "message": "title in body should be at least 1 chars long" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while updating the scorecard item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/knowledge-base/sources/upload": { "post": { "tags": [ "Knowledge Base" ], "summary": "Request KB Source Upload URL", "description": "Creates a KB source record and returns a presigned S3 PUT URL for file upload. After uploading the file, call confirm-upload to validate and trigger indexing. Supported file types: PDF, Markdown, HTML, plain text. Maximum file size: 100 MB.", "operationId": "requestKBSourceUpload", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestKBSourceUploadRequest" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/RequestKBSourceUploadRequest" } } }, "required": true }, "responses": { "201": { "description": "Upload URL generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestKBSourceUploadResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/RequestKBSourceUploadResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "body" } }, "/knowledge-base/sources/{sourceId}/confirm-upload": { "post": { "tags": [ "Knowledge Base" ], "summary": "Confirm KB Source Upload", "description": "Validates the uploaded file (format via magic bytes, size against limit) and triggers indexing. If validation fails, the file is deleted from S3 and the source is removed. Supported formats: PDF, Markdown, HTML, plain text. Maximum size: 100 MB.", "operationId": "confirmKBSourceUpload", "parameters": [ { "name": "sourceId", "in": "path", "description": "The unique identifier of the KB source", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload validated and indexing triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/KBSourceResponse" } } } }, "400": { "description": "File validation failed (unsupported format or size exceeded)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "KB source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recorder_metrics/all_meetings": { "get": { "tags": [ "RecorderMetrics" ], "summary": "List Recorder Meetings", "description": "Returns a cursor-paginated, deduplicated list of calendar meetings for the authenticated organization with the recording status of each meeting and each org participant. One row per calendar event.\n\nIntended for bulk export to data warehouses and analytics pipelines. Requires an organization-level API key — user-scoped keys are rejected.\n\n### Window\n* `fromDateTime` and `toDateTime` are required and must define a window of at most **90 days**.\n* When `upcoming=true`, results are ordered ascending by date; otherwise descending. UUID is used as a stable tiebreaker for same-date meetings.\n\n### Pagination\n* Cursor-based. The first page is requested with no `cursor`. The response's `nextCursor` is passed back unchanged on the next call.\n* When the response has no `nextCursor`, the iteration has reached the end of the dataset.\n* `size` is clamped to a server-side maximum of 200 (default 50).\n* For periodic backfills, run a complete iteration per refresh (start each refresh with no `cursor`); rows inserted into the window after an iteration starts are picked up on the next refresh.\n\n### Meeting `status` values\nAttention's native status taxonomy is returned as-is. Values currently surfaced (non-exhaustive list, subject to additive evolution): `recorded`, `calendar_event_cancelled`, `empty_recording`, `user_override`, `event_not_accepted`, `not_join_internal_team_meetings`, `external_meetings_disabled`, `blacklisted_attendees`, `not_join_when_alone`, `bot_disabled`, `bot_removed`, `waiting_room`, `technical_error`, `no_meeting_link`, `bot_not_scheduled`, `scheduled_future`.\n\nClients should map these codes to their own reporting taxonomy on the consumer side (e.g. dbt models, BI views).\n\n### Field semantics\n* `uuid` — calendar event UUID (deduplication key).\n* `conversationUuid` — populated only when a recording exists (`status=recorded`).\n* `userUuid` / `userName` — the user attributed as the recorder; falls back to the first event participant when no recording exists.\n* `participants[]` — every org user invited to the event with their per-user status (a user may be `recorded` while another is `not_join_when_alone` on the same meeting).\n* `statusLabel` — human-readable label resolved server-side, suitable for direct display.", "operationId": "listRecorderMeetings", "parameters": [ { "name": "fromDateTime", "in": "query", "description": "Window start (inclusive), ISO 8601 date-time, e.g. `2026-04-01T00:00:00Z`.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "toDateTime", "in": "query", "description": "Window end (inclusive), ISO 8601 date-time. Must be after `fromDateTime` and within 90 days of it.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by a previous call. Omit on the first page.", "schema": { "type": "string" } }, { "name": "size", "in": "query", "description": "Items per page. Defaults to 50. Server-side maximum is 200; values above are clamped.", "schema": { "type": "integer" } }, { "name": "upcoming", "in": "query", "description": "When `true`, returns meetings whose start time is in the future (ascending order). Defaults to `false` (past meetings, descending order).", "schema": { "type": "boolean" } }, { "name": "filter[user_id]", "in": "query", "description": "Restrict the dedup pass to meetings involving any of the given user UUIDs. UUIDs not belonging to the authenticated organization are silently dropped; if none survive, an empty page is returned to avoid cross-tenant membership probing.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[meeting_type]", "in": "query", "description": "Restrict results to internal (all org participants) or external meetings.", "schema": { "type": "string", "enum": [ "internal", "external" ] } } ], "responses": { "200": { "description": "Cursor-paginated list of meetings with recording status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecorderMetricsMeetingsPage" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/RecorderMetricsMeetingsPage" } } } }, "400": { "description": "Invalid request parameters (missing dates, invalid cursor, window over 90 days)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed or non-organization API key supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/actions": { "get": { "tags": [ "Proactive" ], "summary": "List Actions", "description": "Lists Proactive actions (Next Best Actions), mirroring the action feed users see in the UI.\n\n### Scope\n* An **organization-level** API key returns actions for every user in the organization.\n* A **user-scoped** API key returns only that user's actions; the `owner_uuid` filter is ignored for user-scoped keys.\n\n### Filtering\n* `status` defaults to `pending`. Pass one or more of `pending`, `drafted`, `sent`, `dismissed`, `expired` to widen the set. Suppressed actions are never returned.\n* `owner_uuid` narrows the result to a single owner (organization-level keys only).\n\n### Pagination\n* Cursor-based. Omit `cursor` for the first page; pass the response's `next_cursor` unchanged for the next. When `next_cursor` is absent, iteration is complete.\n* `size` is clamped to a server-side maximum of 200 (default 50).", "operationId": "listProactiveActions", "parameters": [ { "name": "owner_uuid", "in": "query", "description": "Filter to a single owner user UUID. Only honored for organization-level API keys; ignored for user-scoped keys.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Lifecycle statuses to include. Defaults to pending only. Suppressed actions are never returned.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending", "drafted", "sent", "dismissed", "expired" ] } } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor from a previous response's next_cursor. Omit for the first page.", "schema": { "type": "string" } }, { "name": "size", "in": "query", "description": "Maximum number of actions to return per page (default 50, max 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Successfully retrieved the matching actions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProactiveActionsResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while processing the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/actions/{action_uuid}/dismiss": { "post": { "tags": [ "Proactive" ], "summary": "Dismiss Action", "description": "Dismisses a pending Proactive action owned by the caller. Mirrors the dismiss action in the UI.", "operationId": "dismissProactiveAction", "parameters": [ { "name": "action_uuid", "in": "path", "description": "Unique identifier of the action to dismiss", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Action dismissed (or already not pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProactiveActionMutationResponse" } } } }, "401": { "description": "Authentication failed - valid API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Action not found or not owned by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error occurred while processing the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "ExecuteCRMQueryRequest": { "required": [ "query" ], "type": "object", "properties": { "query": { "maxLength": 10000, "type": "string", "description": "The query to execute (e.g., SOQL for Salesforce)", "example": "SELECT Id, Name, Email FROM Contact WHERE CreatedDate = LAST_N_DAYS:30 LIMIT 100" } }, "example": { "query": "SELECT Id, Name, Amount FROM Opportunity WHERE StageName = 'Closed Won' LIMIT 10" } }, "ExecuteCRMQueryResponse": { "type": "object", "properties": { "records": { "type": "array", "description": "Query result records", "items": { "type": "object", "additionalProperties": true } }, "totalSize": { "type": "integer", "description": "Total number of records matching the query" }, "done": { "type": "boolean", "description": "Whether all records have been returned" }, "nextRecordsUrl": { "type": "string", "description": "URL to fetch the next batch of records (if paginated)" } }, "example": { "records": [ { "Id": "006ABC123", "Name": "Enterprise Deal", "Amount": 50000 } ], "totalSize": 1, "done": true } }, "ScorecardsSummaryRequest": { "required": [ "fromDateTime", "scorecardUUID", "scorecardsItemsUUIDs", "teamUUIDs", "toDateTime", "userUUIDs" ], "type": "object", "properties": { "fromDateTime": { "type": "string", "description": "Start date and time for filtering scorecards (ISO 8601 format)", "format": "date-time" }, "toDateTime": { "type": "string", "description": "End date and time for filtering scorecards (ISO 8601 format)", "format": "date-time" }, "scorecardsItemsUUIDs": { "type": "array", "items": { "type": "string" } }, "scorecardUUID": { "type": "string" }, "teamUUIDs": { "type": "array", "items": { "type": "string" } }, "userUUIDs": { "type": "array", "items": { "type": "string" } } }, "example": { "scorecardUUID": "sc-uuid-123", "fromDateTime": "2024-01-01T00:00:00Z", "toDateTime": "2024-03-31T23:59:59Z", "teamUUIDs": [ "team-uuid-1", "team-uuid-2" ], "userUUIDs": [ "user-uuid-1", "user-uuid-2" ], "scorecardsItemsUUIDs": [ "si-uuid-1", "si-uuid-2" ] } }, "ScorecardsSummaryItemAverage": { "required": [ "average", "scorecardItemUUID", "title" ], "type": "object", "properties": { "title": { "type": "string" }, "scorecardItemUUID": { "type": "string" }, "average": { "type": "number" }, "description": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "quote": { "type": "string" }, "start_sec": { "type": "number" }, "end_sec": { "type": "number" }, "link": { "type": "string", "description": "Deep link to the conversation at the evidence timestamp" } } }, "x-omitempty": true } }, "example": { "scorecardItemUUID": "si-uuid-123", "title": "Discovery Quality", "average": 87.5, "description": "Great opening with warm greeting", "evidence": [ { "quote": "Thank you for calling, how can I help you today?", "start_sec": 33, "end_sec": 45.5, "link": "https://app.attention.tech/conversations/all-calls/conv-uuid-123?videoStartTime=33&videoEndTime=45" } ] } }, "ScorecardsSummaryMetricItem": { "required": [ "date", "entityInfo", "itemAverages", "overallScore" ], "type": "object", "properties": { "overallScore": { "type": "number" }, "itemAverages": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardsSummaryItemAverage" } }, "date": { "type": "string", "format": "date-time" }, "entityInfo": { "required": [ "title", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" } } }, "conversationInfo": { "required": [ "startedAt", "teamUUID", "title", "userUUID", "uuid" ], "type": "object", "properties": { "teamUUID": { "type": "string" }, "userUUID": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "uuid": { "type": "string" }, "title": { "type": "string" } } } }, "example": { "date": "2024-03-15T10:30:00Z", "overallScore": 88, "entityInfo": { "uuid": "entity-uuid-123", "title": "Enterprise Deal Review" }, "conversationInfo": { "uuid": "conv-uuid-123", "title": "Q1 Pipeline Review", "teamUUID": "team-uuid-456", "userUUID": "user-uuid-789", "startedAt": "2024-03-15T10:00:00Z" }, "itemAverages": [ { "scorecardItemUUID": "si-uuid-1", "title": "Discovery Quality", "average": 90 } ] } }, "ScorecardsSummaryItem": { "required": [ "itemAverageTotals", "max", "metrics", "metricsCount", "min", "overallScoreTotals", "teamName", "userName" ], "type": "object", "properties": { "overallScoreTotals": { "type": "number" }, "min": { "type": "number" }, "userName": { "type": "string" }, "teamName": { "type": "string" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardsSummaryMetricItem" } }, "max": { "type": "number" }, "itemAverageTotals": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardsSummaryItemAverage" } }, "metricsCount": { "type": "number" } }, "example": { "userName": "Jane Smith", "teamName": "Sales Team", "overallScoreTotals": 85.5, "metricsCount": 12, "min": 65, "max": 98, "itemAverageTotals": [ { "scorecardItemUUID": "si-uuid-1", "title": "Discovery Quality", "average": 88 } ], "metrics": [ { "date": "2024-03-15T10:30:00Z", "overallScore": 88, "entityInfo": { "uuid": "entity-uuid-1", "title": "Pipeline Review" }, "itemAverages": [ { "scorecardItemUUID": "si-uuid-1", "title": "Discovery Quality", "average": 90 } ] } ] } }, "ScorecardsSummaryResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "type": "array", "description": "Array of resources matching the query", "items": { "$ref": "#/components/schemas/ScorecardsSummaryItem" } } }, "example": { "data": [ { "userName": "Jane Smith", "teamName": "Sales Team", "overallScoreTotals": 85.5, "metricsCount": 12, "min": 65, "max": 98, "itemAverageTotals": [ { "scorecardItemUUID": "si-uuid-1", "title": "Discovery Quality", "average": 88 } ], "metrics": [] } ] } }, "AskAttentionResponseV2": { "type": "array", "example": [ { "output": "Yes, this is an example of an 'Ask Attention' response", "conversation_id": "conv_uuid_1", "error": "", "segments": [ { "start_sec": 120.5, "end_sec": 135, "text": "Speaker A discusses pricing and discounts." } ] }, { "output": "Yes, this is another example of an 'Ask Attention' response", "conversation_id": "conv_uuid_2", "error": "", "segments": [ { "start_sec": 45, "end_sec": 62.5, "text": "Speaker B asks about the integration timeline." } ] } ], "items": { "required": [ "conversation_id", "error", "output" ], "type": "object", "properties": { "output": { "type": "string" }, "conversation_id": { "type": "string" }, "error": { "type": "string" }, "segments": { "type": "array", "description": "Optional timestamped segments relevant to the answer (present when include_timestamps=true).", "items": { "type": "object", "properties": { "start_sec": { "type": "number", "description": "Start time in seconds" }, "end_sec": { "type": "number", "description": "End time in seconds" }, "text": { "type": "string", "description": "Transcript excerpt for this segment" } } } }, "title": { "type": "string", "description": "Conversation title" } } } }, "AskAttentionRequestV2": { "required": [ "conversations_ids", "deal_id", "prompt" ], "type": "object", "properties": { "conversations_ids": { "type": "array", "items": { "maxLength": 50, "type": "string" } }, "deal_id": { "type": "string" }, "prompt": { "type": "string" } }, "example": { "conversations_ids": [], "deal_id": "conv_123", "prompt": "Customer mentioned budget constraints but showed interest in premium features" } }, "AskAttentionResponse": { "required": [ "conversations_used", "output" ], "type": "object", "properties": { "output": { "type": "string" }, "conversations_used": { "type": "array", "items": { "type": "string" } } }, "example": { "output": "Yes, this is an example of an 'Ask Attention' response", "conversations_used": [ "conv_uuid_1", "conv_uuid_2" ] } }, "AskAttentionRequest": { "required": [ "context_id", "context_type", "prompt" ], "type": "object", "properties": { "context_type": { "type": "string", "enum": [ "conversation", "deal" ] }, "context_id": { "type": "string" }, "prompt": { "type": "string" } }, "example": { "context_type": "conversation", "context_id": "conv_123", "prompt": "Customer mentioned budget constraints but showed interest in premium features" } }, "CreateDeckResponse": { "required": [ "emails_shared_with", "error", "link", "success" ], "type": "object", "properties": { "success": { "type": "boolean" }, "link": { "type": "string" }, "error": { "type": "string" }, "emails_shared_with": { "type": "array", "items": { "type": "string" } } }, "example": { "success": true, "link": "https://example.com/deck/123", "error": "", "emails_shared_with": [ "user1@example.com", "user2@example.com" ] } }, "CreateDeckRequest": { "required": [ "context_id", "users_to_share" ], "type": "object", "properties": { "users_to_share": { "type": "array", "items": { "type": "string" } }, "context_id": { "type": "string" }, "deck_type": { "type": "string" }, "slides": { "type": "integer" }, "structure": { "type": "array", "items": { "$ref": "#/components/schemas/OutlineItem" } }, "additional_instructions": { "type": "string" } }, "example": { "context_id": "deal_123", "users_to_share": [ "user1@example.com", "user2@example.com" ], "deck_type": "sales_presentation", "slides": 10, "structure": [ { "layout_instruction": "Use a two-column layout", "content_instruction": "Include key metrics and competitor analysis" } ], "additional_instructions": "Focus on enterprise features and ROI" } }, "OutlineItem": { "type": "object", "properties": { "layout_instruction": { "type": "string" }, "content_instruction": { "type": "string" } }, "example": { "layout_instruction": "Use a two-column layout", "content_instruction": "Include key metrics and competitor analysis" } }, "GIHistoryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GIHistory" } }, "links": { "$ref": "#/components/schemas/Links" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "example": { "data": [ { "uuid": "hist_123", "title": "Sales Team Analysis", "results": [ { "uuid": "res_456", "synthesis": "Team performance analysis for Q1", "prompt": "Analyze sales team performance", "status": "FINISHED", "items": [], "conversationsUsed": [ "conv_789" ], "emailsUsed": [ "email_123" ], "type": "TEXT_WITH_SOURCES", "result": {} } ] } ], "links": { "self": "https://api.attention.tech/v2/gi/history", "related": "https://api.attention.tech/v2/gi/history/related" }, "meta": { "pageCount": 1, "totalRecords": 1, "pageNumber": 1, "pageSize": 10 } } }, "GIHistory": { "required": [ "results", "title", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string" }, "user": { "type": "object", "properties": { "uuid": { "type": "string" } } }, "title": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/GIResult" } }, "executionTemplate": { "$ref": "#/components/schemas/GIExecutionTemplate" } }, "example": { "uuid": "hist_123", "user": { "uuid": "user_456" }, "title": "Sales Team Analysis", "results": [ { "uuid": "res_789", "synthesis": "Team performance analysis for Q1", "prompt": "Analyze sales team performance", "status": "FINISHED", "items": [], "conversationsUsed": [ "conv_123" ], "emailsUsed": [ "email_456" ], "type": "TEXT_WITH_SOURCES", "result": {} } ], "executionTemplate": { "uuid": "template_123", "prompt": "Analyze sales team performance", "period": "WEEKLY", "lastExecutionAt": "2024-03-20T10:00:00Z", "nextExecutionAt": "2024-03-27T10:00:00Z", "createdAt": "2024-03-13T10:00:00Z" } } }, "GIExecutionTemplate": { "required": [ "period", "prompt", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string" }, "history": { "$ref": "#/components/schemas/GIHistory" }, "filters": { "$ref": "#/components/schemas/GIExecutionTemplateFilters" }, "user": { "$ref": "#/components/schemas/User" }, "prompt": { "type": "string" }, "period": { "$ref": "#/components/schemas/GIExecutionTemplatePeriod" }, "lastExecutionAt": { "type": "string", "format": "date-time" }, "nextExecutionAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "example": { "uuid": "template_123", "prompt": "Analyze sales team performance", "period": "WEEKLY", "lastExecutionAt": "2024-03-20T10:00:00Z", "nextExecutionAt": "2024-03-27T10:00:00Z", "createdAt": "2024-03-13T10:00:00Z", "filters": { "teams": [ { "teamUUID": "team_123", "teamName": "Sales Team A" } ], "teamMembers": [ { "teamMemberUUID": "member_123", "teamMemberName": "John", "teamMemberLastName": "Doe", "teamMemberEmail": "john.doe@example.com" } ], "opportunities": [ { "opportunityUUID": "opp_123", "opportunityName": "Enterprise Deal" } ] } } }, "GIExecutionTemplatePeriod": { "type": "string", "example": "WEEKLY", "enum": [ "WEEKLY", "MONTHLY" ] }, "GIExecutionTemplateFilters": { "required": [ "opportunities", "teamMembers", "teams" ], "type": "object", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/GIFilterTeam" } }, "teamMembers": { "type": "array", "items": { "$ref": "#/components/schemas/GIFilterTeamMember" } }, "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/GIFilterOpportunities" } } }, "example": { "teams": [ { "teamUUID": "team_123", "teamName": "Sales Team A" } ], "teamMembers": [ { "teamMemberUUID": "member_123", "teamMemberName": "John", "teamMemberLastName": "Doe", "teamMemberEmail": "john.doe@example.com" } ], "opportunities": [ { "opportunityUUID": "opp_123", "opportunityName": "Enterprise Deal" } ] } }, "GIResult": { "required": [ "conversationsUsed", "emailsUsed", "items", "prompt", "result", "status", "synthesis", "type", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string" }, "synthesis": { "type": "string" }, "prompt": { "type": "string" }, "status": { "$ref": "#/components/schemas/GIStatus" }, "filtersUsed": { "$ref": "#/components/schemas/GIFilters" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/GIResultItem" } }, "conversationsUsed": { "type": "array", "items": { "type": "string" } }, "emailsUsed": { "type": "array", "items": { "type": "string" } }, "type": { "$ref": "#/components/schemas/GIResultType" }, "result": { "type": "object", "properties": {} } }, "example": { "uuid": "res_123", "synthesis": "Analysis of sales team performance shows strong growth in Q1", "prompt": "Analyze sales team performance", "status": "FINISHED", "filtersUsed": { "teams": [ { "teamUUID": "team_123", "teamName": "Sales Team A" } ], "teamMembers": [ { "teamMemberUUID": "member_123", "teamMemberName": "John", "teamMemberLastName": "Doe", "teamMemberEmail": "john.doe@example.com" } ], "opportunities": [ { "opportunityUUID": "opp_123", "opportunityName": "Enterprise Deal" } ], "conversations": [ { "conversationUUID": "conv_123", "conversationTitle": "Sales Review Meeting" } ], "isInternal": false, "labels": [ { "name": "priority", "values": [ "high" ] } ] }, "items": [ { "uuid": "item_123", "summary": "Sales team achieved 120% of Q1 target", "evidence": { "conversationsEvidence": [ { "type": "CONVERSATION", "conversationUUID": "conv_123", "conversationTitle": "Sales Review Meeting", "conversationQuotes": [ { "quote": "We've exceeded our Q1 targets by 20%", "reference": { "startIdx": "0", "endIdx": "100" } } ] } ] } } ], "conversationsUsed": [ "conv_123" ], "emailsUsed": [ "email_123" ], "type": "TEXT_WITH_SOURCES", "result": { "summary": "Strong Q1 performance with 20% growth" } } }, "GIResultItem": { "required": [ "summary", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string" }, "summary": { "type": "string" }, "evidence": { "$ref": "#/components/schemas/GIItemEvidence" } }, "example": { "uuid": "item_123", "summary": "Sales team achieved 120% of Q1 target", "evidence": { "conversationsEvidence": [ { "type": "CONVERSATION", "conversationUUID": "conv_123", "conversationTitle": "Sales Review Meeting", "conversationQuotes": [ { "quote": "We've exceeded our Q1 targets by 20%", "reference": { "startIdx": "0", "endIdx": "100" } } ] } ] } } }, "GIItemEvidence": { "required": [ "conversationsEvidence" ], "type": "object", "properties": { "conversationsEvidence": { "type": "array", "items": { "$ref": "#/components/schemas/GIConversationEvidence" } } }, "example": { "conversationsEvidence": [ { "type": "CONVERSATION", "conversationUUID": "conv_123", "conversationTitle": "Sales Review Meeting", "conversationQuotes": [ { "quote": "We've exceeded our Q1 targets by 20%", "reference": { "startIdx": "0", "endIdx": "100" } } ] } ] } }, "GIConversationEvidence": { "required": [ "conversationQuotes", "conversationTitle", "conversationUUID", "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/GIEvidenceType" }, "conversationUUID": { "type": "string" }, "conversationTitle": { "type": "string" }, "finishedAt": { "type": "string", "format": "date-time" }, "conversationQuotes": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationQuote" } } }, "example": { "type": "CONVERSATION", "conversationUUID": "conv_123", "conversationTitle": "Sales Review Meeting", "finishedAt": "2024-03-20T11:00:00Z", "conversationQuotes": [ { "quote": "We've exceeded our Q1 targets by 20%", "reference": { "startIdx": "0", "endIdx": "100" } } ] } }, "ConversationQuote": { "required": [ "quote" ], "type": "object", "properties": { "quote": { "type": "string" }, "reference": { "$ref": "#/components/schemas/Range" } }, "example": { "quote": "We've exceeded our Q1 targets by 20%", "reference": { "startIdx": "0", "endIdx": "100" } } }, "Range": { "required": [ "endIdx", "startIdx" ], "type": "object", "properties": { "startIdx": { "type": "string" }, "endIdx": { "type": "string" } }, "example": { "startIdx": "0", "endIdx": "100" } }, "GIEvidenceType": { "type": "string", "example": "CONVERSATION", "enum": [ "CONVERSATION" ] }, "GIResultType": { "type": "string", "example": "TEXT_WITH_SOURCES", "enum": [ "LIST", "TEXT_WITH_SOURCES", "SINGLE_QUOTE", "QUOTE_LIST", "SUMMARY_TABLE", "TABLE_QUOTES" ] }, "GIStatus": { "type": "string", "example": "FINISHED", "enum": [ "PENDING", "FINISHED" ] }, "GIFilters": { "required": [ "conversations", "labels", "opportunities", "teamMembers", "teams" ], "type": "object", "properties": { "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/GIFilterTeam" } }, "teamMembers": { "type": "array", "items": { "$ref": "#/components/schemas/GIFilterTeamMember" } }, "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/GIFilterOpportunities" } }, "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/GIFilterConversation" } }, "isInternal": { "type": "boolean" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/GILabelFilter" } } }, "example": { "startDate": "2024-03-01T00:00:00Z", "endDate": "2024-03-31T23:59:59Z", "teams": [ { "teamUUID": "team_123", "teamName": "Sales Team A" } ], "teamMembers": [ { "teamMemberUUID": "member_123", "teamMemberName": "John", "teamMemberLastName": "Doe", "teamMemberEmail": "john.doe@example.com" } ], "opportunities": [ { "opportunityUUID": "opp_123", "opportunityName": "Enterprise Deal" } ], "conversations": [ { "conversationUUID": "conv_123", "conversationTitle": "Sales Review Meeting" } ], "isInternal": false, "labels": [ { "name": "priority", "values": [ "high" ] } ] } }, "GILabelFilter": { "required": [ "name", "values" ], "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "example": { "name": "priority", "values": [ "high", "medium", "low" ] } }, "GIFilterConversation": { "required": [ "conversationTitle", "conversationUUID" ], "type": "object", "properties": { "conversationUUID": { "type": "string" }, "conversationTitle": { "type": "string" } }, "example": { "conversationUUID": "conv_123", "conversationTitle": "Sales Review Meeting" } }, "GIFilterOpportunities": { "required": [ "opportunityName", "opportunityUUID" ], "type": "object", "properties": { "opportunityUUID": { "type": "string" }, "opportunityName": { "type": "string" } }, "example": { "opportunityUUID": "opp_123", "opportunityName": "Enterprise Deal" } }, "GIFilterTeamMember": { "required": [ "teamMemberEmail", "teamMemberLastName", "teamMemberName", "teamMemberUUID" ], "type": "object", "properties": { "teamMemberUUID": { "type": "string" }, "teamMemberName": { "type": "string" }, "teamMemberLastName": { "type": "string" }, "teamMemberEmail": { "type": "string" } }, "example": { "teamMemberUUID": "member_123", "teamMemberName": "John", "teamMemberLastName": "Doe", "teamMemberEmail": "john.doe@example.com" } }, "GIFilterTeam": { "required": [ "teamName", "teamUUID" ], "type": "object", "properties": { "teamUUID": { "type": "string" }, "teamName": { "type": "string" } }, "example": { "teamUUID": "team_123", "teamName": "Sales Team A" } }, "NewLibraryItemInfo": { "required": [ "my_library" ], "type": "object", "properties": { "my_library": { "type": "boolean" }, "folder_path": { "type": "string" } }, "example": { "my_library": true, "folder_path": "/sales/meetings" } }, "NewVideoTimespan": { "required": [ "end_time", "start_time" ], "type": "object", "properties": { "start_time": { "type": "number" }, "end_time": { "type": "number" }, "duration": { "type": "number" } }, "example": { "start_time": 120.5, "end_time": 180.75, "duration": 60.25 } }, "NewRange": { "required": [ "end_idx", "start_idx" ], "type": "object", "properties": { "start_idx": { "type": "string" }, "end_idx": { "type": "string" } }, "example": { "start_idx": "0", "end_idx": "100" } }, "NewSnippetReference": { "required": [ "characters", "speakers", "transcript_version" ], "type": "object", "properties": { "characters": { "$ref": "#/components/schemas/NewRange" }, "speakers": { "$ref": "#/components/schemas/NewRange" }, "transcript_version": { "type": "string", "enum": [ "V1", "V2" ] } }, "example": { "characters": { "start_idx": "0", "end_idx": "150" }, "speakers": { "start_idx": "0", "end_idx": "50" }, "transcript_version": "V2" } }, "CreatedSnippetResponse": { "required": [ "id", "url" ], "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "share_code": { "type": "string" } }, "example": { "id": "snp-uuid-789", "url": "https://app.attention.tech/snippets/snp-uuid-789", "share_code": "abc123def" } }, "CreateSnippetRequest": { "required": [ "conversation_id", "internal", "notify_views", "user_uuid", "video" ], "type": "object", "properties": { "user_uuid": { "type": "string" }, "conversation_id": { "type": "string" }, "reference": { "$ref": "#/components/schemas/NewSnippetReference" }, "video": { "$ref": "#/components/schemas/NewVideoTimespan" }, "notes": { "type": "string" }, "title": { "type": "string" }, "in_library": { "type": "boolean", "description": "Indicates whether the snippet should be added to the library or not" }, "library_item_info": { "$ref": "#/components/schemas/NewLibraryItemInfo" }, "internal": { "type": "boolean" }, "notify_views": { "type": "boolean" } }, "example": { "user_uuid": "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6", "conversation_id": "conv-uuid-123", "internal": false, "notify_views": true, "title": "Key Discovery Moment", "notes": "Customer mentioned budget constraints", "in_library": true, "video": { "start_time": 120.5, "end_time": 180, "duration": 59.5 }, "reference": { "characters": { "start_idx": "100", "end_idx": "250" }, "speakers": { "start_idx": "2", "end_idx": "5" }, "transcript_version": "V1" } } }, "createScorecardResultRequest": { "required": [ "items", "scorecard_uuid", "summary" ], "type": "object", "properties": { "scorecard_uuid": { "type": "string" }, "conversation_uuid": { "type": "string" }, "chat_uuid": { "type": "string" }, "summary": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardResultItemRequest" } } }, "example": { "scorecard_uuid": "sc-uuid-123", "summary": "Excellent discovery process, identified 3 key pain points", "conversation_uuid": "conv-uuid-789", "items": [ { "scorecard_item_uuid": "si-uuid-1", "numeric_result": 95, "description": "Outstanding listening skills" }, { "scorecard_item_uuid": "si-uuid-2", "numeric_result": 85, "description": "Good closing technique" } ] } }, "changeConversationOpportunityRequest": { "required": [ "conversation_id" ], "type": "object", "properties": { "conversation_id": { "type": "string", "description": "UUID of the conversation to update", "example": "conv_abc123" }, "opportunity_id": { "type": "string", "description": "UUID of the opportunity to link. Required when linking or updating an opportunity.", "example": "opp_xyz789" }, "entity_code": { "type": "string", "description": "CRM entity code for the opportunity (e.g., 'salesforce', 'hubspot')", "example": "salesforce" }, "skip_intelligence_calculation": { "type": "boolean", "description": "When true, skips recalculating CRM intelligence fields after the opportunity change. Defaults to false.", "default": false }, "remove_opportunity": { "type": "boolean", "description": "When true, removes the current opportunity from the conversation instead of linking one. Defaults to false.", "default": false } }, "example": { "conversation_id": "conv-uuid-123", "opportunity_id": "opp-uuid-456", "remove_opportunity": false, "skip_intelligence_calculation": false } }, "ScorecardResultItemRequest": { "required": [ "description", "scorecard_item_uuid" ], "type": "object", "properties": { "scorecard_item_uuid": { "type": "string" }, "numeric_result": { "type": "integer" }, "description": { "type": "string" } }, "example": { "scorecard_item_uuid": "si-uuid-123", "numeric_result": 90, "description": "Demonstrated strong objection handling" } }, "createScorecardResultResponse": { "required": [ "success" ], "type": "object", "properties": { "success": { "type": "boolean" } }, "example": { "success": true } }, "changeConversationOpportunityResponse": { "required": [ "success" ], "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the opportunity was changed successfully" } }, "example": { "success": true } }, "ListUsersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "links": { "$ref": "#/components/schemas/Links" } }, "example": { "data": [ { "botName": "Karen's Notetaker", "email": "karen@attention.tech", "firstName": "Karen", "lastName": "Doe", "primaryTeamUUID": "4b56088c-110d-486b-b4f9-f1d6eb1927cf", "roles": [ { "name": "Admin", "type": "ADMIN", "uuid": "84e67f54-5157-442b-a2b3-8b9c728b2fef" }, { "name": "Sales Representative", "type": "SALES_REP", "uuid": "e28b72c8-a4f4-446c-92d9-2483acab3c71" } ], "settings": { "joinWhenIAmHostAndAlone": true, "joinWhenIAmHostWithPeers": true, "realTimeCapabilitiesOFF": true }, "teams": [ { "children": [], "domain": "attention.tech", "name": "teamA5", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "parentTeamUUID": "38dd31c6-8fc3-45ed-acc0-86567f13d296", "uuid": "4b56088c-110d-486b-b4f9-f1d6eb1927cf" }, { "children": [], "domain": "attention.tech", "name": "A3", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "parentTeamUUID": "2ccf9bde-68e3-4de4-bc4e-51b927336665", "uuid": "d350b24c-70bc-424e-9ae6-06afdba616fc" }, { "children": [], "domain": "Wrapbook.com", "name": "de wrapbook", "organizationUUID": "43c2c551-279c-4a2a-a84f-b43f06328e8b", "uuid": "24c426ca-9a14-4c84-8225-5a02e253f505" } ], "transcriptLang": "en", "uuid": "ccef8743-8f86-416b-9c62-a7eaa026f31d" }, { "botName": "test's Notetaker", "email": "test@attention.tech", "firstName": "Jhon", "joinOutsideHostMeetings": true, "lastName": "Doe", "primaryTeamUUID": "4b56088c-110d-486b-b4f9-f1d6eb1927cf", "roles": [ { "name": "Sales Representative", "type": "SALES_REP", "uuid": "e28b72c8-a4f4-446c-92d9-2483acab3c71" } ], "settings": { "joinWhenIAmHostAndAlone": true, "joinWhenIAmHostWithPeers": true, "realTimeCapabilitiesOFF": true }, "teams": [ { "children": [], "domain": "attention.tech", "name": "A3", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "parentTeamUUID": "2ccf9bde-68e3-4de4-bc4e-51b927336665", "uuid": "d350b24c-70bc-424e-9ae6-06afdba616fc" }, { "children": [], "domain": "Wrapbook.com", "name": "de wrapbook", "organizationUUID": "43c2c551-279c-4a2a-a84f-b43f06328e8b", "uuid": "24c426ca-9a14-4c84-8225-5a02e253f505" } ], "transcriptLang": "en", "uuid": "8e288333-f634-4659-a57a-251bb4f51726" } ] } }, "Email": { "required": [ "bodyUrl", "ccRecipients", "isInternalUser", "messageId", "recipients", "sendDate", "sender", "snippet", "subject", "threadId" ], "type": "object", "properties": { "messageId": { "type": "string", "description": "The unique identifier of the email message.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "threadId": { "type": "string", "description": "The unique identifier of the email thread or conversation.", "example": "thread_789f0123-g45h-67i8-j901-234567890123" }, "sendDate": { "type": "string", "description": "The date and time when the email was sent.", "format": "date-time", "example": "2024-03-15T14:30:00Z" }, "sender": { "type": "string", "description": "The email address of the sender.", "example": "john.doe@company.com" }, "recipients": { "type": "array", "description": "List of primary recipient email addresses.", "example": [ "jane.smith@company.com", "bob.johnson@company.com" ], "items": { "type": "string" } }, "ccRecipients": { "type": "array", "description": "List of CC (carbon copy) recipient email addresses.", "example": [ "manager@company.com", "team@company.com" ], "items": { "type": "string" } }, "subject": { "type": "string", "description": "The subject line of the email.", "example": "Project Update - Q1 2024 Report" }, "snippet": { "type": "string", "description": "A brief preview or excerpt of the email body content.", "example": "Hi team, I wanted to share the latest updates on our Q1 project..." }, "bodyUrl": { "type": "string", "description": "URL endpoint to retrieve the full email body content.", "example": "https://api.company.com/emails/123e4567-e89b-12d3-a456-426614174000/body" }, "isInternalUser": { "type": "boolean", "description": "Indicates whether the sender is an internal user within the organization.", "example": true } }, "example": { "messageId": "123e4567-e89b-12d3-a456-426614174000", "threadId": "thread_789f0123-g45h-67i8-j901-234567890123", "sendDate": "2024-03-15T14:30:00Z", "sender": "john.doe@company.com", "recipients": [ "jane.smith@company.com", "bob.johnson@company.com" ], "ccRecipients": [ "manager@company.com", "team@company.com" ], "subject": "Project Update - Q1 2024 Report", "snippet": "Hi team, I wanted to share the latest updates on our Q1 project...", "bodyUrl": "https://api.company.com/emails/123e4567-e89b-12d3-a456-426614174000/body", "isInternalUser": true } }, "ListEmailsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "example": { "data": [ { "messageId": "123e4567-e89b-12d3-a456-426614174000", "threadId": "thread_789f0123-g45h-67i8-j901-234567890123", "sendDate": "2024-03-15T14:30:00Z", "sender": "john.doe@company.com", "recipients": [ "jane.smith@company.com", "bob.johnson@company.com" ], "ccRecipients": [ "manager@company.com", "team@company.com" ], "subject": "Project Update - Q1 2024 Report", "snippet": "Hi team, I wanted to share the latest updates on our Q1 project...", "bodyUrl": "https://api.company.com/emails/123e4567-e89b-12d3-a456-426614174000/body", "isInternalUser": false } ], "meta": { "pageCount": 5, "totalRecords": 100, "pageNumber": 1, "pageSize": 20 } } }, "Error": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the error." }, "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string value." }, "code": { "type": "string", "description": "An application-specific error code, expressed as a string value." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } }, "meta": { "type": "object", "properties": {} } }, "example": { "id": "not_found_error", "status": "404", "code": "404", "title": "Not Found Error", "detail": "The requested resource was not found", "source": { "pointer": "/data/attributes/id" } } }, "BaseError": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } }, "example": { "code": "unauthorized", "message": "Invalid or expired API key" } }, "ChatParticipant": { "type": "object", "properties": { "externalId": { "type": "string", "description": "External identifier of the participant" }, "name": { "type": "string", "description": "Display name of the participant" }, "email": { "type": "string", "description": "Email address of the participant" }, "participantType": { "type": "string", "description": "Type of participant", "enum": [ "prospect", "user", "bot" ] }, "userUuid": { "type": "string", "description": "UUID of the associated user (if applicable)" } }, "example": { "externalId": "slack-user-123", "name": "Jane Smith", "email": "jane@example.com", "participantType": "user", "userUuid": "user-uuid-456" } }, "ChatTranscriptItem": { "type": "object", "properties": { "sentence": { "type": "string", "description": "The text content of the transcript entry" }, "author": { "type": "string", "description": "Name of the author" }, "authorEmail": { "type": "string", "description": "Email address of the author" }, "datetime": { "type": "string", "description": "Timestamp of the transcript entry", "format": "date-time" } }, "example": { "author": "Jane Smith", "authorEmail": "jane@example.com", "sentence": "Let's discuss the Q1 targets.", "datetime": "2024-03-18T09:05:00Z" } }, "Chat": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the chat" }, "externalId": { "type": "string", "description": "External identifier from the source system" }, "applicationName": { "type": "string", "description": "Name of the application that created the chat" }, "title": { "type": "string", "description": "Title of the chat" }, "type": { "type": "string", "description": "Type of chat (chat or email)", "enum": [ "chat", "email" ] }, "userId": { "type": "string", "description": "UUID of the user who owns the chat" }, "teamId": { "type": "string", "description": "UUID of the team the chat belongs to" }, "participants": { "type": "array", "description": "List of chat participants", "items": { "$ref": "#/components/schemas/ChatParticipant" } }, "transcript": { "type": "array", "description": "Chat transcript entries (omitted when exclude_transcript=true)", "items": { "$ref": "#/components/schemas/ChatTranscriptItem" } }, "dateStart": { "type": "string", "description": "When the chat started", "format": "date-time" }, "createdAt": { "type": "string", "description": "When the chat record was created", "format": "date-time" } }, "example": { "id": "chat-uuid-123", "externalId": "slack-channel-xyz", "applicationName": "slack", "title": "Sales Q1 Planning", "type": "chat", "userId": "user-uuid-456", "teamId": "team-uuid-789", "dateStart": "2024-03-18T09:00:00Z", "createdAt": "2024-03-18T09:00:00Z", "participants": [ { "externalId": "slack-user-1", "name": "Jane Smith", "email": "jane@example.com", "participantType": "user", "userUuid": "user-uuid-456" } ], "transcript": [ { "author": "Jane Smith", "authorEmail": "jane@example.com", "sentence": "Let's discuss our targets.", "datetime": "2024-03-18T09:05:00Z" } ] } }, "ListChatsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Chat" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "example": { "data": [ { "id": "chat-uuid-123", "externalId": "slack-channel-xyz", "applicationName": "slack", "title": "Sales Q1 Planning", "type": "chat", "userId": "user-uuid-456", "teamId": "team-uuid-789", "dateStart": "2024-03-18T09:00:00Z", "createdAt": "2024-03-18T09:00:00Z", "participants": [], "transcript": [] } ], "meta": { "totalRecords": 1 } } }, "ConversationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "links": { "$ref": "#/components/schemas/Links" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "example": { "data": [], "links": { "self": "/v2/conversations?page=1", "related": "/v2/conversations?page=2" }, "meta": { "totalRecords": 150 } } }, "Conversation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "conversations" ] }, "id": { "type": "string" }, "attributes": { "required": [ "dealUUID", "externalIntelligenceOpportunityID", "externalOpportunity", "importMetadata", "zoomMetadata" ], "type": "object", "properties": { "uuid": { "type": "string" }, "transcript": { "type": "object", "additionalProperties": true }, "boards": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationBoard" } }, "finishedAt": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "liveStreamStartedAt": { "type": "string", "format": "date-time" }, "liveStreamEndedAt": { "type": "string", "format": "date-time" }, "talktracks": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationTalktrack" } }, "createdAt": { "type": "string", "format": "date-time" }, "userUUID": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" }, "team": { "$ref": "#/components/schemas/Team" }, "teamUUID": { "type": "string" }, "extractedIntelligence": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ExtractedIntelligenceItem" } }, "confirmedExtractedIntelligence": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ExtractedIntelligenceItem" } }, "externalIntelligenceOpportunityID": { "type": "string" }, "crmExportStatus": { "$ref": "#/components/schemas/CrmExportStatus" }, "archived": { "type": "boolean" }, "externalOpportunity": { "$ref": "#/components/schemas/CRMExportOpportunity" }, "videoUID": { "type": "string" }, "videoStatus": { "$ref": "#/components/schemas/VideoStatus" }, "bots": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationBot" } }, "transcriptStatus": { "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "referenceable": { "type": "boolean" }, "private": { "type": "boolean" }, "mediaStorageStatus": { "$ref": "#/components/schemas/VideoStatus" }, "importStatus": { "$ref": "#/components/schemas/ConversationImportStatus" }, "scorecardResults": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardResult" } }, "labels": { "type": "object", "additionalProperties": true }, "labelTagsToFilterIfNA": { "type": "array", "items": { "type": "string" } }, "deprecatedLabelCategories": { "type": "array", "items": { "type": "string" } }, "isInternal": { "type": "boolean" }, "mediaDuration": { "type": "number", "format": "float" }, "dealUUID": { "type": "string" }, "emailTemplateID": { "type": "string" }, "linkedCrmRecords": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedCrmRecord" } }, "externalAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedCrmRecord" } }, "externalContacts": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedCrmRecord" } }, "isEmpty": { "type": "boolean" }, "zoomMetadata": { "$ref": "#/components/schemas/ZoomMetadata" }, "importMetadata": { "type": "object", "additionalProperties": true }, "zoomMeetingJoinUrl": { "type": "string", "description": "The Zoom meeting join URL if the conversation was recorded from a Zoom meeting" }, "googleMeetJoinUrl": { "type": "string", "description": "The Google Meet join URL if the conversation was recorded from a Google Meet" }, "microsoftTeamsJoinUrl": { "type": "string", "description": "The Microsoft Teams meeting join URL if the conversation was recorded from a Teams meeting" }, "webexJoinUrl": { "type": "string", "description": "The Webex meeting join URL if the conversation was recorded from a Webex meeting" } } }, "links": { "$ref": "#/components/schemas/Links" } }, "example": { "type": "conversations", "id": "conv-uuid-123", "attributes": { "uuid": "conv-uuid-123", "title": "Q1 Deal Review - Acme Corp", "createdAt": "2024-03-18T10:00:00Z", "finishedAt": "2024-03-18T10:45:00Z", "liveStreamStartedAt": "2024-03-18T10:00:00Z", "liveStreamEndedAt": "2024-03-18T10:45:00Z", "userUUID": "user-uuid-456", "teamUUID": "team-uuid-789", "archived": false, "referenceable": true, "private": false, "isInternal": false, "isEmpty": false, "mediaDuration": 2700, "videoUID": "vid-uid-abc", "videoStatus": "ready", "mediaStorageStatus": "ready", "transcriptStatus": "completed", "crmExportStatus": "exported", "importStatus": "completed", "dealUUID": "deal-uuid-xyz", "emailTemplateID": "", "externalIntelligenceOpportunityID": "opp-ext-123", "zoomMeetingJoinUrl": "", "googleMeetJoinUrl": "", "microsoftTeamsJoinUrl": "", "webexJoinUrl": "", "transcript": {}, "participants": [ { "id": "part-uuid-1", "email": "jane@example.com", "name": "Jane Smith", "organizer": true, "status": "accepted" }, { "id": "part-uuid-2", "email": "john@customer.com", "name": "John Doe", "organizer": false, "status": "accepted" } ], "attendees": [ { "id": "part-uuid-1", "email": "jane@example.com", "name": "Jane Smith", "organizer": true, "status": "accepted" } ], "bots": [ { "uuid": "bot-uuid-1", "meetingUrl": "https://zoom.us/j/1234567890", "status": { "code": "completed", "message": "Recording uploaded", "createdAt": "2024-03-18T10:50:00Z" } } ], "boards": [ { "uuid": "cb-uuid-1", "board": { "uuid": "board-uuid-1", "name": "Sales Playbook", "teamUUID": "team-uuid-789", "columns": [] }, "battlecards": [] } ], "talktracks": [ { "uuid": "ct-uuid-1", "items": [ { "uuid": "cti-uuid-1", "activatedItemId": "item-uuid-1", "done": true } ] } ], "scorecardResults": [ { "uuid": "sr-uuid-1", "title": "Sales Discovery Scorecard", "items": [], "summary": { "averageScore": 85, "min": 0, "max": 100, "summaryText": "Good performance" } } ], "externalOpportunity": { "uuid": "opp-uuid-456", "title": "Enterprise Deal - Acme Corp" }, "importMetadata": {}, "linkedCrmRecords": [ { "id": "001ABC123", "code": "Account" } ], "externalAccounts": [ { "id": "001ACC456", "code": "Account" } ], "externalContacts": [ { "id": "003CON789", "code": "Contact" } ], "extractedIntelligence": {}, "confirmedExtractedIntelligence": {}, "labels": {}, "labelTagsToFilterIfNA": [], "deprecatedLabelCategories": [] }, "links": { "self": "/v2/conversations/conv-uuid-123" } } }, "DetailedTranscript": { "type": "array", "example": [ { "speaker": { "name": "Jane Smith", "email": "jane@example.com", "type": "internal" }, "words": [ { "text": "Hello", "startTimestamp": 0.5, "endTimestamp": 1 }, { "text": "everyone", "startTimestamp": 1.1, "endTimestamp": 1.5 } ] }, { "speaker": { "name": "John Doe", "email": "john@customer.com", "type": "external" }, "words": [ { "text": "Hi", "startTimestamp": 2, "endTimestamp": 2.3 }, { "text": "there", "startTimestamp": 2.4, "endTimestamp": 2.7 } ] } ], "items": { "type": "object", "properties": { "speaker": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "type": { "type": "string", "enum": [ "internal", "external" ] } } }, "words": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "startTimestamp": { "type": "number" }, "endTimestamp": { "type": "number" } } } } } } }, "SimpleTranscript": { "type": "string", "example": "Jane Smith: Let's review the quarterly numbers.\nJohn Doe: Sure, I have the report ready." }, "ConversationBoard": { "type": "object", "properties": { "uuid": { "type": "string" }, "board": { "$ref": "#/components/schemas/Board" }, "battlecards": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationBoardBattlecard" } } }, "example": { "uuid": "cb-uuid-123", "board": { "uuid": "board-uuid-456", "name": "Sales Playbook", "teamUUID": "team-uuid-789", "columns": [] }, "battlecards": [ { "uuid": "cbb-uuid-1", "activatedBattlecardID": "bc-uuid-1", "feedbackAction": "helpful", "hidden": false } ] } }, "ConversationTalktrack": { "type": "object", "properties": { "uuid": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationTalktrackItem" } } }, "example": { "uuid": "ct-uuid-123", "items": [ { "uuid": "cti-uuid-1", "activatedItemId": "item-uuid-456", "done": true } ] } }, "ConversationTalktrackItem": { "type": "object", "properties": { "uuid": { "type": "string" }, "activatedItemId": { "type": "string" }, "done": { "type": "boolean" } }, "example": { "uuid": "cti-uuid-1", "activatedItemId": "item-uuid-456", "done": true } }, "User": { "type": "object", "properties": { "uuid": { "type": "string", "description": "The unique identifier of the user.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "email": { "type": "string", "description": "The email address of the user.", "example": "user@example.com" }, "firstName": { "type": "string", "description": "The first name of the user.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the user.", "example": "Doe" }, "createdAt": { "type": "string", "description": "The date and time the user was created.", "example": "2021-01-01T00:00:00Z" }, "deletedAt": { "type": "string", "description": "The date and time the user was deactivated.", "example": "2021-01-01T00:00:00Z" }, "transcriptLang": { "type": "string", "description": "The preferred transcript language for the user.", "example": "en-US" }, "joinOutsideHostMeetings": { "type": "boolean", "description": "Indicates if the user can join meetings outside their host organization.", "example": true }, "realTimeCapabilities": { "type": "boolean", "description": "Indicates if the user has real-time transcription capabilities.", "example": false }, "settings": { "$ref": "#/components/schemas/UserSettings" }, "botName": { "type": "string", "description": "The name of the bot associated with the user.", "example": "MyBot" }, "botImageURL": { "type": "string", "description": "The URL of the bot's profile image.", "example": "https://example.com/bot.png" }, "primaryTeamUUID": { "type": "string", "description": "The UUID of the user's primary team.", "example": "primary-team-uuid-12345" }, "organizationRoleUUID": { "type": "string", "description": "The UUID of the user's role in the organization.", "example": "org-role-uuid-56789" }, "roles": { "type": "array", "description": "A list of roles assigned to the user.", "items": { "$ref": "#/components/schemas/Role" } }, "showReferralScreen": { "type": "boolean", "description": "Whether the user is shown a referral screen.", "example": false }, "seatType": { "type": "string", "description": "The type of seat assigned to the user.", "example": "admin" }, "teams": { "type": "array", "description": "A list of teams assigned to the user.", "items": { "$ref": "#/components/schemas/Team" } } }, "example": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "email": "user@example.com", "firstName": "John", "lastName": "Doe", "createdAt": "2021-01-01T00:00:00Z", "transcriptLang": "en-US", "joinOutsideHostMeetings": true, "realTimeCapabilities": false, "botName": "MyBot", "botImageURL": "https://example.com/bot.png", "primaryTeamUUID": "primary-team-uuid-12345", "organizationRoleUUID": "org-role-uuid-56789", "showReferralScreen": false, "seatType": "admin" } }, "UserSettings": { "type": "object", "properties": { "realTimeCapabilitiesOFF": { "type": "boolean" }, "autoCalculateCRMFields": { "type": "boolean" }, "joinWhenIAmHostAndAlone": { "type": "boolean" }, "joinWhenIAmHostWithPeers": { "type": "boolean" }, "joinWhenPeerIsHost": { "type": "boolean" }, "joinWhenUnlicensedPeerIsHost": { "type": "boolean" }, "dealsEnabled": { "type": "boolean" } }, "example": { "realTimeCapabilitiesOFF": true, "autoCalculateCRMFields": true, "joinWhenIAmHostAndAlone": true, "joinWhenIAmHostWithPeers": true, "joinWhenPeerIsHost": true, "joinWhenUnlicensedPeerIsHost": true, "dealsEnabled": true } }, "Team": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the team", "example": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" }, "name": { "type": "string", "description": "Name of the team", "example": "Engineering" }, "phrases": { "type": "array", "description": "List of keywords or phrases associated with the team", "example": [ "engineering", "tech", "development" ], "items": { "type": "string" } }, "slackConnection": { "$ref": "#/components/schemas/SlackConnection" }, "domain": { "type": "string", "description": "Domain associated with the team", "example": "attention.tech" }, "organizerJoinInternalMeetings": { "type": "boolean", "description": "Whether team organizers can join internal meetings", "example": true }, "consentEmailEnabled": { "type": "boolean", "description": "Whether email consent is enabled for the team", "example": true }, "parentTeamUUID": { "type": "string", "description": "UUID of the parent team if this team is part of a hierarchy", "example": "2ccf9bde-68e3-4de4-bc4e-51b927336665" }, "organizationUUID": { "type": "string", "description": "UUID of the organization this team belongs to", "example": "16b78cec-82ef-46d2-8213-5d3bb7d2571c" }, "children": { "type": "array", "description": "List of child teams if this team has a hierarchical structure", "items": { "$ref": "#/components/schemas/Team" } } }, "description": "Represents a team in the system with its properties and hierarchical structure", "example": { "uuid": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "name": "Engineering", "phrases": [ "engineering", "tech", "development" ], "domain": "attention.tech", "organizerJoinInternalMeetings": true, "consentEmailEnabled": true, "parentTeamUUID": "2ccf9bde-68e3-4de4-bc4e-51b927336665", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c" } }, "TeamResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "List of teams", "items": { "$ref": "#/components/schemas/Team" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "description": "Response containing a list of teams and metadata", "example": { "data": [ { "uuid": "team-uuid-123", "name": "Sales Team", "domain": "sales.example.com", "organizationUUID": "org-uuid-456", "phrases": [ "revenue", "deal" ], "consentEmailEnabled": true, "organizerJoinInternalMeetings": false } ], "meta": { "totalRecords": 1 } } }, "TeamMemberResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "List of team members", "items": { "$ref": "#/components/schemas/TeamMember" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "description": "Response containing a list of team members and metadata", "example": { "data": [ { "teamUUID": "team-uuid-123", "userUUID": "user-uuid-456", "team": { "uuid": "team-uuid-123", "name": "Sales Team" }, "user": { "uuid": "user-uuid-456", "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com" } } ], "meta": { "totalRecords": 1 } } }, "SlackConnection": { "type": "object", "properties": { "id": { "type": "string", "description": "Slack connection identifier", "example": "T1234567890" }, "info": { "$ref": "#/components/schemas/SlackTeamInfo" } }, "description": "Represents the Slack integration details for a team", "example": { "id": "T1234567890", "info": { "id": "T01234567", "name": "Acme Corp" } } }, "SlackTeamInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "Slack team identifier", "example": "T1234567890" }, "name": { "type": "string", "description": "Name of the Slack team", "example": "Attention Tech" } }, "description": "Information about a connected Slack team", "example": { "id": "T01234567", "name": "Acme Corp" } }, "TeamMember": { "type": "object", "properties": { "userUUID": { "type": "string", "description": "Unique identifier of the user", "example": "c74eb7bc-7b0e-45e2-843a-67305bfc4dce" }, "teamUUID": { "type": "string", "description": "Unique identifier of the team", "example": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" }, "user": { "$ref": "#/components/schemas/User" }, "team": { "$ref": "#/components/schemas/Team" } }, "description": "Represents a member of a team with their associated user information", "example": { "teamUUID": "team-uuid-123", "userUUID": "user-uuid-456", "team": { "uuid": "team-uuid-123", "name": "Sales Team" }, "user": { "uuid": "user-uuid-456", "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com" } } }, "ExtractedIntelligenceItem": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "refreshing": { "type": "boolean" }, "options": { "$ref": "#/components/schemas/IntelligenceItemOptionalValues" }, "source": { "type": "string" }, "scope_insight": { "type": "string" } }, "example": { "id": "intel_123", "key": "budget", "value": "50000", "title": "Budget Range", "category": "financial", "refreshing": false, "options": { "values": [ "30000", "50000", "100000" ], "maxValues": 1 }, "source": "conversation", "scope_insight": "Customer mentioned budget range of $50,000" } }, "CrmExportStatus": { "type": "string", "example": "PENDING", "enum": [ "PENDING", "EXPORTED", "DISMISSED" ] }, "CRMExportOpportunity": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" } }, "example": { "uuid": "opp-uuid-456", "title": "Enterprise Deal - Acme Corp" } }, "ZoomMetadata": { "required": [ "calleeName", "calleeNumber", "callerName", "callerNumber" ], "type": "object", "properties": { "calleeName": { "type": "string" }, "calleeNumber": { "type": "string" }, "callerName": { "type": "string" }, "callerNumber": { "type": "string" } }, "example": { "callerName": "Jane Smith", "callerNumber": "+14155551234", "calleeName": "John Doe", "calleeNumber": "+14155555678" } }, "VideoStatus": { "type": "string", "example": "PENDING", "enum": [ "PENDING", "UNAVAILABLE", "IMPORTING", "READY" ] }, "LinkedCrmRecord": { "required": [ "code", "id" ], "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" } }, "example": { "id": "001ABC123", "code": "Account" } }, "ConversationBot": { "type": "object", "properties": { "uuid": { "type": "string" }, "status": { "$ref": "#/components/schemas/BotStatus" }, "meetingUrl": { "type": "string", "description": "The original meeting URL used to invite the bot" } }, "example": { "uuid": "bot-uuid-123", "meetingUrl": "https://zoom.us/j/1234567890", "status": { "code": "completed", "message": "Recording uploaded successfully", "createdAt": "2024-03-18T14:30:00Z" } } }, "Participant": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "organizer": { "type": "boolean" }, "name": { "type": "string" }, "status": { "type": "string" } }, "example": { "id": "part-uuid-123", "email": "john@customer.com", "name": "John Smith", "organizer": true, "status": "accepted" } }, "ConversationImportStatus": { "type": "string", "example": "NONE", "enum": [ "NONE", "PENDING", "IN_PROGRESS", "FINISHED", "DISCARDED", "FAILED" ] }, "ScorecardResult": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" }, "summary": { "$ref": "#/components/schemas/ScorecardResultSummary" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScorecardItemResult" } } }, "example": { "uuid": "sr-uuid-123", "title": "Sales Discovery Scorecard", "items": [ { "uuid": "sir-uuid-1", "scorecardItemUUID": "si-uuid-1", "title": "Discovery Quality", "description": "Strong questioning", "status": "completed", "type": "numeric", "position": 1, "numericResult": { "score": 90, "min": 0, "max": 100 }, "evidences": [ "Asked about budget" ] } ], "summary": { "averageScore": 87.5, "min": 0, "max": 100, "summaryText": "Above average performance" } } }, "ScorecardItemResult": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/ScorecardItemResultStatus" }, "type": { "$ref": "#/components/schemas/ScorecardType" }, "position": { "type": "integer" }, "numericResult": { "$ref": "#/components/schemas/NumericScorecardResult" }, "description": { "type": "string" }, "evidences": { "type": "array", "items": { "type": "string" } }, "scorecardItemUUID": { "type": "string" } }, "example": { "uuid": "sir-uuid-123", "scorecardItemUUID": "si-uuid-456", "title": "Discovery Quality", "description": "Strong questioning technique", "status": "completed", "type": "numeric", "position": 1, "numericResult": { "score": 90, "min": 0, "max": 100 }, "evidences": [ "Asked about budget timeline", "Identified key stakeholders" ] } }, "NumericScorecardResult": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "score": { "type": "integer" } }, "example": { "score": 85, "min": 0, "max": 100 } }, "ScorecardType": { "type": "string", "example": "NUMERIC", "enum": [ "NUMERIC" ] }, "ScorecardItemResultStatus": { "type": "string", "example": "CALCULATED", "enum": [ "CALCULATED", "CALCULATING" ] }, "ScorecardResultSummary": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "averageScore": { "type": "number", "format": "float" }, "summaryText": { "type": "string" } }, "example": { "averageScore": 82.5, "min": 0, "max": 100, "summaryText": "Strong performance across all categories" } }, "Board": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/Column" } }, "team": { "$ref": "#/components/schemas/Team" }, "teamUUID": { "type": "string" } }, "example": { "uuid": "board-uuid-123", "name": "Sales Playbook", "teamUUID": "team-uuid-456", "columns": [ { "id": "col-uuid-1", "title": "Discovery", "children": [ { "uuid": "bc-uuid-1", "text": "Budget questions", "response": "Ask about budget range", "keywords": [ "budget" ] } ] } ] } }, "Column": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/Battlecard" } } }, "example": { "id": "col-uuid-123", "title": "Discovery", "children": [ { "uuid": "bc-uuid-1", "text": "Budget questions", "response": "Ask about allocated budget range", "keywords": [ "budget", "spend" ] } ] } }, "Battlecard": { "type": "object", "properties": { "uuid": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "response": { "type": "string" }, "text": { "type": "string" } }, "example": { "uuid": "bc-uuid-123", "text": "Competitor mentions lower pricing", "response": "Emphasize our ROI advantage and total cost of ownership", "keywords": [ "pricing", "competitor", "cost" ] } }, "ConversationBoardBattlecard": { "type": "object", "properties": { "uuid": { "type": "string" }, "activatedBattlecardID": { "type": "string" }, "hidden": { "type": "boolean" }, "feedbackAction": { "type": "string" } }, "example": { "uuid": "cbb-uuid-123", "activatedBattlecardID": "bc-uuid-456", "feedbackAction": "helpful", "hidden": false } }, "IntelligenceItemOptionalValues": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } }, "maxValues": { "type": "integer" } }, "example": { "values": [ "30000", "50000", "100000" ], "maxValues": 1 } }, "BotStatus": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "example": { "code": "BOT_READY", "message": "Bot is ready to process requests", "createdAt": "2024-03-20T10:00:00Z" } }, "CreateAPIKeyRequest": { "required": [ "name", "orgLevel" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the API key" }, "orgLevel": { "type": "boolean", "description": "Whether the API key is organization-level or user-level" } }, "example": { "name": "Admin API Key", "orgLevel": true } }, "APIKey": { "required": [ "id", "lastSeenAt", "name", "organizationUUID", "userUUID", "value" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the API key" }, "name": { "type": "string", "description": "The name of the API key" }, "organizationUUID": { "type": "string", "description": "The UUID of the organization this API key belongs to, if applicable" }, "userUUID": { "type": "string", "description": "The UUID of the user this API key belongs to, if applicable" }, "value": { "type": "string", "description": "The actual API key value" }, "lastSeenAt": { "type": "string", "description": "The last time this API key was used", "format": "date-time" } }, "example": { "id": "e5323e40-xxxx-4f6f-84f6-85eba56091ed", "name": "Admin API Key", "organizationUUID": "16b78cec-xxxx-46d2-8213-5d3bb7d2571c", "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", "lastSeenAt": "2024-03-20T10:00:00Z" } }, "TeamRequest": { "required": [ "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "The UUID of the team the user will belong to.", "example": "f7c7fe28-ac4e-4181-a980-0f6ef98ca0e1" }, "primary": { "type": "boolean", "description": "Whether this team is the user's primary team.", "example": true } }, "example": { "uuid": "f7c7fe28-ac4e-4181-a980-0f6ef98ca0e1", "primary": true } }, "Links": { "type": "object", "properties": { "self": { "type": "string" }, "related": { "type": "string" } }, "example": { "self": "https://api.attention.tech/v2/conversations/123", "related": "https://api.attention.tech/v2/conversations/123/participants" } }, "Meta": { "type": "object", "properties": { "pageCount": { "type": "integer" }, "totalRecords": { "type": "integer" }, "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" } }, "example": { "pageCount": 5, "totalRecords": 100, "pageNumber": 1, "pageSize": 20 } }, "Role": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "example": { "uuid": "84e67f54-5157-442b-a2b3-8b9c728b2fef", "name": "Admin", "type": "ADMIN" } }, "Base_422_Error": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BaseError" } }, "example": { "code": 422, "message": "Missing required fields in body" } }, "Base_401_Error": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BaseError" } }, "example": { "code": 401, "message": "unauthenticated for Invalid API key" } }, "Base_500_Error": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Error" } }, "example": { "code": "500", "detail": "An unexpected error occurred on the server. Please try again later or contact support if the problem persists.", "id": "internal_server_error", "title": "Internal Server Error" } }, "CreateUserRequest": { "required": [ "email", "first_name", "last_name", "roleUUID", "teams" ], "type": "object", "properties": { "email": { "type": "string", "description": "The email address of the new user.", "example": "user@example.com" }, "first_name": { "type": "string", "description": "The first name of the new user.", "example": "John" }, "last_name": { "type": "string", "description": "The last name of the new user.", "example": "Doe" }, "password": { "type": "string", "description": "The password for the new user's account." }, "teams": { "minItems": 1, "type": "array", "description": "A list of teams the user will belong to. Each team requires a UUID.", "items": { "$ref": "#/components/schemas/TeamRequest" } }, "roleUUID": { "type": "string", "description": "The UUID of the role assigned to the user." }, "seat_type": { "type": "string", "description": "The type of seat assigned to the user.", "example": "recording", "default": "recording", "enum": [ "listener", "recording" ] } }, "example": { "email": "15john.doe@example.com", "first_name": "John", "last_name": "Doe", "password": "SecureP@ssw0rd!", "roleUUID": "84e67f54-5157-442b-a2b3-8b9c728b2fef1", "teams": [ { "uuid": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "primary": true }, { "uuid": "802a13d8-1ad0-4f4a-b880-9ace889fafa6", "primary": false } ], "seat_type": "recording" } }, "CreateUserResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "example": { "data": { "botName": "John's Notetaker", "email": "15john.doe@example.com", "firstName": "John", "lastName": "Doe", "primaryTeamUUID": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "settings": { "autoCalculateCRMFields": true, "joinWhenIAmHostAndAlone": true, "joinWhenIAmHostWithPeers": true, "joinWhenUnlicensedPeerIsHost": true, "realTimeCapabilitiesOFF": true, "seat_type": "recording" }, "transcriptLang": "en", "uuid": "c74eb7bc-7b0e-45e2-843a-67305bfc4dce" } } }, "UpdateUserRequest": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "password": { "type": "string" }, "botName": { "type": "string" }, "dealsEnabled": { "type": "boolean" }, "teamUUIDsToRemove": { "type": "array", "items": { "type": "string" } }, "teamsToAdd": { "type": "array", "items": { "$ref": "#/components/schemas/TeamRequest" } }, "roleUUID": { "type": "string", "description": "The UUID of the role assigned to the user." }, "seat_type": { "type": "string", "description": "The type of seat assigned to the user.", "example": "recording", "default": "recording", "enum": [ "listener", "recording" ] } }, "example": { "firstName": "John", "lastName": "Doe", "password": "newPassword123", "botName": "JohnBot4", "dealsEnabled": false, "teamUUIDsToRemove": [ "802a13d8-1ad0-4f4a-b880-9ace889fafa61" ], "teamsToAdd": [ { "uuid": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "primary": true }, { "uuid": "802a13d8-1ad0-4f4a-b880-9ace889fafa6", "primary": false } ], "roleUUID": "84e67f54-5157-442b-a2b3-8b9c728b2fef1", "seat_type": "recording" } }, "UpdateUserResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "example": { "data": { "botName": "John's Notetaker", "email": "15john.doe@example.com", "firstName": "John", "lastName": "Doe", "primaryTeamUUID": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "roles": [ { "name": "Sales Rep", "type": "SALES_REP", "uuid": "55906d03-2849-4c3c-a67f-da07a6300de4" } ], "settings": { "autoCalculateCRMFields": true, "joinWhenIAmHostAndAlone": true, "joinWhenIAmHostWithPeers": true, "joinWhenUnlicensedPeerIsHost": true, "realTimeCapabilitiesOFF": true, "seat_type": "recording" }, "transcriptLang": "en", "uuid": "c74eb7bc-7b0e-45e2-843a-67305bfc4dce" } } }, "CreateTeamRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" }, "parentTeamUUID": { "type": "string" } }, "example": { "name": "Marketing", "parentTeamUUID": "2ccf9bde-68e3-4de4-bc4e-51b927336665" } }, "CreateTeamResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Team" } }, "example": { "data": { "name": "[Attention] Marketing", "uuid": "5d350a34-6c8d-4408-b0d6-6cfac4782e1f" } } }, "UpdateTeamRequest": { "type": "object", "properties": { "name": { "type": "string" }, "parentTeamUUID": { "type": "string" } }, "example": { "name": "Marketing", "parentTeamUUID": "2ccf9bde-68e3-4de4-bc4e-51b927336665" } }, "UpdateTeamResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Team" } }, "example": { "data": { "name": "Marketing", "uuid": "25fd70be-4d15-4b95-9931-69a320ceef76" } } }, "ListOrganizationRolesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } }, "example": { "data": [ { "name": "Admin", "type": "ADMIN", "uuid": "84e67f54-5157-442b-a2b3-8b9c728b2fef" }, { "name": "Sales Rep", "type": "SALES_REP", "uuid": "55906d03-2849-4c3c-a67f-da07a6300de4" } ] } }, "CalendarEventJoinableSource": { "type": "string", "example": "DEFAULT", "enum": [ "DEFAULT", "USER", "TEAM" ] }, "CalendarEventJoinable": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/CalendarEventJoinableSource" }, "shouldJoin": { "type": "boolean" }, "reason": { "type": "string" } }, "example": { "source": "USER", "shouldJoin": true, "reason": "User has enabled auto-join for this meeting type" } }, "GoogleCalendarNotice": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } }, "example": { "type": "WARNING", "message": "Calendar sync is experiencing delays" } }, "CalendarEvent": { "type": "object", "properties": { "uuid": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "notice": { "$ref": "#/components/schemas/GoogleCalendarNotice" }, "conversation": { "$ref": "#/components/schemas/Conversation" }, "joinableOverride": { "$ref": "#/components/schemas/CalendarEventJoinable" }, "joinableFinal": { "$ref": "#/components/schemas/CalendarEventJoinable" }, "joinUrl": { "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } }, "example": { "uuid": "event_123", "summary": "Sales Team Meeting", "description": "Weekly sales team sync", "startTime": "2024-03-20T10:00:00Z", "endTime": "2024-03-20T11:00:00Z", "notice": { "type": "WARNING", "message": "Calendar sync is experiencing delays" }, "joinableOverride": { "source": "USER", "shouldJoin": true, "reason": "User has enabled auto-join for this meeting type" }, "joinableFinal": { "source": "USER", "shouldJoin": true, "reason": "User has enabled auto-join for this meeting type" }, "joinUrl": "https://zoom.us/j/123456789", "participants": [ { "id": "participant_123", "email": "john.doe@example.com", "organizer": true, "name": "John Doe", "status": "accepted" } ] } }, "CalendarEventsPage": { "type": "object", "properties": { "pageCount": { "type": "integer" }, "totalRecords": { "type": "integer" }, "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } } }, "example": { "pageCount": 2, "totalRecords": 20, "pageNumber": 1, "pageSize": 10, "items": [ { "uuid": "event_123", "summary": "Sales Team Meeting", "description": "Weekly sales team sync", "startTime": "2024-03-20T10:00:00Z", "endTime": "2024-03-20T11:00:00Z", "joinUrl": "https://zoom.us/j/123456789", "participants": [ { "id": "participant_123", "email": "john.doe@example.com", "organizer": true, "name": "John Doe", "status": "accepted" } ] } ] } }, "Base_Scim_Error": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "detail": { "type": "string", "description": "A description of the error" }, "status": { "type": "integer", "description": "The HTTP status code for the error" } }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "The details of the error", "status": 409 } }, "ServiceProviderConfigResponse": { "type": "object", "properties": { "schemas": { "type": "array", "example": [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ], "items": { "type": "string" } }, "documentationUrl": { "type": "string", "example": "https://support.okta.com/scim-fake-page.html" }, "patch": { "required": [ "supported" ], "type": "object", "properties": { "supported": { "type": "boolean" } }, "example": { "supported": false } }, "bulk": { "required": [ "supported" ], "type": "object", "properties": { "supported": { "type": "boolean" } }, "example": { "supported": false } }, "filter": { "required": [ "maxResults", "supported" ], "type": "object", "properties": { "supported": { "type": "boolean" }, "maxResults": { "type": "integer" } }, "example": { "supported": false, "maxResults": 100 } }, "changePassword": { "required": [ "supported" ], "type": "object", "properties": { "supported": { "type": "boolean" } }, "example": { "supported": true } }, "sort": { "required": [ "supported" ], "type": "object", "properties": { "supported": { "type": "boolean" } }, "example": { "supported": false } }, "etag": { "required": [ "supported" ], "type": "object", "properties": { "supported": { "type": "boolean" } }, "example": { "supported": false } }, "authenticationSchemes": { "type": "array", "example": [ { "name": "HTTP Basic", "description": "Authentication via API key in the Authorization header", "specUri": "http://tools.ietf.org/html/rfc2617", "documentationUri": "https://datatracker.ietf.org/doc/html/rfc2617", "type": "httpbasic", "primary": true } ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "specUri": { "type": "string" }, "documentationUri": { "type": "string" }, "type": { "type": "string" }, "primary": { "type": "boolean" } } } }, "urn:okta:schemas:scim:providerconfig:1.0": { "type": "object", "properties": { "userManagementCapabilities": { "type": "array", "items": { "type": "string" } } }, "example": { "userManagementCapabilities": [ "GROUP_PUSH", "IMPORT_NEW_USERS", "IMPORT_PROFILE_UPDATES", "PUSH_NEW_USERS", "PUSH_PASSWORD_UPDATES", "PUSH_PENDING_USERS", "PUSH_PROFILE_UPDATES", "PUSH_USER_DEACTIVATION", "REACTIVATE_USERS" ] } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ], "documentationUrl": "https://support.okta.com/scim-fake-page.html", "patch": { "supported": true }, "bulk": { "supported": false }, "filter": { "supported": true, "maxResults": 200 }, "changePassword": { "supported": false }, "sort": { "supported": false }, "etag": { "supported": false }, "authenticationSchemes": [ { "name": "HTTP Basic", "description": "Authentication via API key in the Authorization header", "specUri": "http://tools.ietf.org/html/rfc2617", "documentationUri": "https://datatracker.ietf.org/doc/html/rfc2617", "type": "httpbasic", "primary": true } ] } }, "CreateScimUserRequest": { "required": [ "active", "emails", "name", "password", "schemas", "userName" ], "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "userName": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "primary": { "type": "boolean" }, "value": { "type": "string" }, "type": { "type": "string" } } } }, "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string" } } } }, "name": { "type": "object", "properties": { "familyName": { "type": "string" }, "givenName": { "type": "string" } } }, "active": { "type": "boolean" }, "password": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "display": { "type": "string" }, "value": { "type": "string" } } } }, "urn:okta:onprem_app:1.0:user:custom": { "type": "object", "properties": { "roleUUID": { "type": "string" } } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:okta:onprem_app:1.0:user:custom" ], "userName": "myemail@example.com", "emails": [ { "primary": true, "value": "myemail@example.com", "type": "primary" }, { "primary": false, "value": "mypersonalemail@example.com", "type": "secondary" } ], "phoneNumbers": [ { "value": "123-444-5555", "type": "mobile" } ], "name": { "familyName": "LastName", "givenName": "FirstName" }, "active": true, "password": "verySecure", "groups": [ { "display": "Team A", "value": "2ccf9bde-68e3-4de4-bc4e-51b927336665" }, { "display": "Team B", "value": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" } ], "urn:okta:onprem_app:1.0:user:custom": { "roleUUID": "84e67f54-5157-442b-a2b3-8b9c728b2fef" } } }, "ScimUser": { "required": [ "active", "emails", "externalId", "id", "meta", "name", "phoneNumbers", "schemas", "urn:okta:onprem_app:1.0:user:custom", "userName" ], "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "meta": { "type": "object", "properties": { "created": { "type": "string" }, "lastModified": { "type": "string" }, "version": { "type": "string" } } }, "schemas": { "type": "array", "items": { "type": "string" } }, "userName": { "type": "string" }, "displayName": { "type": "string" }, "preferredLanguage": { "type": "string" }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "active": { "type": "boolean" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string" }, "primary": { "type": "boolean" } } } }, "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string" } } } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "display": { "type": "string" }, "value": { "type": "string" } } } }, "name": { "type": "object", "properties": { "familyName": { "type": "string" }, "givenName": { "type": "string" } } }, "urn:okta:onprem_app:1.0:user:custom": { "type": "object", "properties": { "roleUUID": { "type": "string" } } } }, "example": { "id": "d0dd58e43ded4293a61a8760fcba0458", "externalId": "00ustvXq1A8UAuobW0f5", "meta": { "created": "04-17-2020 00:00:00", "lastModified": "04-17-2020 00:00:00", "version": "v1.0" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:scim:schemas:extension:okta:1.0" ], "userName": "steph.c@example.com", "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en-US", "timezone": "America/Los_Angeles", "active": true, "emails": [ { "value": "steph.c@example.com", "type": "work", "primary": true } ], "phoneNumbers": [ { "value": "123-444-5555", "type": "mobile" } ], "groups": [], "name": { "familyName": "Curry", "givenName": "Steph" }, "urn:okta:onprem_app:1.0:user:custom": { "roleUUID": "84e67f54-5157-442b-a2b3-8b9c728b2fef" } } }, "ListScimUsersResponse": { "required": [ "Resources", "itemsPerPage", "schemas", "startIndex", "totalResults" ], "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "totalResults": { "type": "integer" }, "startIndex": { "type": "integer" }, "itemsPerPage": { "type": "integer" }, "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimUser" } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "totalResults": 3, "startIndex": 1, "itemsPerPage": 3, "Resources": [ { "id": "d0dd58e43ded4293a61a8760fcba0458", "externalId": "00ustvXq1A8UAuobW0f5", "meta": { "created": "04-17-2020 00:00:00", "lastModified": "04-17-2020 00:00:00", "version": "v1.0" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:scim:schemas:extension:okta:1.0" ], "userName": "steph.c@example.com", "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en-US", "timezone": "America/Los_Angeles", "active": true, "emails": [ { "value": "steph.c@example.com", "type": "work", "primary": true } ], "phoneNumbers": [ { "value": "123-444-5555", "type": "mobile" } ], "groups": [], "name": { "familyName": "Curry", "givenName": "Steph" }, "urn:okta:onprem_app:1.0:user:custom": { "roleUUID": "84e67f54-5157-442b-a2b3-8b9c728b2fef" } } ] } }, "ScimGroup": { "required": [ "id" ], "type": "object", "properties": { "schemas": { "type": "array", "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group", "urn:okta:custom:group:1.0" ], "items": { "type": "string" } }, "displayName": { "type": "string", "example": "firstGroup" }, "id": { "type": "string", "example": "1001" }, "members": { "type": "array", "example": [ { "value": "101", "display": "okta" } ], "items": { "$ref": "#/components/schemas/ScimGroupMember" } }, "urn:okta:custom:group:1.0": { "type": "object", "properties": { "description": { "type": "string", "example": "This is the first group" } } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "group-uuid-123", "displayName": "Sales Team", "members": [ { "value": "user-uuid-1", "display": "jane@example.com" } ] } }, "ScimGroupMember": { "required": [ "display", "value" ], "type": "object", "properties": { "value": { "type": "string", "example": "724b985e-5053-4d9d-b8c5-7f2941b60c26" }, "display": { "type": "string", "example": "john.doe@example.com" } }, "example": { "value": "user-uuid-123", "display": "jane@example.com" } }, "ScimCreateGroupRequest": { "required": [ "displayName", "schemas" ], "type": "object", "properties": { "schemas": { "type": "array", "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "items": { "type": "string" } }, "displayName": { "type": "string", "example": "Marketing" }, "members": { "type": "array", "example": [ { "value": "724b985e-5053-4d9d-b8c5-7f2941b60c26", "display": "okta" }, { "value": "8b6109ec-b34c-4343-91ea-f8b0d7dd2616", "display": "admin" } ], "items": { "$ref": "#/components/schemas/ScimGroupMember" } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Sales Team", "members": [ { "value": "user-uuid-1", "display": "jane@example.com" }, { "value": "user-uuid-2", "display": "john@example.com" } ] } }, "ScimCreateGroupResponse": { "required": [ "displayName", "id", "members", "schemas" ], "type": "object", "properties": { "schemas": { "type": "array", "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group", "urn:okta:custom:group:1.0" ], "items": { "type": "string" } }, "displayName": { "type": "string", "example": "[Attention] Marketing" }, "id": { "type": "string", "example": "3ebee315-ef0f-45b8-b5cb-94fb761093d7" }, "members": { "type": "array", "example": [ { "value": "724b985e-5053-4d9d-b8c5-7f2941b60c26", "display": "22john.doe@example.com" }, { "value": "8b6109ec-b34c-4343-91ea-f8b0d7dd2616", "display": "23john.doe@example.com" } ], "items": { "$ref": "#/components/schemas/ScimGroupMember" } }, "urn:okta:custom:group:1.0": { "type": "object", "properties": { "description": { "type": "string", "example": "This is a group created for marketing purposes" } } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "group-uuid-123", "displayName": "Sales Team", "members": [ { "value": "user-uuid-1", "display": "jane@example.com" } ] } }, "ListScimGroupsResponse": { "required": [ "Resources", "itemsPerPage", "schemas", "startIndex", "totalResults" ], "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "totalResults": { "type": "integer" }, "startIndex": { "type": "integer" }, "itemsPerPage": { "type": "integer" }, "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimGroup" } } }, "example": { "totalResults": 2, "startIndex": 1, "itemsPerPage": 2, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group", "urn:okta:custom:group:1.0" ], "displayName": "firstGroup", "id": "1001", "members": [ { "value": "101", "display": "okta" } ], "urn:okta:custom:group:1.0": { "description": "This is the first group" } }, { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "secondGroup", "id": "1002", "members": [ { "value": "101", "display": "okta" }, { "value": "102", "display": "admin" } ] } ] } }, "UpdateScimGroupRequest": { "required": [ "displayName", "schemas" ], "type": "object", "properties": { "schemas": { "type": "array", "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "items": { "type": "string" } }, "displayName": { "type": "string", "example": "Marketing" }, "members": { "type": "array", "example": [ { "value": "724b985e-5053-4d9d-b8c5-7f2941b60c26", "display": "okta" }, { "value": "8b6109ec-b34c-4343-91ea-f8b0d7dd2616", "display": "admin" } ], "items": { "$ref": "#/components/schemas/ScimGroupMember" } } }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Sales Team Updated", "members": [ { "value": "user-uuid-1", "display": "jane@example.com" }, { "value": "user-uuid-3", "display": "bob@example.com" } ] } }, "UpdateScimUserRequest": { "type": "object", "properties": { "id": { "type": "string" }, "schemas": { "type": "array", "items": { "type": "string" } }, "userName": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "primary": { "type": "boolean" }, "value": { "type": "string" }, "type": { "type": "string" } } } }, "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string" } } } }, "name": { "type": "object", "properties": { "familyName": { "type": "string" }, "givenName": { "type": "string" } } }, "active": { "type": "boolean" }, "password": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "display": { "type": "string" }, "value": { "type": "string" } } } }, "urn:okta:onprem_app:1.0:user:custom": { "type": "object", "properties": { "roleUUID": { "type": "string" } } } }, "example": { "id": "d0dd58e43ded4293a61a8760fcba0458", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:scim:schemas:extension:okta:1.0" ], "userName": "steph.c@example.com", "externalId": "00ustvXq1A8UAuobW0f5", "meta": { "created": "04-17-2020 00:00:00", "lastModified": "04-17-2020 00:00:00", "version": "v1.0" }, "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en-US", "timezone": "America/Los_Angeles", "active": true, "emails": [ { "value": "steph.c@example.com", "type": "work", "primary": true } ], "phoneNumbers": [ { "value": "123-444-5555", "type": "mobile" } ], "groups": [ { "display": "Team A", "value": "2ccf9bde-68e3-4de4-bc4e-51b927336665" }, { "display": "Team B", "value": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" } ], "name": { "familyName": "Curry", "givenName": "Steph" }, "urn:okta:onprem_app:1.0:user:custom": { "roleUUID": "84e67f54-5157-442b-a2b3-8b9c728b2fef" } } }, "PatchScimUserRequest": { "required": [ "Operations", "schemas" ], "type": "object", "properties": { "schemas": { "type": "array", "example": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "items": { "type": "string" } }, "Operations": { "type": "array", "items": { "required": [ "op" ], "type": "object", "properties": { "op": { "type": "string", "example": "replace", "enum": [ "add", "remove", "replace" ] } } } } }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { "op": "replace", "value": { "active": false } } ] } }, "PatchScimGroupRequest": { "required": [ "Operations", "schemas" ], "type": "object", "properties": { "schemas": { "type": "array", "example": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "items": { "type": "string" } }, "Operations": { "type": "array", "items": { "required": [ "op" ], "type": "object", "properties": { "op": { "type": "string", "example": "add", "enum": [ "add", "remove", "replace" ] }, "path": { "type": "string", "example": "members" } } } } }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { "op": "add", "path": "members", "value": [ { "value": "5b3680ed-0bed-4c98-af91-e75c3f384b15", "display": "john.doe@example.com" } ] } ] } }, "UsageReportResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageReport" } } }, "example": { "data": [ { "user": { "uuid": "user1-uuid", "email": "user1@email.com", "firstName": "FirstName1", "lastName": "LastName1", "team": { "uuid": "team-uuid", "name": "TeamName" } }, "metrics": { "coachingSessions": 0, "callsViewed": 0, "commentsLeft": 0, "snippetsCreated": 0, "gInsightsRan": 0, "conversationInsightsRan": 0 } }, { "user": { "uuid": "user2-uuid", "email": "user2@email.com", "firstName": "FirstName2", "lastName": "LastName2", "team": { "uuid": "team-uuid", "name": "TeamName" } }, "metrics": { "coachingSessions": 0, "callsViewed": 0, "commentsLeft": 0, "snippetsCreated": 0, "gInsightsRan": 0, "conversationInsightsRan": 0 } } ] } }, "UsageReport": { "required": [ "metrics", "user" ], "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UsageReportUser" }, "metrics": { "$ref": "#/components/schemas/UsageReportMetrics" } }, "example": { "user": { "uuid": "user-uuid-123", "email": "jane@example.com", "firstName": "Jane", "lastName": "Smith", "team": { "uuid": "team-uuid-456", "name": "Sales Team" } }, "metrics": { "callsViewed": 45, "coachingSessions": 12, "commentsLeft": 28, "conversationInsightsRan": 15, "gInsightsRan": 8, "snippetsCreated": 20 } } }, "UsageReportUser": { "type": "object", "properties": { "uuid": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "team": { "$ref": "#/components/schemas/UsageReportTeam" } }, "example": { "uuid": "user-uuid-123", "email": "jane@example.com", "firstName": "Jane", "lastName": "Smith", "team": { "uuid": "team-uuid-456", "name": "Sales Team" } } }, "UsageReportTeam": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" } }, "example": { "uuid": "team-uuid-456", "name": "Sales Team" } }, "UsageReportMetrics": { "required": [ "callsViewed", "coachingSessions", "commentsLeft", "conversationInsightsRan", "gInsightsRan", "snippetsCreated" ], "type": "object", "properties": { "coachingSessions": { "type": "integer" }, "callsViewed": { "type": "integer" }, "commentsLeft": { "type": "integer" }, "snippetsCreated": { "type": "integer" }, "gInsightsRan": { "type": "integer" }, "conversationInsightsRan": { "type": "integer" }, "superAgentQueries": { "type": "integer" }, "superAgentWebQueries": { "type": "integer" }, "superAgentSlackQueries": { "type": "integer" }, "superAgentSessions": { "type": "integer" }, "superAgentWebSessions": { "type": "integer" }, "superAgentSlackSessions": { "type": "integer" } }, "example": { "callsViewed": 45, "coachingSessions": 12, "commentsLeft": 28, "conversationInsightsRan": 15, "gInsightsRan": 8, "snippetsCreated": 20 } }, "ConnectionReportResponse": { "type": "object", "properties": { "summary": { "$ref": "#/components/schemas/ConnectionSummary" }, "users": { "type": "array", "description": "List of all users with their connection status", "items": { "$ref": "#/components/schemas/UserConnectionStatus" } } }, "example": { "summary": { "totalUsers": 4, "fullyConnected": 1, "missingCalendar": 1, "missingEmail": 1, "missingBoth": 1 }, "users": [ { "uuid": "user1-uuid", "email": "user1@company.com", "firstName": "John", "lastName": "Doe", "calendarConnected": true, "emailConnected": true }, { "uuid": "user2-uuid", "email": "user2@company.com", "firstName": "Jane", "lastName": "Smith", "calendarConnected": false, "emailConnected": true }, { "uuid": "user3-uuid", "email": "user3@company.com", "firstName": "Bob", "lastName": "Johnson", "calendarConnected": true, "emailConnected": false }, { "uuid": "user4-uuid", "email": "user4@company.com", "firstName": "Alice", "lastName": "Brown", "calendarConnected": false, "emailConnected": false } ] } }, "ConnectionSummary": { "required": [ "fullyConnected", "missingBoth", "missingCalendar", "missingEmail", "totalUsers" ], "type": "object", "properties": { "totalUsers": { "type": "integer", "description": "Total number of users in the organization" }, "fullyConnected": { "type": "integer", "description": "Users connected to both calendar and email" }, "missingCalendar": { "type": "integer", "description": "Users missing calendar connection" }, "missingEmail": { "type": "integer", "description": "Users missing email connection" }, "missingBoth": { "type": "integer", "description": "Users missing both calendar and email connections" } }, "example": { "totalUsers": 50, "fullyConnected": 35, "missingCalendar": 8, "missingEmail": 4, "missingBoth": 3 } }, "UserConnectionStatus": { "required": [ "calendarConnected", "email", "emailConnected", "firstName", "lastName", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "User unique identifier" }, "email": { "type": "string", "description": "User email address" }, "firstName": { "type": "string", "description": "User first name" }, "lastName": { "type": "string", "description": "User last name" }, "calendarConnected": { "type": "boolean", "description": "Whether the user has connected their calendar" }, "emailConnected": { "type": "boolean", "description": "Whether the user has connected their email" } }, "example": { "uuid": "user-uuid-123", "email": "jane@example.com", "firstName": "Jane", "lastName": "Smith", "calendarConnected": true, "emailConnected": true } }, "ImportConversationRequest": { "required": [ "mediaURL", "userID" ], "type": "object", "properties": { "mediaURL": { "type": "string", "description": "URL of the media file to import (audio or video)" }, "userID": { "type": "string", "description": "UUID of the user who owns this conversation" }, "applicationName": { "type": "string", "description": "Name of the external application (e.g., 'zap:gong', 'salesforce')" }, "applicationExternalID": { "type": "string", "description": "External ID from the source application" }, "conversationTitle": { "type": "string", "description": "Title or name of the conversation" }, "conversationStartedAt": { "type": "string", "description": "When the conversation started (ISO 8601 format)", "format": "date-time" }, "headers": { "type": "array", "description": "HTTP headers to use when fetching the media file", "items": { "$ref": "#/components/schemas/Header" } }, "opportunityID": { "type": "string", "description": "ID of the associated opportunity or deal" }, "linkedCrmRecords": { "type": "array", "description": "CRM records linked to this conversation (accounts, contacts, etc.)", "items": { "$ref": "#/components/schemas/LinkedCrmRecord" } }, "skipScorecardCalculation": { "type": "boolean", "description": "Skip automatic scorecard calculation for this conversation" }, "skipCRMFieldsCalculation": { "type": "boolean", "description": "Skip CRM fields calculation for this conversation" }, "skipOpportunitiesExport": { "type": "boolean", "description": "Skip exporting opportunities for this conversation" }, "transcriptionSettings": { "$ref": "#/components/schemas/TranscriptionSettings" }, "transcript": { "$ref": "#/components/schemas/TranscriptInput" }, "externalMetadata": { "$ref": "#/components/schemas/ExternalMetadata" } }, "example": { "mediaURL": "https://storage.example.com/recordings/call-abc123.mp4", "userID": "user-uuid-123", "conversationTitle": "Q1 Deal Review - Acme Corp", "conversationStartedAt": "2024-03-18T10:30:00Z", "applicationName": "zoom", "applicationExternalID": "zoom-meeting-987654", "opportunityID": "opp-uuid-456", "linkedCrmRecords": [ { "id": "001ABC123", "code": "Account" } ], "externalMetadata": { "participants": [ { "email": "jane@example.com", "name": "Jane Smith", "accessType": "Internal", "organizer": true }, { "email": "john@customer.com", "name": "John Doe", "accessType": "External", "organizer": false } ], "extra": { "source": "zoom", "meetingDuration": 1800 } }, "transcriptionSettings": { "gladia": { "enableDiarization": true } }, "headers": [ { "key": "Authorization", "value": "Bearer token123" } ], "skipCRMFieldsCalculation": false, "skipOpportunitiesExport": false, "skipScorecardCalculation": false } }, "ImportConversationResponse": { "required": [ "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the newly imported conversation" } }, "example": { "uuid": "conv-uuid-new-123" } }, "Header": { "required": [ "key", "value" ], "type": "object", "properties": { "key": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } }, "example": { "key": "Authorization", "value": "Bearer eyJhbGciOiJIUzI1NiJ9..." } }, "TranscriptionSettings": { "type": "object", "properties": { "gladia": { "$ref": "#/components/schemas/GladiaTranscriptionSettings" } }, "example": { "gladia": { "enableDiarization": true } } }, "GladiaTranscriptionSettings": { "type": "object", "properties": { "enableDiarization": { "type": "boolean", "description": "Enable speaker diarization (identifying different speakers)" } }, "example": { "enableDiarization": true } }, "TranscriptInput": { "type": "object", "properties": { "v1": { "$ref": "#/components/schemas/TranscriptV1Input" }, "v2": { "$ref": "#/components/schemas/TranscriptV2Input" } }, "example": { "v1": { "pieceInFlux": "", "final": [ { "speaker": "Jane Smith", "sentence": "Let's review the proposal.", "startTimestamp": 0.5, "endTimestamp": 3.2 } ] } } }, "TranscriptV1Input": { "required": [ "final", "pieceInFlux" ], "type": "object", "properties": { "pieceInFlux": { "type": "string", "description": "Current incomplete piece being transcribed" }, "final": { "type": "array", "description": "Finalized transcript items", "items": { "$ref": "#/components/schemas/TranscriptV1Item" } } }, "example": { "pieceInFlux": "", "final": [ { "speaker": "Jane Smith", "sentence": "Let's review the proposal.", "startTimestamp": 0.5, "endTimestamp": 3.2 } ] } }, "TranscriptV1Item": { "required": [ "startTimestamp" ], "type": "object", "properties": { "speaker": { "type": "string", "description": "Speaker identifier" }, "sentence": { "type": "string", "description": "Transcribed text" }, "startTimestamp": { "type": "number", "description": "Start time in seconds", "format": "float" }, "endTimestamp": { "type": "number", "description": "End time in seconds", "format": "float" } }, "example": { "speaker": "Jane Smith", "sentence": "Let's review the proposal.", "startTimestamp": 0.5, "endTimestamp": 3.2 } }, "TranscriptV2Input": { "required": [ "final", "pieceInFlux" ], "type": "object", "properties": { "pieceInFlux": { "type": "string", "description": "Current incomplete piece being transcribed" }, "final": { "type": "array", "description": "Finalized transcript items with word-level timing", "items": { "$ref": "#/components/schemas/TranscriptV2Item" } } }, "example": { "pieceInFlux": "", "final": [ { "speaker": "Jane Smith", "words": [ { "text": "Let's", "startTimestamp": 0.5, "endTimestamp": 0.8 }, { "text": "review", "startTimestamp": 0.9, "endTimestamp": 1.3 } ] } ] } }, "TranscriptV2Item": { "required": [ "speaker", "words" ], "type": "object", "properties": { "speaker": { "type": "string", "description": "Speaker identifier" }, "words": { "type": "array", "description": "Individual words with timestamps", "items": { "$ref": "#/components/schemas/Word" } } }, "example": { "speaker": "Jane Smith", "words": [ { "text": "Hello", "startTimestamp": 0.5, "endTimestamp": 0.8 }, { "text": "everyone", "startTimestamp": 0.9, "endTimestamp": 1.3 } ] } }, "Word": { "required": [ "endTimestamp", "startTimestamp", "text" ], "type": "object", "properties": { "text": { "type": "string", "description": "Word text" }, "startTimestamp": { "type": "number", "description": "Start time in seconds", "format": "float" }, "endTimestamp": { "type": "number", "description": "End time in seconds", "format": "float" } }, "example": { "text": "Hello", "startTimestamp": 0.5, "endTimestamp": 0.8 } }, "ExternalMetadata": { "type": "object", "properties": { "participants": { "type": "array", "description": "List of conversation participants", "items": { "$ref": "#/components/schemas/ExternalMetadataParticipant" } }, "extra": { "type": "object", "additionalProperties": true, "description": "Additional metadata as key-value pairs" } }, "example": { "participants": [ { "email": "jane@example.com", "name": "Jane Smith", "accessType": "Internal", "organizer": true } ], "extra": { "source": "zoom" } } }, "ExternalMetadataParticipant": { "required": [ "accessType", "email", "name", "organizer" ], "type": "object", "properties": { "email": { "type": "string", "description": "Participant email address" }, "name": { "type": "string", "description": "Participant name" }, "accessType": { "type": "string", "description": "Whether the participant is internal or external to the organization", "enum": [ "Internal", "External" ] }, "organizer": { "type": "boolean", "description": "Whether this participant is the organizer of the conversation" } }, "example": { "email": "john@customer.com", "name": "John Doe", "accessType": "External", "organizer": false } }, "LibraryFolderStructureResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LibraryFolder" } }, "example": { "data": { "uuid": "folder-uuid-root", "name": "Sales Library", "organizationUUID": "org-uuid-123", "parentUUID": "", "path": "/Sales Library", "hidden": false, "subFolders": [ { "uuid": "folder-uuid-sub-1", "name": "Best Practices", "parentUUID": "folder-uuid-root", "hidden": false, "totalElements": 15, "totalFolders": 2 } ], "subFoldersTotal": 3 } } }, "LibraryFolder": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the folder" }, "name": { "type": "string", "description": "Name of the folder" }, "path": { "type": "string", "description": "Full path to the folder from root" }, "parentUUID": { "type": "string", "description": "UUID of the parent folder, empty if root" }, "hidden": { "type": "boolean", "description": "Whether the folder is hidden" }, "userUUID": { "type": "string", "description": "UUID of the user who owns this folder (for personal library folders)" }, "organizationUUID": { "type": "string", "description": "UUID of the organization this folder belongs to" }, "subFolders": { "type": "array", "description": "List of immediate subfolders", "items": { "$ref": "#/components/schemas/LibrarySubFolder" } }, "subFoldersTotal": { "type": "integer", "description": "Total number of subfolders", "format": "int64" } }, "example": { "uuid": "folder-uuid-root", "name": "Sales Library", "organizationUUID": "org-uuid-123", "parentUUID": "", "path": "/Sales Library", "hidden": false, "userUUID": "", "subFolders": [ { "uuid": "folder-uuid-sub-1", "name": "Best Practices", "parentUUID": "folder-uuid-root", "hidden": false, "totalElements": 15, "totalFolders": 2 } ], "subFoldersTotal": 3 } }, "LibrarySubFolder": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the subfolder" }, "name": { "type": "string", "description": "Name of the subfolder" }, "parentUUID": { "type": "string", "description": "UUID of the parent folder" }, "hidden": { "type": "boolean", "description": "Whether the subfolder is hidden" }, "totalElements": { "type": "integer", "description": "Total number of elements (snippets) in this folder", "format": "int64" }, "totalFolders": { "type": "integer", "description": "Total number of nested subfolders", "format": "int64" } }, "example": { "uuid": "folder-uuid-sub-1", "name": "Best Practices", "parentUUID": "folder-uuid-root", "hidden": false, "totalElements": 15, "totalFolders": 2 } }, "ConversationWorkflowLogsResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "List of conversation workflow logs", "items": { "$ref": "#/components/schemas/ConversationWorkflowLog" } }, "total": { "type": "integer", "description": "Total number of logs matching the filter criteria", "format": "int64" } }, "example": { "data": [ { "conversationUUID": "conv-uuid-123", "workflowName": "crm_export", "success": true, "error": "", "createdAt": "2024-03-18T14:35:00Z" }, { "conversationUUID": "conv-uuid-123", "workflowName": "scorecard_calculation", "success": false, "error": "Scorecard template not found", "createdAt": "2024-03-18T14:40:00Z" } ], "total": 2 } }, "ConversationWorkflowLog": { "type": "object", "properties": { "conversationUUID": { "type": "string", "description": "UUID of the conversation" }, "createdAt": { "type": "string", "description": "Timestamp when the workflow was executed", "format": "date-time" }, "workflowName": { "type": "string", "description": "Name of the workflow that was executed" }, "success": { "type": "boolean", "description": "Whether the workflow execution was successful" }, "error": { "type": "string", "description": "Error message if the workflow execution failed" } }, "example": { "conversationUUID": "conv-uuid-123", "workflowName": "crm_export", "success": true, "error": "", "createdAt": "2024-03-18T14:35:00Z" } }, "SendSuperAgentMessageRequest": { "required": [ "content" ], "type": "object", "properties": { "session_id": { "type": "string", "description": "Optional session ID. If not provided, a new session will be created." }, "content": { "type": "string", "description": "The message content to send to the super agent" }, "timezone": { "type": "string", "description": "Optional user timezone for timestamp formatting (e.g., 'America/New_York')" } }, "example": { "session_id": "session-uuid-456", "content": "What were our Q1 revenue results?", "timezone": "America/New_York" } }, "SuperAgentMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the message" }, "session_id": { "type": "string", "description": "ID of the session this message belongs to" }, "content": { "type": "string", "description": "The message content" }, "role": { "type": "string", "description": "The role of the message sender", "enum": [ "user", "assistant" ] }, "timestamp": { "type": "string", "description": "When the message was created", "format": "date-time" }, "metadata": { "type": "object", "properties": {}, "description": "Additional metadata associated with the message" } }, "example": { "id": "msg-uuid-123", "session_id": "session-uuid-456", "content": "Based on the Q1 data, revenue targets were met at 105%.", "role": "assistant", "timestamp": "2024-03-18T14:30:00Z", "metadata": {} } }, "SuperAgentMessageResponse": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The session ID" }, "user_message": { "$ref": "#/components/schemas/SuperAgentMessage" }, "assistant_message": { "$ref": "#/components/schemas/SuperAgentMessage" } }, "example": { "session_id": "session-uuid-456", "user_message": { "id": "msg-uuid-1", "session_id": "session-uuid-456", "content": "What were our Q1 revenue results?", "role": "user", "timestamp": "2024-03-18T14:30:00Z", "metadata": {} }, "assistant_message": { "id": "msg-uuid-2", "session_id": "session-uuid-456", "content": "Based on the Q1 data, revenue targets were met at 105%.", "role": "assistant", "timestamp": "2024-03-18T14:30:05Z", "metadata": {} } } }, "SuperAgentMessageAcceptedResponse": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The session ID to use for polling" }, "user_message": { "$ref": "#/components/schemas/SuperAgentMessage" }, "status": { "type": "string", "description": "Current processing status" }, "message": { "type": "string", "description": "Human-readable status message" } }, "example": { "session_id": "session-uuid-456", "user_message": { "id": "msg-uuid-1", "session_id": "session-uuid-456", "content": "Analyze our pipeline for Q2", "role": "user", "timestamp": "2024-03-18T14:30:00Z", "metadata": {} }, "status": "processing", "message": "Your message is being processed. Poll the session for results." } }, "SuperAgentSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal unique identifier" }, "session_id": { "type": "string", "description": "Session identifier used in API calls" }, "title": { "type": "string", "description": "Session title (auto-generated from first message)" }, "status": { "type": "string", "description": "Current status of the session", "enum": [ "ACTIVE", "COMPLETED", "CANCELLED", "FAILED" ] }, "created_at": { "type": "string", "description": "When the session was created", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the session was last updated", "format": "date-time" } }, "example": { "id": "sa-uuid-123", "session_id": "session-uuid-456", "title": "Q1 Revenue Analysis", "status": "ACTIVE", "created_at": "2024-03-18T14:00:00Z", "updated_at": "2024-03-18T14:30:00Z" } }, "SuperAgentSessionsResponse": { "type": "object", "properties": { "sessions": { "type": "array", "description": "List of user's super agent sessions", "items": { "$ref": "#/components/schemas/SuperAgentSession" } } }, "example": { "sessions": [ { "id": "sa-uuid-1", "session_id": "session-uuid-1", "title": "Q1 Revenue Analysis", "status": "ACTIVE", "created_at": "2024-03-18T14:00:00Z", "updated_at": "2024-03-18T14:30:00Z" }, { "id": "sa-uuid-2", "session_id": "session-uuid-2", "title": "Competitor Research", "status": "COMPLETED", "created_at": "2024-03-17T10:00:00Z", "updated_at": "2024-03-17T11:00:00Z" } ] } }, "SuperAgentSessionHistoryResponse": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The session ID" }, "title": { "type": "string", "description": "Session title" }, "status": { "type": "string", "description": "Current session status" }, "messages": { "type": "array", "description": "List of messages in the session", "items": { "$ref": "#/components/schemas/SuperAgentMessage" } } }, "example": { "session_id": "session-uuid-456", "title": "Q1 Revenue Analysis", "status": "ACTIVE", "messages": [ { "id": "msg-uuid-1", "session_id": "session-uuid-456", "content": "What were our Q1 revenue results?", "role": "user", "timestamp": "2024-03-18T14:30:00Z", "metadata": {} }, { "id": "msg-uuid-2", "session_id": "session-uuid-456", "content": "Revenue targets were met at 105%.", "role": "assistant", "timestamp": "2024-03-18T14:30:05Z", "metadata": {} } ] } }, "ConfirmCRMRequest": { "required": [ "intelligence" ], "type": "object", "properties": { "intelligence": { "type": "array", "description": "List of CRM intelligence items that the user has reviewed and confirmed", "items": { "$ref": "#/components/schemas/ConfirmCRMItem" } }, "opportunity_id": { "type": "string", "description": "UUID of the opportunity to associate the confirmed intelligence with", "example": "opp_xyz789" } }, "example": { "intelligence": [ { "id": "intel_001", "key": "next_steps", "value": "Schedule follow-up demo", "title": "Next Steps" } ], "opportunity_id": "opp_xyz789" } }, "ConfirmCRMItem": { "required": [ "id", "key", "title", "value" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the intelligence item", "example": "intel_001" }, "key": { "type": "string", "description": "Field key in the CRM (e.g., 'next_steps', 'budget')", "example": "next_steps" }, "value": { "type": "string", "description": "Confirmed value for the CRM field", "example": "Schedule follow-up demo" }, "title": { "type": "string", "description": "Human-readable title of the CRM field", "example": "Next Steps" } } }, "UpdateLinkedCrmRecordsRequest": { "type": "object", "properties": { "opportunity_id": { "type": "string", "description": "UUID of the opportunity to associate the CRM records with", "example": "opp_xyz789" }, "linked_crm_records": { "type": "array", "description": "List of CRM records to link to the conversation", "items": { "$ref": "#/components/schemas/LinkedCrmRecordInput" } } }, "example": { "opportunity_id": "opp_xyz789", "linked_crm_records": [ { "id": "acc_001", "code": "salesforce_account" }, { "id": "con_002", "code": "salesforce_contact" } ] } }, "LinkedCrmRecordInput": { "required": [ "code", "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "External CRM record ID", "example": "acc_001" }, "code": { "type": "string", "description": "CRM entity type code (e.g., 'salesforce_account', 'hubspot_contact')", "example": "salesforce_account" } } }, "UpdateLinkedCrmRecordsResponse": { "required": [ "success" ], "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the linked CRM records were updated successfully" } }, "example": { "success": true } }, "UpdateTeamOpportunityRequest": { "required": [ "opportunity_id", "title" ], "type": "object", "properties": { "opportunity_id": { "type": "string", "description": "External CRM opportunity ID to upsert", "example": "opp_xyz789" }, "title": { "type": "string", "description": "Display title for the opportunity", "example": "Enterprise Deal - Acme Corp" } }, "example": { "opportunity_id": "opp_xyz789", "title": "Enterprise Deal - Acme Corp" } }, "UpdateTeamOpportunityResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the created or updated opportunity record", "example": "rec_abc123" } }, "example": { "id": "rec_abc123" } }, "ConversationByExternalIdResponse": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "Attention conversation UUID corresponding to the external ID", "example": "conv_abc123" } }, "example": { "conversation_id": "conv_abc123" } }, "IntegrationWorkflow": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "autoExecution": { "type": "boolean" } } }, "ListIntegrationWorkflowsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationWorkflow" } } } }, "TriggerNativeIntegrationRequest": { "type": "object", "properties": { "workflowIds": { "type": "array", "description": "Specific integration workflow IDs to trigger (empty = all enabled)", "items": { "type": "string" } }, "fieldKeys": { "type": "array", "description": "Specific field keys to push (empty = all confirmed)", "items": { "type": "string" } }, "autoExecution": { "type": "boolean", "description": "Execution mode: true = aggressive retry, false = conservative" } } }, "TriggerNativeIntegrationResponse": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunInfo" } } } }, "WorkflowRunInfo": { "type": "object", "properties": { "workflowId": { "type": "string" }, "runId": { "type": "string" } } }, "KBSourceAttributes": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the KB source" }, "source_type": { "type": "string", "description": "Type of source: manual (inline content) or upload (S3 file)", "enum": [ "manual", "upload" ] }, "content": { "type": "string", "description": "Content of the source (present on get, absent on list)" }, "format": { "type": "string", "description": "Content format (e.g. text/markdown, application/pdf, text/html, text/plain)" }, "status": { "type": "string", "description": "Processing status of the source", "enum": [ "pending", "uploading", "indexing", "indexed", "failed" ] }, "file_size": { "type": "integer", "description": "File size in bytes" }, "chunk_count": { "type": "integer", "description": "Number of indexed chunks" }, "created_at": { "type": "string", "description": "Creation timestamp", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last update timestamp", "format": "date-time" } }, "example": { "title": "Q4 Product Launch Playbook", "source_type": "manual", "content": "# Product Launch Playbook\n\n## Overview\nThis document covers the key steps...", "format": "text/markdown", "status": "indexed", "file_size": 4096, "chunk_count": 12, "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:35:00Z" } }, "KBSource": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource type" }, "id": { "type": "string", "description": "Unique identifier of the KB source" }, "attributes": { "$ref": "#/components/schemas/KBSourceAttributes" } }, "example": { "type": "kb_sources", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attributes": { "title": "Q4 Product Launch Playbook", "source_type": "manual", "format": "text/markdown", "status": "indexed", "file_size": 4096, "chunk_count": 12, "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:35:00Z" } } }, "KBSourceResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KBSource" } }, "example": { "data": { "type": "kb_sources", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attributes": { "title": "Q4 Product Launch Playbook", "source_type": "manual", "content": "# Product Launch Playbook\n\n## Overview\nThis document covers the key steps...", "format": "text/markdown", "status": "indexed", "file_size": 4096, "chunk_count": 12, "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:35:00Z" } } } }, "ListKBSourcesResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "List of KB sources", "items": { "$ref": "#/components/schemas/KBSource" } } }, "example": { "data": [ { "type": "kb_sources", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "attributes": { "title": "Q4 Product Launch Playbook", "source_type": "manual", "format": "text/markdown", "status": "indexed", "file_size": 4096, "chunk_count": 12, "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:35:00Z" } }, { "type": "kb_sources", "id": "f7e8d9c0-b1a2-3456-7890-abcdef123456", "attributes": { "title": "Competitive Analysis 2025.pdf", "source_type": "upload", "format": "application/pdf", "status": "indexing", "file_size": 2458624, "chunk_count": 0, "created_at": "2025-01-16T08:00:00Z", "updated_at": "2025-01-16T08:01:00Z" } } ] } }, "CreateKBSourceRequest": { "required": [ "title" ], "type": "object", "properties": { "title": { "maxLength": 500, "type": "string", "description": "Title of the KB source" }, "content": { "maxLength": 524288, "type": "string", "description": "Content of the source (required for manual entries)" }, "format": { "type": "string", "description": "Content format (defaults to text/markdown). For PDF files, use the upload endpoint instead.", "default": "text/markdown", "enum": [ "text/markdown", "text/html", "text/plain" ] } }, "example": { "title": "Q4 Product Launch Playbook", "content": "# Product Launch Playbook\n\n## Overview\nThis document covers the key steps for launching our Q4 product line.\n\n## Timeline\n- Week 1: Internal enablement\n- Week 2: Beta launch\n- Week 3: GA release", "format": "text/markdown" } }, "UpdateKBSourceRequest": { "type": "object", "properties": { "title": { "maxLength": 500, "type": "string", "description": "Updated title" }, "content": { "maxLength": 524288, "type": "string", "description": "Updated content (triggers re-indexing)" } }, "example": { "title": "Q4 Product Launch Playbook (Updated)", "content": "# Product Launch Playbook v2\n\n## Overview\nUpdated with lessons learned from beta launch..." } }, "LabelOption": { "type": "object", "properties": { "value": { "type": "string", "description": "The option value as displayed to callers. Stored as an arbitrary JSON value server-side; surfaced here as a string for REST ergonomics.", "example": "high-intent" }, "description": { "type": "string", "description": "Optional human-readable description of the option, used for tooltips and AI-flow prompts.", "example": "Prospect has explicit buying signals" } }, "description": "A single selectable value within a label's option set. Present when the label is configured as a multi-value enum.", "example": { "value": "high-intent", "description": "Prospect has explicit buying signals" } }, "Label": { "required": [ "aiFlow", "allTeams", "createdAt", "isDefaultTemplate", "name", "organizationUUID", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the label.", "example": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" }, "name": { "type": "string", "description": "Human-readable label name. Unique per organization. Trimmed; 1 to 128 characters.", "example": "Buying Signal" }, "description": { "type": "string", "description": "Longer description of the label's meaning or criteria. 0 to 2000 characters.", "example": "Conversations where the prospect expresses a buying signal." }, "aiFlow": { "type": "boolean", "description": "Whether this label participates in the AI flow (auto-classification during conversation post-processing).", "example": true }, "allTeams": { "type": "boolean", "description": "Whether this label applies to all teams in the organization. When false, label visibility is constrained by team assignments managed through the internal API.", "example": false }, "isDefaultTemplate": { "type": "boolean", "description": "Whether this label originated from the organization's default template. Default-template labels are typically managed as a system-seeded group.", "example": false }, "options": { "type": "array", "description": "Optional set of selectable values when the label is a multi-value enum. Empty or omitted for binary labels.", "items": { "$ref": "#/components/schemas/LabelOption" } }, "organizationUUID": { "type": "string", "description": "UUID of the organization that owns the label. Always matches the authenticated principal's organization on responses.", "example": "16b78cec-82ef-46d2-8213-5d3bb7d2571c" }, "createdAt": { "type": "string", "description": "Timestamp when the label was created, in ISO 8601 (RFC 3339) format.", "format": "date-time", "example": "2026-04-16T18:00:00Z" } }, "description": "A label (label category) used to classify conversations and drive AI flows, scorecard criteria, and intelligence-item-collection criteria. Labels are scoped to a single organization.", "example": { "uuid": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "name": "Buying Signal", "description": "Conversations where the prospect expresses a buying signal.", "aiFlow": true, "allTeams": false, "isDefaultTemplate": false, "options": [ { "value": "high-intent", "description": "Prospect has explicit buying signals" } ], "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "createdAt": "2026-04-16T18:00:00Z" } }, "CreateLabelRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 128, "minLength": 1, "type": "string", "description": "Human-readable label name. Trimmed before validation. Must be unique within the organization.", "example": "Buying Signal" }, "description": { "maxLength": 2000, "type": "string", "description": "Optional description of the label. 0 to 2000 characters.", "example": "Conversations where the prospect expresses a buying signal." }, "aiFlow": { "type": "boolean", "description": "Whether this label participates in the AI flow (auto-classification during conversation post-processing). Defaults to false.", "example": true }, "allTeams": { "type": "boolean", "description": "Whether this label applies to all teams in the organization. Defaults to false.", "example": false }, "options": { "type": "array", "description": "Optional set of selectable values when the label is a multi-value enum. Omit or send an empty array for binary labels.", "items": { "$ref": "#/components/schemas/LabelOption" } } }, "description": "Payload for creating a new label in the authenticated organization. The organization UUID is derived from the API key and must not be supplied in the body.", "example": { "name": "Buying Signal", "description": "Conversations where the prospect expresses a buying signal.", "aiFlow": true, "allTeams": false, "options": [ { "value": "high-intent", "description": "Prospect has explicit buying signals" } ] } }, "UpdateLabelRequest": { "type": "object", "properties": { "name": { "maxLength": 128, "minLength": 1, "type": "string", "description": "New label name. Trimmed before validation. Must be unique within the organization. Renaming cascades to scorecard criteria and intelligence-item-collection criteria that reference the old name.", "example": "Buying Signal (v2)" }, "description": { "maxLength": 2000, "type": "string", "description": "New description. Pass an empty string to clear. 0 to 2000 characters. Omit to leave unchanged.", "nullable": true, "example": "Updated description of the buying signal label." }, "aiFlow": { "type": "boolean", "description": "New AI-flow participation value. Omit to leave unchanged.", "nullable": true, "example": false }, "allTeams": { "type": "boolean", "description": "New allTeams value. Omit to leave unchanged.", "nullable": true, "example": true }, "options": { "type": "array", "description": "New option set. When provided, the full list replaces the existing options. Omit to leave unchanged; send an empty array to clear.", "items": { "$ref": "#/components/schemas/LabelOption" } } }, "description": "Payload for partially updating a label. Only fields present in the body are applied (pointer-nil merge semantics). At least one mutable field must be provided.", "example": { "name": "Buying Signal (v2)", "description": "Updated description of the buying signal label.", "aiFlow": false } }, "LabelResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Label" } }, "description": "Single-resource response envelope for label endpoints.", "example": { "data": { "uuid": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "name": "Buying Signal", "description": "Conversations where the prospect expresses a buying signal.", "aiFlow": true, "allTeams": false, "isDefaultTemplate": false, "options": [], "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "createdAt": "2026-04-16T18:00:00Z" } } }, "ListLabelsResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "The page of labels belonging to the caller's organization.", "items": { "$ref": "#/components/schemas/Label" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "description": "Paginated list-response envelope for labels.", "example": { "data": [ { "uuid": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "name": "Buying Signal", "description": "Conversations where the prospect expresses a buying signal.", "aiFlow": true, "allTeams": false, "isDefaultTemplate": false, "options": [], "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "createdAt": "2026-04-16T18:00:00Z" } ], "meta": { "pageCount": 1, "totalRecords": 1, "pageNumber": 1, "pageSize": 50 } } }, "FieldConfigurationCriteriaCondition": { "type": "object", "properties": { "field": { "type": "string", "description": "Name of the field the condition applies to.", "example": "account.industry" }, "value": { "type": "string", "description": "Value the field must match for this condition.", "example": "technology" } }, "description": "A single condition within a field-configuration criteria expression. Conditions reference a field name and the value it must match for an intelligence item to apply.", "example": { "field": "account.industry", "value": "technology" } }, "FieldConfigurationCriteria": { "type": "object", "properties": { "conditions": { "type": "array", "description": "Ordered list of conditions to evaluate.", "items": { "$ref": "#/components/schemas/FieldConfigurationCriteriaCondition" } }, "operator": { "type": "string", "description": "Boolean operator used to combine the conditions.", "example": "AND", "enum": [ "AND", "OR" ] } }, "description": "Criteria expression that controls when this field configuration applies. Conditions are combined using the specified boolean operator.", "example": { "conditions": [ { "field": "account.industry", "value": "technology" } ], "operator": "AND" } }, "FieldConfiguration": { "required": [ "allTeams", "createdAt", "isDefaultTemplate", "name", "organizationUUID", "teamsUUID", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the field configuration.", "example": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11" }, "name": { "type": "string", "description": "Human-readable name of the field configuration.", "example": "Enterprise Discovery Questions" }, "organizationUUID": { "type": "string", "description": "UUID of the organization the field configuration belongs to.", "example": "16b78cec-82ef-46d2-8213-5d3bb7d2571c" }, "teamsUUID": { "type": "array", "description": "UUIDs of the teams this field configuration is assigned to. Ignored when `allTeams` is true.", "example": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ], "items": { "type": "string" } }, "allTeams": { "type": "boolean", "description": "When true, this configuration applies to every team in the organization and `teamsUUID` is ignored.", "example": false }, "isDefaultTemplate": { "type": "boolean", "description": "Whether this configuration is the organization's default template.", "example": false }, "criteria": { "$ref": "#/components/schemas/FieldConfigurationCriteria" }, "createdAt": { "type": "string", "description": "Timestamp when the configuration was created.", "format": "date-time", "example": "2026-03-01T12:00:00Z" } }, "description": "A Field Configuration (internally `IntelligenceItemCollection`) groups a set of intelligence items that are surfaced together for the teams it is assigned to. Field Configurations are scoped to a single organization.", "example": { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "name": "Enterprise Discovery Questions", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "teamsUUID": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ], "allTeams": false, "isDefaultTemplate": false, "criteria": { "conditions": [ { "field": "account.industry", "value": "technology" } ], "operator": "AND" }, "createdAt": "2026-03-01T12:00:00Z" } }, "CreateFieldConfigurationRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name of the configuration. Trimmed; 1-128 characters.", "example": "Enterprise Discovery Questions" }, "teamsUUID": { "type": "array", "description": "UUIDs of the teams to assign this configuration to. Ignored when `allTeams` is true.", "example": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ], "items": { "type": "string" } }, "allTeams": { "type": "boolean", "description": "When true, the configuration applies to every team in the organization.", "example": false }, "criteria": { "$ref": "#/components/schemas/FieldConfigurationCriteria" } }, "description": "Request payload for creating a new field configuration. The owning organization is inferred from the API key - any organization UUID included in the body is ignored.", "example": { "name": "Enterprise Discovery Questions", "teamsUUID": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ], "allTeams": false, "criteria": { "conditions": [ { "field": "account.industry", "value": "technology" } ], "operator": "AND" } } }, "UpdateFieldConfigurationRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "New human-readable name. When present, trimmed; 1-128 characters.", "example": "Renamed Discovery Questions" }, "teamsUUID": { "type": "array", "description": "Replacement list of team UUIDs this configuration is assigned to. When omitted, existing assignments are preserved.", "example": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ], "items": { "type": "string" } }, "allTeams": { "type": "boolean", "description": "When present, sets whether the configuration applies to every team in the organization.", "nullable": true, "example": false }, "criteria": { "$ref": "#/components/schemas/FieldConfigurationCriteria" } }, "description": "Request payload for updating a field configuration. Uses PATCH semantics - only fields present in the body are updated; omitted fields are left unchanged.", "example": { "name": "Renamed Discovery Questions", "teamsUUID": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ] } }, "FieldConfigurationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FieldConfiguration" } }, "description": "Envelope containing a single field configuration.", "example": { "data": { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "name": "Enterprise Discovery Questions", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "teamsUUID": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ], "allTeams": false, "isDefaultTemplate": false } } }, "ListFieldConfigurationsResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "Field configurations for the current page.", "items": { "$ref": "#/components/schemas/FieldConfiguration" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "description": "Paginated envelope containing a list of field configurations belonging to the authenticated organization.", "example": { "data": [ { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "name": "Enterprise Discovery Questions", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "teamsUUID": [ "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" ], "allTeams": false } ], "meta": { "totalRecords": 1, "pageNumber": 1, "pageSize": 50, "pageCount": 1 } } }, "FieldConfigurationItemMetadata": { "type": "object", "properties": { "min_score": { "type": "number", "description": "Minimum allowed score value.", "format": "double", "example": 0 }, "max_score": { "type": "number", "description": "Maximum allowed score value.", "format": "double", "example": 10 }, "middle_score": { "type": "number", "description": "Optional midpoint score value, used by scoring heuristics.", "format": "double", "nullable": true, "example": 5 }, "min_criteria": { "type": "string", "description": "Human-readable description of what the minimum score means.", "example": "No fit" }, "max_criteria": { "type": "string", "description": "Human-readable description of what the maximum score means.", "example": "Perfect fit" }, "middle_criteria": { "type": "string", "description": "Human-readable description of what the middle score means.", "nullable": true, "example": "Partial fit" } }, "description": "Numeric scoring metadata for a field-configuration item. Required when the item represents a numeric score - `min_score` must be less than or equal to `max_score`.", "example": { "min_score": 0, "max_score": 10, "min_criteria": "No fit", "max_criteria": "Perfect fit" } }, "FieldConfigurationItem": { "required": [ "allowLongResponse", "availableToAllClients", "category", "contentType", "contents", "createdAt", "extractQuotes", "fieldConfigurationUUID", "lastModifiedAt", "promptType", "title", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the item.", "example": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01" }, "fieldConfigurationUUID": { "type": "string", "description": "UUID of the parent field configuration.", "example": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11" }, "title": { "type": "string", "description": "Short human-readable title of the item. Trimmed; 1-128 characters.", "example": "Budget Range" }, "category": { "type": "string", "description": "Category of the item. One of the intelligence-category enum values.", "example": "CRM", "enum": [ "CRM", "Indicators", "BuiltInInsight", "CustomInsight" ] }, "contents": { "type": "string", "description": "Prompt text that Attention will evaluate against each conversation.", "example": "What is the customer's stated budget range?" }, "description": { "type": "string", "description": "Optional longer description shown to end users. 0-2000 characters.", "example": "Used by the RevOps team to forecast deal size." }, "promptType": { "type": "string", "description": "Prompt family used to analyze the conversation.", "example": "freeform" }, "contentType": { "type": "string", "description": "Expected shape of the extracted content.", "example": "text" }, "responseType": { "type": "string", "description": "Optional response data type hint.", "example": "number" }, "options": { "type": "array", "description": "Optional allowed response values when the item is a multiple-choice field.", "example": [ "small", "medium", "large" ], "items": { "type": "string" } }, "dependsOn": { "type": "array", "description": "UUIDs of other items this item depends on.", "items": { "type": "string" } }, "maxValues": { "type": "integer", "description": "Maximum number of values allowed for multi-select items.", "example": 1 }, "allowLongResponse": { "type": "boolean", "description": "Whether the analyzer may produce a longer free-text response.", "example": false }, "extractQuotes": { "type": "boolean", "description": "Whether the analyzer should attach supporting quotes to the response.", "example": true }, "availableToAllClients": { "type": "boolean", "description": "Internal flag marking the item as globally available.", "example": false }, "analysisLevel": { "type": "string", "description": "Level at which the item is evaluated.", "example": "conversation", "enum": [ "conversation", "deal", "lead", "contact", "account" ] }, "metadata": { "$ref": "#/components/schemas/FieldConfigurationItemMetadata" }, "createdAt": { "type": "string", "description": "Timestamp when the item was created.", "format": "date-time", "example": "2026-03-01T12:00:00Z" }, "lastModifiedAt": { "type": "string", "description": "Timestamp when the item was last updated.", "format": "date-time", "example": "2026-03-02T08:30:00Z" } }, "description": "A single field within a Field Configuration (internally `IntelligenceItem`). Items describe a prompt that Attention evaluates against a conversation and produces a value for. A field-configuration item is cloned as one `IntelligenceItemAssignment` per team the parent configuration is assigned to - see `IntelligenceItemAssignment`.", "example": { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "fieldConfigurationUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "title": "Budget Range", "category": "CRM", "contents": "What is the customer's stated budget range?", "promptType": "freeform", "contentType": "text", "analysisLevel": "conversation", "createdAt": "2026-03-01T12:00:00Z", "lastModifiedAt": "2026-03-02T08:30:00Z" } }, "IntelligenceItemAssignment": { "required": [ "category", "createdAt", "intelligenceItemUUID", "lastModifiedAt", "teamUUID", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the assignment row.", "example": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01-a1b2c3" }, "intelligenceItemUUID": { "type": "string", "description": "UUID of the underlying field-configuration item this assignment points at.", "example": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01" }, "teamUUID": { "type": "string", "description": "UUID of the team this assignment applies to.", "example": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4" }, "organizationUUID": { "type": "string", "description": "UUID of the organization this assignment belongs to.", "example": "16b78cec-82ef-46d2-8213-5d3bb7d2571c" }, "category": { "type": "string", "description": "Category of the underlying item (copied from the item at assignment time).", "example": "CRM" }, "displayOrder": { "type": "integer", "description": "Position of this assignment in the team's ordered list of items.", "example": 0 }, "requestStage": { "type": "integer", "description": "Analysis stage in which this assignment is evaluated.", "example": 0 }, "createdAt": { "type": "string", "description": "Timestamp when the assignment was created.", "format": "date-time", "example": "2026-03-01T12:00:00Z" }, "lastModifiedAt": { "type": "string", "description": "Timestamp when the assignment was last updated.", "format": "date-time", "example": "2026-03-01T12:00:00Z" } }, "description": "One row of the fan-out produced when a field-configuration item is created or updated: a single item is expanded into N `IntelligenceItemAssignment` rows, one per team the parent configuration is assigned to.", "example": { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01-a1b2c3", "intelligenceItemUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "teamUUID": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "organizationUUID": "16b78cec-82ef-46d2-8213-5d3bb7d2571c", "category": "CRM", "displayOrder": 0, "requestStage": 0 } }, "CreateFieldConfigurationItemRequest": { "required": [ "category", "contentType", "contents", "promptType", "title" ], "type": "object", "properties": { "title": { "type": "string", "description": "Short human-readable title of the item. Trimmed; 1-128 characters.", "example": "Budget Range" }, "category": { "type": "string", "description": "Category of the item.", "example": "CRM", "enum": [ "CRM", "Indicators", "BuiltInInsight", "CustomInsight" ] }, "contents": { "type": "string", "description": "Prompt text that Attention will evaluate against each conversation.", "example": "What is the customer's stated budget range?" }, "description": { "type": "string", "description": "Optional longer description. 0-2000 characters.", "example": "Used by the RevOps team to forecast deal size." }, "promptType": { "type": "string", "description": "Prompt family used to analyze the conversation.", "example": "freeform" }, "contentType": { "type": "string", "description": "Expected shape of the extracted content.", "example": "text" }, "responseType": { "type": "string", "description": "Optional response data type hint.", "example": "number" }, "options": { "type": "array", "description": "Optional allowed response values for multiple-choice items.", "example": [ "small", "medium", "large" ], "items": { "type": "string" } }, "dependsOn": { "type": "array", "description": "UUIDs of other items this item depends on.", "items": { "type": "string" } }, "maxValues": { "type": "integer", "description": "Maximum number of values allowed for multi-select items.", "nullable": true, "example": 1 }, "allowLongResponse": { "type": "boolean", "description": "Whether the analyzer may produce a longer free-text response.", "example": false }, "extractQuotes": { "type": "boolean", "description": "Whether the analyzer should attach supporting quotes to the response.", "example": true }, "analysisLevel": { "type": "string", "description": "Level at which the item is evaluated.", "example": "conversation", "enum": [ "conversation", "deal", "lead", "contact", "account" ] }, "metadata": { "$ref": "#/components/schemas/FieldConfigurationItemMetadata" }, "displayOrder": { "type": "integer", "description": "Optional starting position in the team's ordered item list; existing assignments at or after this position are shifted by one.", "nullable": true, "example": 0 }, "requestStage": { "type": "integer", "description": "Optional analysis stage in which the resulting assignments are evaluated.", "example": 0 } }, "description": "Request payload for creating a single new item inside a field configuration. The REST endpoint wraps this singular request into the underlying bulk creation path (ADR-9). Creating an item fans out into one `IntelligenceItemAssignment` per team the parent configuration is assigned to - the response returns the list of created assignments.", "example": { "title": "Budget Range", "category": "CRM", "contents": "What is the customer's stated budget range?", "promptType": "freeform", "contentType": "text", "analysisLevel": "conversation" } }, "UpdateFieldConfigurationItemRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "New title. Trimmed; 1-128 characters.", "example": "Budget Range (revised)" }, "contents": { "type": "string", "description": "New prompt text.", "example": "What budget range has the customer confirmed?" }, "description": { "type": "string", "description": "Optional new description. 0-2000 characters.", "example": "Revised for the 2026 playbook." }, "promptType": { "type": "string", "description": "New prompt family.", "example": "freeform" }, "contentType": { "type": "string", "description": "New content type hint.", "example": "text" }, "responseType": { "type": "string", "description": "New response type hint.", "example": "number" }, "options": { "type": "array", "description": "New allowed response values.", "example": [ "small", "medium", "large" ], "items": { "type": "string" } }, "dependsOn": { "type": "array", "description": "New dependency list.", "items": { "type": "string" } }, "maxValues": { "type": "integer", "description": "New maximum number of values for multi-select items.", "nullable": true, "example": 1 }, "allowLongResponse": { "type": "boolean", "description": "Whether the analyzer may produce a longer free-text response.", "nullable": true, "example": false }, "extractQuotes": { "type": "boolean", "description": "Whether the analyzer should attach supporting quotes.", "nullable": true, "example": true }, "analysisLevel": { "type": "string", "description": "New analysis level.", "example": "conversation", "enum": [ "conversation", "deal", "lead", "contact", "account" ] }, "metadata": { "$ref": "#/components/schemas/FieldConfigurationItemMetadata" } }, "description": "Request payload for updating an existing field-configuration item. Uses PATCH semantics - only fields present in the body are updated.", "example": { "title": "Budget Range (revised)", "contents": "What budget range has the customer confirmed?" } }, "FieldConfigurationItemResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FieldConfigurationItem" } }, "description": "Envelope containing a single field-configuration item.", "example": { "data": { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "fieldConfigurationUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "title": "Budget Range", "category": "CRM", "contents": "What is the customer's stated budget range?", "promptType": "freeform", "contentType": "text" } } }, "FieldConfigurationItemCreateData": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/FieldConfigurationItem" }, "assignments": { "type": "array", "description": "Assignment rows created as part of the fan-out. For a configuration assigned to N teams, N assignments are returned.", "items": { "$ref": "#/components/schemas/IntelligenceItemAssignment" } } }, "description": "Create-item payload: the newly created item plus the fan-out `IntelligenceItemAssignment` rows - one per team the parent field configuration is assigned to.", "example": { "item": { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "fieldConfigurationUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "title": "Budget Range", "category": "CRM", "contents": "What is the customer's stated budget range?", "promptType": "freeform", "contentType": "text" }, "assignments": [ { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01-a1b2c3", "intelligenceItemUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "teamUUID": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "category": "CRM", "displayOrder": 0 } ] } }, "FieldConfigurationItemCreateResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FieldConfigurationItemCreateData" } }, "description": "Envelope returned when a field-configuration item is created. The `data.assignments` array documents the fan-out (one entry per team the parent configuration is assigned to).", "example": { "data": { "item": { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "fieldConfigurationUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "title": "Budget Range", "category": "CRM", "contents": "What is the customer's stated budget range?", "promptType": "freeform", "contentType": "text" }, "assignments": [ { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01-a1b2c3", "intelligenceItemUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "teamUUID": "fe515723-fe2e-4959-a5fa-c4d3937fe7e4", "category": "CRM", "displayOrder": 0 } ] } } }, "ListFieldConfigurationItemsResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "Field-configuration items for the current page.", "items": { "$ref": "#/components/schemas/FieldConfigurationItem" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "description": "Paginated envelope containing a list of items belonging to a single field configuration.", "example": { "data": [ { "uuid": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11__item-01", "fieldConfigurationUUID": "b9e1c0a0-5a3d-4a9c-9b1e-2d6f4b7a1c11", "title": "Budget Range", "category": "CRM", "contents": "What is the customer's stated budget range?", "promptType": "freeform", "contentType": "text" } ], "meta": { "totalRecords": 1, "pageNumber": 1, "pageSize": 50, "pageCount": 1 } } }, "ScorecardInteractionType": { "type": "string", "description": "Type of interaction the scorecard evaluates.", "example": "conversation", "enum": [ "conversation", "chat", "email" ] }, "ScorecardItemType": { "type": "string", "description": "Scoring type for a scorecard item. Currently only numeric is supported.", "example": "numeric", "enum": [ "numeric" ] }, "ScorecardCriteriaOperator": { "type": "string", "description": "Boolean operator joining criteria conditions.", "example": "AND", "enum": [ "AND", "OR" ] }, "ScorecardCriteriaCondition": { "type": "object", "properties": { "field": { "type": "string", "description": "Field path being matched (for example, a label UUID or label option UUID)." }, "value": { "type": "string", "description": "Expected value for the field to satisfy the condition." } }, "description": "A single criteria condition pairing a field path with an expected value.", "example": { "field": "label-uuid-123", "value": "option-uuid-456" } }, "ScorecardCriteria": { "type": "object", "properties": { "operator": { "$ref": "#/components/schemas/ScorecardCriteriaOperator" }, "conditions": { "type": "array", "description": "List of field/value conditions evaluated with the operator.", "items": { "$ref": "#/components/schemas/ScorecardCriteriaCondition" } } }, "description": "Label-based criteria that gate when a scorecard is applied to an interaction.", "example": { "operator": "AND", "conditions": [ { "field": "label-uuid-123", "value": "option-uuid-456" } ] } }, "NumericScorecardMetadata": { "type": "object", "properties": { "min": { "type": "integer", "description": "Minimum score value (inclusive).", "nullable": true }, "middle": { "type": "integer", "description": "Optional middle score anchor. When present, a middleCriteria is required.", "nullable": true }, "max": { "type": "integer", "description": "Maximum score value (inclusive).", "nullable": true }, "minCriteria": { "type": "string", "description": "Guidance for the evaluator describing what a minimum score looks like." }, "middleCriteria": { "type": "string", "description": "Guidance for the evaluator describing what the middle score looks like. Required when middle is set." }, "maxCriteria": { "type": "string", "description": "Guidance for the evaluator describing what a maximum score looks like." } }, "description": "Configuration for a numeric scorecard item including score range and per-bucket criteria.", "example": { "min": 0, "middle": 50, "max": 100, "minCriteria": "No discovery questions asked.", "middleCriteria": "Some discovery questions asked, but key stakeholders missed.", "maxCriteria": "Thorough discovery covering budget, authority, need, and timeline." } }, "ScorecardItemMetadata": { "type": "object", "properties": { "numericMetadata": { "$ref": "#/components/schemas/NumericScorecardMetadata" } }, "description": "Type-discriminated metadata for a scorecard item. Numeric items populate numericMetadata.", "example": { "numericMetadata": { "min": 0, "middle": 50, "max": 100, "minCriteria": "No discovery questions asked.", "middleCriteria": "Some discovery questions asked.", "maxCriteria": "Thorough discovery performed." } } }, "Scorecard": { "required": [ "allTeams", "createdAt", "enabled", "expertMode", "interactionType", "isDefaultTemplate", "organizationUUID", "title", "uuid" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "Scorecard UUID." }, "title": { "type": "string", "description": "Human-readable title of the scorecard (1-128 characters)." }, "organizationUUID": { "type": "string", "description": "UUID of the organization that owns the scorecard." }, "teamUUID": { "type": "string", "description": "UUID of the specific team assigned to this scorecard, if any. Mutually exclusive with allTeams=true." }, "allTeams": { "type": "boolean", "description": "Whether the scorecard is assigned to every team in the organization." }, "enabled": { "type": "boolean", "description": "Whether the scorecard is active and runs against new interactions." }, "interactionType": { "$ref": "#/components/schemas/ScorecardInteractionType" }, "detailedInstructions": { "type": "string", "description": "Optional free-form guidance appended to the evaluator prompt." }, "scorecardPrompt": { "type": "string", "description": "Optional prompt override used in expert mode." }, "expertMode": { "type": "boolean", "description": "Whether this scorecard uses custom prompts (expert mode) instead of the default template." }, "isDefaultTemplate": { "type": "boolean", "description": "Whether this scorecard was seeded as one of the default organization templates." }, "criteria": { "$ref": "#/components/schemas/ScorecardCriteria" }, "createdAt": { "type": "string", "description": "Timestamp when the scorecard was created.", "format": "date-time" } }, "description": "A scorecard template used to evaluate a conversation, chat, or email.", "example": { "id": "sc-uuid-123", "title": "Sales Discovery Scorecard", "organizationId": "org-uuid-456", "teamId": "team-uuid-789", "allTeams": false, "enabled": true, "interactionType": "conversation", "detailedInstructions": "Focus on discovery quality and next-step commitments.", "scorecardPrompt": "", "expertMode": false, "isDefaultTemplate": false, "criteria": { "operator": "AND", "conditions": [] }, "createdAt": "2026-04-16T10:15:00Z" } }, "ScorecardItem": { "required": [ "createdAt", "lastUpdatedAt", "position", "scorecardUUID", "title", "type", "uuid", "version", "weight" ], "type": "object", "properties": { "uuid": { "type": "string", "description": "Scorecard item UUID." }, "scorecardUUID": { "type": "string", "description": "UUID of the parent scorecard." }, "title": { "type": "string", "description": "Human-readable title of the item (1-128 characters)." }, "type": { "$ref": "#/components/schemas/ScorecardItemType" }, "position": { "type": "integer", "description": "Zero-indexed ordering position among siblings on the parent scorecard." }, "weight": { "type": "integer", "description": "Relative weight of this item within the scorecard (0-100)." }, "version": { "type": "integer", "description": "Monotonic version counter incremented on each update." }, "expertPrompt": { "type": "string", "description": "Optional expert-mode prompt override for this specific item." }, "metadata": { "$ref": "#/components/schemas/ScorecardItemMetadata" }, "createdAt": { "type": "string", "description": "Timestamp when the item was created.", "format": "date-time" }, "lastUpdatedAt": { "type": "string", "description": "Timestamp of the most recent update.", "format": "date-time" } }, "description": "A single scoring criterion belonging to a scorecard template.", "example": { "id": "si-uuid-123", "scorecardId": "sc-uuid-456", "title": "Discovery Quality", "type": "numeric", "position": 0, "weight": 25, "version": 1, "expertPrompt": "", "metadata": { "numericMetadata": { "min": 0, "middle": 50, "max": 100, "minCriteria": "No discovery questions asked.", "middleCriteria": "Some discovery questions asked.", "maxCriteria": "Thorough discovery performed." } }, "createdAt": "2026-04-16T10:15:00Z", "lastUpdatedAt": "2026-04-16T10:15:00Z" } }, "CreateScorecardRequest": { "required": [ "title" ], "type": "object", "properties": { "title": { "type": "string", "description": "Human-readable title of the scorecard (1-128 characters, trimmed)." }, "teamUUID": { "type": "string", "description": "UUID of the team to assign the scorecard to. Mutually exclusive with allTeams=true. Omit both for an unassigned scorecard." }, "allTeams": { "type": "boolean", "description": "Assign the scorecard to every team in the organization. Mutually exclusive with teamId.", "default": false }, "enabled": { "type": "boolean", "description": "Whether the scorecard is active after creation.", "default": true }, "interactionType": { "$ref": "#/components/schemas/ScorecardInteractionType" }, "detailedInstructions": { "type": "string", "description": "Optional free-form guidance (0-2000 characters)." }, "scorecardPrompt": { "type": "string", "description": "Optional prompt override for expert mode (0-8000 characters)." }, "expertMode": { "type": "boolean", "description": "Whether the scorecard uses custom prompts instead of the default template.", "default": false }, "criteria": { "$ref": "#/components/schemas/ScorecardCriteria" } }, "description": "Payload for creating a scorecard template.", "example": { "title": "Sales Discovery Scorecard", "allTeams": true, "enabled": true, "interactionType": "conversation", "detailedInstructions": "Evaluate discovery quality.", "expertMode": false } }, "UpdateScorecardRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "Replacement title (1-128 characters, trimmed)." }, "teamUUID": { "type": "string", "description": "Reassign the scorecard to a specific team. Mutually exclusive with allTeams=true." }, "allTeams": { "type": "boolean", "description": "Reassign the scorecard to every team. Mutually exclusive with teamId.", "nullable": true }, "enabled": { "type": "boolean", "description": "Toggle the scorecard active state.", "nullable": true }, "interactionType": { "$ref": "#/components/schemas/ScorecardInteractionType" }, "detailedInstructions": { "type": "string", "description": "Replacement detailed instructions (0-2000 characters)." }, "scorecardPrompt": { "type": "string", "description": "Replacement expert-mode prompt (0-8000 characters)." }, "expertMode": { "type": "boolean", "description": "Toggle expert mode.", "nullable": true }, "criteria": { "$ref": "#/components/schemas/ScorecardCriteria" } }, "description": "Partial update payload for a scorecard. All fields are optional; at least one must be present.", "example": { "title": "Sales Discovery Scorecard (v2)", "enabled": false } }, "ScorecardResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Scorecard" } }, "description": "Single-resource envelope wrapping a Scorecard.", "example": { "data": { "id": "sc-uuid-123", "title": "Sales Discovery Scorecard", "organizationId": "org-uuid-456", "allTeams": true, "enabled": true, "interactionType": "conversation", "expertMode": false, "isDefaultTemplate": false, "createdAt": "2026-04-16T10:15:00Z" } } }, "CreateScorecardItemRequest": { "required": [ "title", "type", "weight" ], "type": "object", "properties": { "title": { "type": "string", "description": "Human-readable title of the item (1-128 characters, trimmed)." }, "type": { "$ref": "#/components/schemas/ScorecardItemType" }, "weight": { "type": "integer", "description": "Relative weight of this item within the scorecard (0-100)." }, "position": { "type": "integer", "description": "Optional position override. When omitted, the item is appended to the end of the scorecard." }, "expertPrompt": { "type": "string", "description": "Optional expert-mode prompt override (0-8000 characters)." }, "metadata": { "$ref": "#/components/schemas/ScorecardItemMetadata" } }, "description": "Payload for creating a single scorecard item.", "example": { "title": "Discovery Quality", "type": "numeric", "weight": 25, "metadata": { "numericMetadata": { "min": 0, "middle": 50, "max": 100, "minCriteria": "No discovery questions asked.", "middleCriteria": "Some discovery questions asked.", "maxCriteria": "Thorough discovery performed." } } } }, "UpdateScorecardItemRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "Replacement title (1-128 characters, trimmed)." }, "weight": { "type": "integer", "description": "Replacement weight (0-100)." }, "position": { "type": "integer", "description": "Replacement position. Reordering siblings is the caller's responsibility; overlapping positions may produce undefined ordering." }, "expertPrompt": { "type": "string", "description": "Replacement expert-mode prompt (0-8000 characters)." }, "metadata": { "$ref": "#/components/schemas/ScorecardItemMetadata" } }, "description": "Partial update payload for a scorecard item. All fields optional; at least one required.", "example": { "title": "Discovery Quality (revised)", "weight": 30 } }, "ScorecardItemResponse": { "required": [ "data" ], "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScorecardItem" } }, "description": "Single-resource envelope wrapping a ScorecardItem.", "example": { "data": { "id": "si-uuid-123", "scorecardId": "sc-uuid-456", "title": "Discovery Quality", "type": "numeric", "position": 0, "weight": 25, "version": 1, "createdAt": "2026-04-16T10:15:00Z", "lastUpdatedAt": "2026-04-16T10:15:00Z" } } }, "ListScorecardItemsResponse": { "required": [ "data", "meta" ], "type": "object", "properties": { "data": { "type": "array", "description": "Page of scorecard items ordered by position ascending.", "items": { "$ref": "#/components/schemas/ScorecardItem" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "description": "Paginated collection envelope of scorecard items.", "example": { "data": [ { "id": "si-uuid-123", "scorecardId": "sc-uuid-456", "title": "Discovery Quality", "type": "numeric", "position": 0, "weight": 25, "version": 1, "createdAt": "2026-04-16T10:15:00Z", "lastUpdatedAt": "2026-04-16T10:15:00Z" } ], "meta": { "totalRecords": 1, "pageNumber": 1, "pageSize": 50, "pageCount": 1 } } }, "RequestKBSourceUploadRequest": { "type": "object", "properties": { "title": { "maxLength": 500, "type": "string", "description": "Title of the KB source. Optional — if omitted, the server attempts to extract the title from PDF metadata, falling back to 'Untitled upload'." } }, "example": { "title": "Competitive Analysis 2025.pdf" } }, "RequestKBSourceUploadResponse": { "type": "object", "properties": { "source_id": { "type": "string", "description": "UUID of the created KB source" }, "upload_url": { "type": "string", "description": "Presigned S3 PUT URL for uploading the file" } }, "example": { "source_id": "f7e8d9c0-b1a2-3456-7890-abcdef123456", "upload_url": "https://s3.amazonaws.com/bucket/kb-sources/org-uuid/source-uuid?X-Amz-Algorithm=AWS4-HMAC-SHA256&..." } }, "RecorderMetricsMeetingsPage": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecorderMetricsMeeting" }, "description": "Page of meetings ordered by date (ascending when upcoming=true, descending otherwise) with UUID as tiebreaker." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page. Absent (or empty) when the iteration has reached the end of the dataset." } } }, "RecorderMetricsMeeting": { "type": "object", "required": [ "uuid", "summary", "date", "userUuid", "userName", "status", "statusLabel", "participants" ], "properties": { "uuid": { "type": "string", "description": "Calendar event UUID. Acts as the deduplication key." }, "conversationUuid": { "type": "string", "description": "Conversation UUID. Populated only when a recording exists (status=recorded)." }, "summary": { "type": "string", "description": "Meeting title." }, "date": { "type": "string", "format": "date-time", "description": "Meeting start time, ISO 8601." }, "userUuid": { "type": "string", "description": "UUID of the user attributed as the recorder. Falls back to the first event participant when no recording exists." }, "userName": { "type": "string", "description": "Display name for userUuid." }, "status": { "type": "string", "description": "Attention's native status code. Clients map this to their own taxonomy. See the endpoint description for the current set of values." }, "statusLabel": { "type": "string", "description": "Human-readable label for the status, resolved server-side." }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/RecorderMetricsMeetingParticipant" }, "description": "Every org user invited to the event with their per-user recording status." }, "consentLinkUsed": { "type": "boolean", "description": "Whether the meeting used an Attention consent link." }, "consentStatus": { "type": "string", "description": "consented | declined | no_response, when consentLinkUsed is true (no_response = a consent link was used but no attendee acted). Null when consentLinkUsed is false (no consent link)." } } }, "RecorderMetricsMeetingParticipant": { "type": "object", "required": [ "userUuid", "userName", "status", "statusLabel" ], "properties": { "userUuid": { "type": "string" }, "userName": { "type": "string" }, "status": { "type": "string", "description": "Per-user status. Same code space as the meeting-level status; can differ from it (e.g. a meeting may be `recorded` while a particular user is `not_join_when_alone`)." }, "statusLabel": { "type": "string" } } }, "ProactiveAction": { "type": "object", "description": "A Proactive Next Best Action as shown to the user.", "required": [ "uuid", "entity_type", "entity_id", "owner_user_uuid", "action_type", "title", "signal_type", "severity", "display_group", "subject", "draft_body", "proposed_recipients", "proposed_slots", "status", "external_url", "why", "generated_at", "updated_at", "expires_at" ], "properties": { "uuid": { "type": "string", "description": "Unique identifier of the action" }, "entity_type": { "type": "string", "description": "Type of the entity the action targets (e.g. crm_record)" }, "entity_id": { "type": "string", "description": "Identifier of the entity the action targets" }, "owner_user_uuid": { "type": "string", "description": "UUID of the user who owns the action" }, "action_type": { "type": "string", "description": "Kind of action (e.g. send_email)" }, "title": { "type": "string", "description": "Short title / next move" }, "signal_type": { "type": "string", "description": "The parent signal's type (e.g. no_reply, close_date_risk). Empty when the action has no parent signal." }, "severity": { "type": "string", "description": "The parent signal's severity: high, medium, or low. Empty when absent." }, "display_group": { "type": "string", "description": "The deterministic feed section this action belongs to, derived from signal_type: At risk, You committed, Buying signals, Re-engage, Coordinate internally, CRM cleanup, Connect your tools, or Other." }, "subject": { "type": "string", "description": "Draft subject line, when the action is an email." }, "draft_body": { "type": "string", "description": "Drafted message body, when available." }, "proposed_recipients": { "type": "array", "items": { "type": "string" }, "description": "Proposed recipients of the drafted message." }, "proposed_slots": { "type": "array", "items": { "type": "string" }, "description": "Proposed meeting time slots, rendered in the rep's timezone." }, "status": { "type": "string", "description": "Lifecycle status: pending, drafted, sent, dismissed, or expired." }, "external_url": { "type": "string", "description": "URL of the drafted artifact in the external system, when available" }, "why": { "$ref": "#/components/schemas/ProactiveActionWhy" }, "generated_at": { "type": "string", "format": "date-time", "description": "When the action was generated" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the action was last updated" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the action stops being valid and is no longer shown." } }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entity_type": "account", "entity_id": "0018c00002ExampleAAA", "owner_user_uuid": "a1b2c3d4-e5f6-7a8b-9c0d-ef1234567890", "action_type": "send_email", "title": "Follow up on the renewal", "signal_type": "no_reply", "severity": "medium", "display_group": "Re-engage", "subject": "Re: renewal", "draft_body": "Hi Jane,\n\nFollowing up on the renewal we discussed — do the proposed terms still work on your side?\n\nBest,\nAlex", "proposed_recipients": [ "jane.doe@example.com" ], "proposed_slots": [], "status": "pending", "external_url": "", "why": { "rationale": "No reply in 8 days and the opportunity's close date is this month.", "key_quote": { "text": "Let's circle back next week.", "speaker": "Jane Doe", "source_label": "Call on 2026-01-08", "source_url": "https://example.com/conversations/abc123" }, "evidence": [ { "label": "No reply in 8 days", "description": "Last outreach was 8 days ago with no response.", "impact": "negative", "source_label": "Email thread", "source_url": "https://example.com/mail/thread/123" } ] }, "generated_at": "2026-01-15T09:00:00.000Z", "updated_at": "2026-01-15T09:00:00.000Z", "expires_at": "2026-01-22T09:00:00.000Z" } }, "ProactiveActionWhy": { "type": "object", "description": "The reasoning behind a Proactive action — the \"why this suggestion\" contract.", "properties": { "rationale": { "type": "string", "description": "Plain-language explanation of why this action is suggested." }, "key_quote": { "$ref": "#/components/schemas/ProactiveActionKeyQuote" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/ProactiveActionEvidence" } } } }, "ProactiveActionKeyQuote": { "type": "object", "properties": { "text": { "type": "string" }, "speaker": { "type": "string" }, "source_label": { "type": "string" }, "source_url": { "type": "string" } } }, "ProactiveActionEvidence": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "impact": { "type": "string" }, "source_label": { "type": "string" }, "source_url": { "type": "string" } } }, "ListProactiveActionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProactiveAction" } }, "next_cursor": { "type": "string", "description": "Opaque cursor for the next page. Absent when there are no more results.", "example": "MjAyNi0wMS0xNVQwOTowMDowMFp8M2ZhODVmNjQtNTcxNy00NTYyLWIzZmMtMmM5NjNmNjZhZmE2" } } }, "ProactiveActionMutationResponse": { "type": "object", "properties": { "action_uuid": { "type": "string", "description": "Unique identifier of the action that was mutated" }, "updated": { "type": "boolean", "description": "True when the action transitioned state; false when it was already not pending (idempotent no-op)" } }, "example": { "action_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "updated": true } } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "name": "Authorization", "in": "header" } } }, "x-original-swagger-version": "2.0" }