{ "openapi": "3.0.3", "info": { "title": "Giov API", "version": "1.0.0", "description": "The Giov workspace API. Create a key in Settings → MCP & API → API keys and send it as Authorization: Bearer giov_sk_…. Each operation needs the Read or Write permission named in x-giov-permission. Requests run as the person who created the key, within their role. Generated from apps/dashboard/src/lib/api.ts by docs/copilot/dashboard-api/generate.mjs. Guide: https://giovchat.app/docs/api" }, "servers": [ { "url": "https://api.giovchat.app" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "A Giov API key (giov_sk_…)." } } }, "security": [ { "apiKey": [] } ], "paths": { "/v1/admin/agents": { "get": { "operationId": "getAdminAgents", "summary": "Get Admin Agents", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks team:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "team:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/channels": { "get": { "operationId": "getChannels", "summary": "Get Channels", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "available": { "type": "boolean" }, "channel": { "type": "string", "enum": [ "website", "email", "whatsapp", "messenger", "instagram", "telegram" ] }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "displayName": { "type": "string" }, "providerAccountId": { "type": "string" }, "status": { "type": "string", "enum": [ "disconnected", "connecting", "connected", "degraded", "reconnect_required", "error", "disabled" ] }, "mailboxAddress": { "type": "string" }, "lastSyncedAt": { "type": "number" }, "lastError": { "type": "string" }, "automationEnabled": { "type": "boolean" }, "giovbotAgentId": { "type": "string" }, "historyMode": { "type": "string", "enum": [ "new_only", "last_30_days" ] }, "historyStatus": { "type": "string", "enum": [ "completed", "pending", "failed", "idle", "running" ] }, "historyImportedMessages": { "type": "number" }, "tokenExpiresAt": { "type": "number" }, "healthCheckedAt": { "type": "number" }, "lastInboundAt": { "type": "number" }, "lastOutboundAt": { "type": "number" }, "connectedAt": { "type": "number" }, "updatedAt": { "type": "number" }, "capabilities": { "type": "object", "properties": {} } }, "required": [ "channel", "enabled", "status" ] } }, "whatsappTestConnection": { "type": "object", "properties": { "phoneNumberId": { "type": "string" }, "businessAccountId": { "type": "string" } }, "required": [ "phoneNumberId", "businessAccountId" ] } }, "required": [ "channels" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/channels/{channel}": { "patch": { "operationId": "updateChannel", "summary": "Update Channel", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "automationEnabled": { "type": "boolean" }, "giovbotAgentId": { "type": "string" }, "applyTo": { "type": "string", "enum": [ "new_only", "all_bot_owned" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/channels/{channel}/connect/status": { "get": { "operationId": "getChannelConnectionStatus", "summary": "Get Channel Connection Status", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "available": { "type": "boolean" }, "channel": { "type": "string", "enum": [ "website", "email", "whatsapp", "messenger", "instagram", "telegram" ] }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "displayName": { "type": "string" }, "providerAccountId": { "type": "string" }, "status": { "type": "string", "enum": [ "disconnected", "connecting", "connected", "degraded", "reconnect_required", "error", "disabled" ] }, "mailboxAddress": { "type": "string" }, "lastSyncedAt": { "type": "number" }, "lastError": { "type": "string" }, "automationEnabled": { "type": "boolean" }, "giovbotAgentId": { "type": "string" }, "historyMode": { "type": "string", "enum": [ "new_only", "last_30_days" ] }, "historyStatus": { "type": "string", "enum": [ "completed", "pending", "failed", "idle", "running" ] }, "historyImportedMessages": { "type": "number" }, "tokenExpiresAt": { "type": "number" }, "healthCheckedAt": { "type": "number" }, "lastInboundAt": { "type": "number" }, "lastOutboundAt": { "type": "number" }, "connectedAt": { "type": "number" }, "updatedAt": { "type": "number" }, "capabilities": { "type": "object", "properties": { "historyImport": { "type": "boolean" }, "media": { "type": "boolean" }, "replies": { "type": "boolean" }, "quotedReplies": { "type": "boolean" }, "nativeReplies": { "type": "boolean" }, "deliveryStatuses": { "type": "boolean" }, "whatsappTemplates": { "type": "boolean" } } } }, "required": [ "channel", "enabled", "status" ] } }, "required": [ "connection" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/channels/email/mailboxes": { "get": { "operationId": "getEmailMailboxes", "summary": "Get Email Mailboxes", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "limit": { "type": "number" }, "used": { "type": "number" }, "overLimit": { "type": "boolean" }, "canAdd": { "type": "boolean" }, "mailboxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "mailboxAddress": { "type": "string" }, "displayName": { "type": "string" }, "imapHost": { "type": "string" }, "imapPort": { "type": "number" }, "imapSecurity": { "type": "string", "enum": [ "tls", "starttls" ] }, "imapUsername": { "type": "string" }, "smtpHost": { "type": "string" }, "smtpPort": { "type": "number" }, "smtpSecurity": { "type": "string", "enum": [ "tls", "starttls" ] }, "smtpUsername": { "type": "string" }, "credentialsSet": { "type": "boolean" }, "status": { "type": "string", "enum": [ "disconnected", "connecting", "connected", "degraded", "reconnect_required", "error", "disabled" ] }, "lastError": { "type": "string" }, "lastSyncedAt": { "type": "number" }, "connectedAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "mailboxAddress", "displayName", "imapHost", "imapPort", "imapSecurity", "imapUsername", "smtpHost", "smtpPort", "smtpSecurity", "smtpUsername", "credentialsSet", "status", "lastError", "lastSyncedAt", "connectedAt", "updatedAt" ] } } }, "required": [ "enabled", "limit", "used", "overLimit", "canAdd", "mailboxes" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot": { "get": { "operationId": "getCopilotSettings", "summary": "Get Copilot Settings", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "agentId": { "type": "string" }, "issuer": { "type": "string" }, "publicJwk": { "type": "object", "properties": { "kty": { "type": "string", "enum": [ "EC" ] }, "crv": { "type": "string", "enum": [ "P-256" ] }, "x": { "type": "string" }, "y": { "type": "string" } }, "required": [ "kty", "crv", "x", "y" ] }, "origins": { "type": "array", "items": { "type": "string" } }, "allowAutonomousWrites": { "type": "boolean" }, "permissions": { "type": "object", "properties": { "change": { "type": "object", "properties": {} }, "sensitive": { "type": "object", "properties": {} } }, "required": [ "change", "sensitive" ] }, "connections": { "type": "array", "items": { "type": "object", "properties": {} } }, "actions": { "type": "array", "items": { "type": "object", "properties": {} } }, "tasks": { "type": "array", "items": { "type": "object", "properties": {} } }, "activation": { "type": "object", "properties": { "routes": { "type": "object", "properties": {} }, "identity": { "type": "string", "enum": [ "assertion", "user_hash" ] }, "sessionEndpoint": { "type": "string" }, "sidebarSide": { "type": "string", "enum": [ "left", "right" ] }, "layoutTarget": { "type": "string" }, "layout": { "type": "string", "enum": [ "auto", "compact" ] }, "browserOrigins": { "type": "object", "properties": {} }, "learning": { "type": "object", "properties": {} }, "launcher": { "type": "string", "enum": [ "floating", "hidden" ] }, "panelWidth": { "type": "number" } }, "required": [ "routes", "sidebarSide" ] }, "learning": { "type": "object", "properties": { "fromUsers": { "type": "boolean" } }, "required": [ "fromUsers" ] } }, "required": [ "agentId", "issuer", "publicJwk", "origins", "allowAutonomousWrites", "connections", "actions", "tasks" ] }, "revision": { "type": "number" }, "enabled": { "type": "boolean" }, "updatedAt": { "type": "number" }, "credentialConnections": { "type": "array", "items": { "type": "string" } }, "encryptionReady": { "type": "boolean" }, "catalogCounts": { "type": "object", "properties": {} } }, "required": [ "draft", "revision", "enabled", "updatedAt", "credentialConnections", "encryptionReady" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot-learning/endpoints": { "get": { "operationId": "getCopilotLearnedEndpoints", "summary": "Get Copilot Learned Endpoints", "parameters": [], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot-learning/sessions/current": { "get": { "operationId": "getCopilotLearningStatus", "summary": "Get Copilot Learning Status", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "expiresAt": { "type": "number" }, "observed": { "type": "number" } }, "required": [ "active" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/action-index": { "get": { "operationId": "getCopilotActionIndex", "summary": "Get Copilot Action Index", "description": "Where indexing the published actions for Copilot's search stands (the newest job), or null.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "failed", "queued", "running", "succeeded" ] }, "revision": { "type": "number" }, "done": { "type": "number" }, "total": { "type": "number" }, "error": { "type": "string" }, "updatedAt": { "type": "number" } }, "required": [ "status", "revision", "done", "total", "error", "updatedAt" ] } }, "required": [ "index" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/activity": { "get": { "operationId": "getCopilotActivity", "summary": "Get Copilot Activity", "description": "Copilot usage per day in the viewer's time zone, with the previous period.", "parameters": [ { "name": "days", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "timeZone", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "number" }, "timeZone": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "series": { "type": "array", "items": { "type": "object" } }, "totals": { "type": "object", "properties": { "sessions": { "type": "number" }, "chats": { "type": "number" }, "users": { "type": "number" }, "questions": { "type": "number" }, "shortcuts": { "type": "number" }, "actionsSucceeded": { "type": "number" }, "actionsFailed": { "type": "number" }, "confirmations": { "type": "number" }, "failedRuns": { "type": "number" }, "handoffs": { "type": "number" }, "credits": { "type": "number" }, "liked": { "type": "number" }, "disliked": { "type": "number" } }, "required": [ "sessions", "chats", "users", "questions", "shortcuts", "actionsSucceeded", "actionsFailed", "confirmations", "failedRuns", "handoffs", "credits" ] }, "previous": { "type": "object", "properties": { "sessions": { "type": "number" }, "chats": { "type": "number" }, "users": { "type": "number" }, "questions": { "type": "number" }, "shortcuts": { "type": "number" }, "actionsSucceeded": { "type": "number" }, "actionsFailed": { "type": "number" }, "confirmations": { "type": "number" }, "failedRuns": { "type": "number" }, "handoffs": { "type": "number" }, "credits": { "type": "number" }, "liked": { "type": "number" }, "disliked": { "type": "number" } }, "required": [ "sessions", "chats", "users", "questions", "shortcuts", "actionsSucceeded", "actionsFailed", "confirmations", "failedRuns", "handoffs", "credits" ] }, "model": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "ownKey": { "type": "boolean" } }, "required": [ "id", "label", "ownKey" ] }, "transcriptDays": { "type": "number" } }, "required": [ "days", "timeZone", "from", "to", "series", "totals", "previous", "model", "transcriptDays" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/activity/chats": { "get": { "operationId": "listCopilotChats", "summary": "List Copilot Chats", "description": "The Activity log by chat (a chat can continue across sessions and devices).", "parameters": [ { "name": "days", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "timeZone", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "failed", "all", "actions", "confirmation", "shortcuts" ] } }, { "name": "day", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "chats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "subject": { "type": "string" }, "accountId": { "type": "string" }, "origin": { "type": "string" }, "startedAt": { "type": "number" }, "lastActivityAt": { "type": "number" }, "sessionCount": { "type": "number" }, "runs": { "type": "number" }, "questions": { "type": "number" }, "shortcuts": { "type": "number" }, "actions": { "type": "number" }, "failed": { "type": "number" }, "confirmations": { "type": "number" }, "credits": { "type": "number" }, "preview": { "type": "string" }, "handoffConversationId": { "type": "string" } }, "required": [ "id", "subject", "accountId", "origin", "startedAt", "lastActivityAt", "sessionCount", "runs", "questions", "shortcuts", "actions", "failed", "confirmations", "credits", "preview", "handoffConversationId" ] } }, "hasMore": { "type": "boolean" } }, "required": [ "chats", "hasMore" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/activity/chats/{id}": { "get": { "operationId": "getCopilotChat", "summary": "Get Copilot Chat", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "turns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "number" }, "sessionId": { "type": "string" }, "shortcut": { "type": "string" }, "question": { "type": "string" }, "reply": { "type": "string" }, "status": { "type": "string" }, "errorCode": { "type": "string" }, "neededConfirmation": { "type": "boolean" }, "actions": { "type": "object", "properties": {} }, "credits": { "type": "number" }, "feedback": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "id", "at", "sessionId", "shortcut", "question", "reply", "status", "errorCode", "neededConfirmation", "actions", "credits" ] } }, "transcriptDays": { "type": "number" } }, "required": [ "turns", "transcriptDays" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/activity/feedback": { "get": { "operationId": "listCopilotFeedback", "summary": "List Copilot Feedback", "description": "Replies their users rated (disliked by default), newest rating first, with the up/down counts.", "parameters": [ { "name": "days", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "timeZone", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "rating", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "all", "up", "down" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "up": { "type": "number" }, "down": { "type": "number" }, "rating": { "type": "string", "enum": [ "all", "up", "down" ] }, "replies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "chatId": { "type": "string" }, "sessionId": { "type": "string" }, "subject": { "type": "string" }, "rating": { "type": "string", "enum": [ "up", "down" ] }, "at": { "type": "number" }, "ratedAt": { "type": "number" }, "shortcut": { "type": "string" }, "question": { "type": "string" }, "reply": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "chatId", "sessionId", "subject", "rating", "at", "ratedAt", "shortcut", "question", "reply", "status" ] } }, "hasMore": { "type": "boolean" }, "transcriptDays": { "type": "number" } }, "required": [ "up", "down", "rating", "replies", "hasMore", "transcriptDays" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/catalog/entries": { "get": { "operationId": "getCopilotCatalogEntries", "summary": "Get Copilot Catalog Entries", "description": "One page of a connection's catalog: filtered, sorted and counted on the server.", "parameters": [ { "name": "connectionId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "access", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectionId": { "type": "string" }, "sourceId": { "type": "string" }, "identity": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "removed", "conflict" ] }, "data": { "type": "object", "properties": {} }, "imported": { "type": "object", "properties": {} }, "manualFields": { "type": "object", "properties": {} }, "conflicts": { "type": "object", "properties": {} }, "lastSyncedAt": { "type": "number" } }, "required": [ "id", "connectionId", "sourceId", "identity", "status", "data", "imported", "manualFields", "conflicts", "lastSyncedAt" ] } }, "total": { "type": "number" }, "all": { "type": "number" }, "approved": { "type": "number" }, "pending": { "type": "number" }, "pendingLevels": { "type": "object", "properties": { "read": { "type": "number" }, "write": { "type": "number" }, "high": { "type": "number" } }, "required": [ "read", "write", "high" ] }, "updatedAt": { "type": "number" } }, "required": [ "entries", "total", "all", "approved", "pending", "pendingLevels", "updatedAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/catalog/entries/{entryId}": { "get": { "operationId": "getCopilotCatalogEntry", "summary": "Get Copilot Catalog Entry", "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "id": { "type": "string" }, "connectionId": { "type": "string" }, "sourceId": { "type": "string" }, "identity": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "removed", "conflict" ] }, "data": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "http", "mcp" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS" ] }, "url": { "type": "string" }, "path": { "type": "string" }, "toolName": { "type": "string" }, "headers": { "type": "object", "properties": {} }, "request": { "type": "object", "properties": {} }, "response": { "type": "object", "properties": {} }, "responses": { "type": "object", "properties": {} }, "suggestedAction": { "type": "object", "properties": {} } }, "required": [ "transport", "name", "headers" ] }, "imported": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "http", "mcp" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS" ] }, "url": { "type": "string" }, "path": { "type": "string" }, "toolName": { "type": "string" }, "headers": { "type": "object", "properties": {} }, "request": { "type": "object", "properties": {} }, "response": { "type": "object", "properties": {} }, "responses": { "type": "object", "properties": {} }, "suggestedAction": { "type": "object", "properties": {} } }, "required": [ "transport", "name", "headers" ] }, "manualFields": { "type": "array", "items": { "type": "string", "enum": [ "url", "name", "transport", "description", "method", "path", "toolName", "headers", "request", "response", "responses", "suggestedAction" ] } }, "conflicts": { "type": "array", "items": { "type": "string", "enum": [ "url", "name", "transport", "description", "method", "path", "toolName", "headers", "request", "response", "responses", "suggestedAction" ] } }, "lastSyncedAt": { "type": "number" } }, "required": [ "id", "connectionId", "sourceId", "identity", "status", "data", "imported", "manualFields", "conflicts", "lastSyncedAt" ] } }, "required": [ "entry" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/catalog/sources": { "get": { "operationId": "getCopilotCatalogSources", "summary": "Get Copilot Catalog Sources", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object" } }, "updatedAt": { "type": "number" } }, "required": [ "sources", "updatedAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/copilot/runs": { "get": { "operationId": "getCopilotRuns", "summary": "Get Copilot Runs", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "status": { "type": "string" }, "step": { "type": "number" }, "revision": { "type": "number" }, "errorCode": { "type": "string" }, "createdAt": { "type": "number" }, "attempts": { "type": "object", "properties": {} } }, "required": [ "id", "taskId", "status", "step", "revision", "errorCode", "createdAt", "attempts" ] } } }, "required": [ "runs" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks copilot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "copilot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot": { "get": { "operationId": "getGiovBotWorkspace", "summary": "Get Giov Bot Workspace", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents": { "post": { "operationId": "createGiovBotAgent", "summary": "Create Giov Bot Agent", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "firstMessage": { "type": "string" }, "enable": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } }, "required": [ "agent" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}": { "delete": { "operationId": "archiveGiovBotAgent", "summary": "Archive Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "object", "properties": {} }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": {} }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": {} }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } } }, "required": [ "agents" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] }, "get": { "operationId": "getGiovBotAgent", "summary": "Get Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] }, "procedures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "instructions": { "type": "string" }, "keywords": { "type": "object", "properties": {} }, "targetType": { "type": "string", "enum": [ "ai_agent", "inbox", "department", "teammate" ] }, "targetId": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "instructions", "keywords", "targetType", "targetId", "createdAt", "updatedAt" ] } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "transport": { "type": "string", "enum": [ "mcp", "webhook" ] }, "mcpToolName": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "headerNames": { "type": "object", "properties": {} }, "hasSigningSecret": { "type": "boolean" }, "allowWrites": { "type": "boolean" }, "schema": { "type": "object", "properties": {} }, "executions": { "type": "number" }, "successPercent": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "description", "transport", "mcpToolName", "method", "url", "headerNames", "hasSigningSecret", "allowWrites", "schema", "executions", "successPercent", "createdAt", "updatedAt" ] } }, "variables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "object", "list", "null" ] }, "scope": { "type": "string", "enum": [ "workspace", "agent" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "agentId", "name", "value", "valueType", "scope", "createdAt", "updatedAt" ] } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "librarySources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "toolRuns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "toolId": { "type": "string" }, "toolName": { "type": "string" }, "conversationId": { "type": "string" }, "success": { "type": "boolean" }, "statusCode": { "type": "number" }, "errorMessage": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "id", "toolId", "toolName", "conversationId", "success", "statusCode", "errorMessage", "createdAt" ] } }, "llm": { "type": "object", "properties": { "platformModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokConfigured": { "type": "boolean" }, "byokProvider": { "type": "string" }, "byoAiKeyAllowed": { "type": "boolean" }, "creditsLimit": { "type": "number" }, "creditsUsed": { "type": "number" }, "publishedLimit": { "type": "number" }, "allowedChannels": { "type": "array", "items": { "type": "string" } } }, "required": [ "platformModels", "byokModels", "byokConfigured", "byokProvider", "byoAiKeyAllowed", "creditsLimit", "creditsUsed", "publishedLimit", "allowedChannels" ] }, "giovbotCanEnable": { "type": "boolean" }, "workspaceGiovbotEnabled": { "type": "boolean" } }, "required": [ "agent", "procedures", "tools", "variables", "sources", "librarySources", "jobs", "sourceIds", "toolRuns", "llm", "giovbotCanEnable", "workspaceGiovbotEnabled" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "patchGiovBotAgent", "summary": "Patch Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] }, "procedures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "instructions": { "type": "string" }, "keywords": { "type": "object", "properties": {} }, "targetType": { "type": "string", "enum": [ "ai_agent", "inbox", "department", "teammate" ] }, "targetId": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "instructions", "keywords", "targetType", "targetId", "createdAt", "updatedAt" ] } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "transport": { "type": "string", "enum": [ "mcp", "webhook" ] }, "mcpToolName": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "headerNames": { "type": "object", "properties": {} }, "hasSigningSecret": { "type": "boolean" }, "allowWrites": { "type": "boolean" }, "schema": { "type": "object", "properties": {} }, "executions": { "type": "number" }, "successPercent": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "description", "transport", "mcpToolName", "method", "url", "headerNames", "hasSigningSecret", "allowWrites", "schema", "executions", "successPercent", "createdAt", "updatedAt" ] } }, "variables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "object", "list", "null" ] }, "scope": { "type": "string", "enum": [ "workspace", "agent" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "agentId", "name", "value", "valueType", "scope", "createdAt", "updatedAt" ] } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "librarySources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "toolRuns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "toolId": { "type": "string" }, "toolName": { "type": "string" }, "conversationId": { "type": "string" }, "success": { "type": "boolean" }, "statusCode": { "type": "number" }, "errorMessage": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "id", "toolId", "toolName", "conversationId", "success", "statusCode", "errorMessage", "createdAt" ] } }, "llm": { "type": "object", "properties": { "platformModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokConfigured": { "type": "boolean" }, "byokProvider": { "type": "string" }, "byoAiKeyAllowed": { "type": "boolean" }, "creditsLimit": { "type": "number" }, "creditsUsed": { "type": "number" }, "publishedLimit": { "type": "number" }, "allowedChannels": { "type": "array", "items": { "type": "string" } } }, "required": [ "platformModels", "byokModels", "byokConfigured", "byokProvider", "byoAiKeyAllowed", "creditsLimit", "creditsUsed", "publishedLimit", "allowedChannels" ] }, "giovbotCanEnable": { "type": "boolean" }, "workspaceGiovbotEnabled": { "type": "boolean" } }, "required": [ "agent", "procedures", "tools", "variables", "sources", "librarySources", "jobs", "sourceIds", "toolRuns", "llm", "giovbotCanEnable", "workspaceGiovbotEnabled" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/deactivate": { "post": { "operationId": "deactivateGiovBotAgent", "summary": "Deactivate Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } }, "required": [ "agent" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/default": { "post": { "operationId": "setDefaultGiovBotAgent", "summary": "Set Default Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "object", "properties": {} }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": {} }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": {} }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } } }, "required": [ "agents" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/discard-draft": { "post": { "operationId": "discardGiovBotDraft", "summary": "Discard Giov Bot Draft", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } }, "required": [ "agent" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/duplicate": { "post": { "operationId": "duplicateGiovBotAgent", "summary": "Duplicate Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } }, "required": [ "agent" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/export": { "get": { "operationId": "exportGiovBotAgent", "summary": "Export Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "giovbot-agent" ] }, "version": { "type": "number" }, "exportedAt": { "type": "number" }, "agent": { "type": "object", "properties": {} }, "resources": { "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "object" } }, "procedures": { "type": "array", "items": { "type": "object" } }, "tools": { "type": "array", "items": { "type": "object" } }, "knowledge": { "type": "array", "items": { "type": "object" } }, "testCases": { "type": "array", "items": { "type": "object" } } }, "required": [ "variables", "procedures", "tools", "knowledge", "testCases" ] } }, "required": [ "format", "version", "exportedAt", "agent", "resources" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/preview": { "post": { "operationId": "previewGiovBotAgent", "summary": "Preview Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": [ "role", "content" ] } } }, "required": [ "message" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string" }, "usedFallback": { "type": "boolean" }, "handoff": { "type": "boolean" }, "confidence": { "type": "number" }, "model": { "type": "string" }, "reason": { "type": "string" }, "procedureId": { "type": "string" }, "toolId": { "type": "string" }, "knowledge": { "type": "array", "items": { "type": "string" } }, "blocks": { "type": "array", "items": { "type": "object", "properties": {} } } }, "required": [ "reply", "usedFallback", "handoff", "confidence", "model", "reason" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/procedures": { "post": { "operationId": "createGiovBotProcedure", "summary": "Create Giov Bot Procedure", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "procedures": { "type": "array", "items": { "type": "object" } } }, "required": [ "procedures" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/procedures/{id}": { "delete": { "operationId": "deleteGiovBotProcedure", "summary": "Delete Giov Bot Procedure", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "procedures": { "type": "array", "items": { "type": "object" } } }, "required": [ "procedures" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "patchGiovBotProcedure", "summary": "Patch Giov Bot Procedure", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "procedures": { "type": "array", "items": { "type": "object" } } }, "required": [ "procedures" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/publish": { "post": { "operationId": "publishGiovBotAgent", "summary": "Publish Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } }, "required": [ "agent" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/rag-test": { "post": { "operationId": "testGiovBotRag", "summary": "Test Giov Bot Rag", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "chunks": { "type": "array", "items": { "type": "object", "properties": {} } } }, "required": [ "chunks" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/rollback": { "post": { "operationId": "rollbackGiovBotAgent", "summary": "Rollback Giov Bot Agent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "versionId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } }, "required": [ "agent" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/sources/{sourceId}": { "delete": { "operationId": "detachGiovBotSource", "summary": "Detach Giov Bot Source", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] }, "procedures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "instructions": { "type": "string" }, "keywords": { "type": "object", "properties": {} }, "targetType": { "type": "string", "enum": [ "ai_agent", "inbox", "department", "teammate" ] }, "targetId": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "instructions", "keywords", "targetType", "targetId", "createdAt", "updatedAt" ] } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "transport": { "type": "string", "enum": [ "mcp", "webhook" ] }, "mcpToolName": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "headerNames": { "type": "object", "properties": {} }, "hasSigningSecret": { "type": "boolean" }, "allowWrites": { "type": "boolean" }, "schema": { "type": "object", "properties": {} }, "executions": { "type": "number" }, "successPercent": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "description", "transport", "mcpToolName", "method", "url", "headerNames", "hasSigningSecret", "allowWrites", "schema", "executions", "successPercent", "createdAt", "updatedAt" ] } }, "variables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "object", "list", "null" ] }, "scope": { "type": "string", "enum": [ "workspace", "agent" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "agentId", "name", "value", "valueType", "scope", "createdAt", "updatedAt" ] } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "librarySources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "toolRuns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "toolId": { "type": "string" }, "toolName": { "type": "string" }, "conversationId": { "type": "string" }, "success": { "type": "boolean" }, "statusCode": { "type": "number" }, "errorMessage": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "id", "toolId", "toolName", "conversationId", "success", "statusCode", "errorMessage", "createdAt" ] } }, "llm": { "type": "object", "properties": { "platformModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokConfigured": { "type": "boolean" }, "byokProvider": { "type": "string" }, "byoAiKeyAllowed": { "type": "boolean" }, "creditsLimit": { "type": "number" }, "creditsUsed": { "type": "number" }, "publishedLimit": { "type": "number" }, "allowedChannels": { "type": "array", "items": { "type": "string" } } }, "required": [ "platformModels", "byokModels", "byokConfigured", "byokProvider", "byoAiKeyAllowed", "creditsLimit", "creditsUsed", "publishedLimit", "allowedChannels" ] }, "giovbotCanEnable": { "type": "boolean" }, "workspaceGiovbotEnabled": { "type": "boolean" } }, "required": [ "agent", "procedures", "tools", "variables", "sources", "librarySources", "jobs", "sourceIds", "toolRuns", "llm", "giovbotCanEnable", "workspaceGiovbotEnabled" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/sources/{sourceId}/attach": { "post": { "operationId": "attachGiovBotSource", "summary": "Attach Giov Bot Source", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": { "model": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "byok" ] }, "backupMode": { "type": "string", "enum": [ "custom", "default", "disabled" ] }, "backupModel": { "type": "string" }, "temperature": { "type": "number" }, "sendTemperature": { "type": "boolean" }, "maxTokens": { "type": "number" }, "reasoningEffort": { "type": "string", "enum": [ "low", "high", "default", "minimal", "medium" ] }, "reasoningSummary": { "type": "boolean" } }, "required": [ "model", "source", "backupMode", "backupModel", "temperature", "sendTemperature", "maxTokens", "reasoningEffort", "reasoningSummary" ] }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": { "supportedLanguages": { "type": "object", "properties": {} }, "attachments": { "type": "object", "properties": {} }, "schedule": { "type": "object", "properties": {} } }, "required": [ "supportedLanguages", "attachments", "schedule" ] }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": { "focusEnabled": { "type": "boolean" }, "confidenceThreshold": { "type": "number" }, "blockedTopics": { "type": "object", "properties": {} }, "neverInvent": { "type": "boolean" }, "content": { "type": "object", "properties": {} }, "custom": { "type": "object", "properties": {} }, "customRules": { "type": "string" }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "inbox", "department", "teammate" ] }, "handoffTargetId": { "type": "string" }, "systemTools": { "type": "object", "properties": {} } }, "required": [ "focusEnabled", "confidenceThreshold", "blockedTopics", "neverInvent", "content", "custom", "customRules", "fallbackMessage", "handoffTarget", "handoffTargetId", "systemTools" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] }, "procedures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "instructions": { "type": "string" }, "keywords": { "type": "object", "properties": {} }, "targetType": { "type": "string", "enum": [ "ai_agent", "inbox", "department", "teammate" ] }, "targetId": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "instructions", "keywords", "targetType", "targetId", "createdAt", "updatedAt" ] } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "transport": { "type": "string", "enum": [ "mcp", "webhook" ] }, "mcpToolName": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "headerNames": { "type": "object", "properties": {} }, "hasSigningSecret": { "type": "boolean" }, "allowWrites": { "type": "boolean" }, "schema": { "type": "object", "properties": {} }, "executions": { "type": "number" }, "successPercent": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "description", "transport", "mcpToolName", "method", "url", "headerNames", "hasSigningSecret", "allowWrites", "schema", "executions", "successPercent", "createdAt", "updatedAt" ] } }, "variables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "object", "list", "null" ] }, "scope": { "type": "string", "enum": [ "workspace", "agent" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "agentId", "name", "value", "valueType", "scope", "createdAt", "updatedAt" ] } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "librarySources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "toolRuns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "toolId": { "type": "string" }, "toolName": { "type": "string" }, "conversationId": { "type": "string" }, "success": { "type": "boolean" }, "statusCode": { "type": "number" }, "errorMessage": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "id", "toolId", "toolName", "conversationId", "success", "statusCode", "errorMessage", "createdAt" ] } }, "llm": { "type": "object", "properties": { "platformModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokModels": { "type": "array", "items": { "type": "object", "properties": {} } }, "byokConfigured": { "type": "boolean" }, "byokProvider": { "type": "string" }, "byoAiKeyAllowed": { "type": "boolean" }, "creditsLimit": { "type": "number" }, "creditsUsed": { "type": "number" }, "publishedLimit": { "type": "number" }, "allowedChannels": { "type": "array", "items": { "type": "string" } } }, "required": [ "platformModels", "byokModels", "byokConfigured", "byokProvider", "byoAiKeyAllowed", "creditsLimit", "creditsUsed", "publishedLimit", "allowedChannels" ] }, "giovbotCanEnable": { "type": "boolean" }, "workspaceGiovbotEnabled": { "type": "boolean" } }, "required": [ "agent", "procedures", "tools", "variables", "sources", "librarySources", "jobs", "sourceIds", "toolRuns", "llm", "giovbotCanEnable", "workspaceGiovbotEnabled" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/spotlight": { "get": { "operationId": "getGiovBotSpotlight", "summary": "Get Giov Bot Spotlight", "description": "Days are cut in `timeZone` (the viewer's), so \"today\" matches their calendar.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "timeZone", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "number" }, "timeZone": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "unpublishedChanges": { "type": "boolean" }, "totals": { "type": "object", "properties": { "conversations": { "type": "number" }, "success": { "type": "number" }, "handoffs": { "type": "number" }, "open": { "type": "number" }, "fallbacks": { "type": "number" }, "replies": { "type": "number" }, "successRate": { "type": "number" }, "handoffRate": { "type": "number" }, "fallbackRate": { "type": "number" }, "avgLatencyMs": { "type": "number" }, "avgDurationMs": { "type": "number" }, "credits": { "type": "number" } }, "required": [ "conversations", "success", "handoffs", "open", "fallbacks", "replies", "successRate", "handoffRate", "fallbackRate", "avgLatencyMs", "avgDurationMs", "credits" ] }, "previous": { "type": "object", "properties": { "conversations": { "type": "number" }, "success": { "type": "number" }, "handoffs": { "type": "number" }, "open": { "type": "number" }, "fallbacks": { "type": "number" }, "replies": { "type": "number" }, "successRate": { "type": "number" }, "handoffRate": { "type": "number" }, "fallbackRate": { "type": "number" }, "avgLatencyMs": { "type": "number" }, "avgDurationMs": { "type": "number" }, "credits": { "type": "number" } }, "required": [ "conversations", "success", "handoffs", "open", "fallbacks", "replies", "successRate", "handoffRate", "fallbackRate", "avgLatencyMs", "avgDurationMs", "credits" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "conversations": { "type": "number" }, "success": { "type": "number" }, "handoffs": { "type": "number" }, "open": { "type": "number" }, "fallbacks": { "type": "number" }, "replies": { "type": "number" }, "credits": { "type": "number" }, "avgDurationMs": { "type": "number" }, "avgLatencyMs": { "type": "number" }, "byModel": { "type": "object", "properties": {} } }, "required": [ "day", "conversations", "success", "handoffs", "open", "fallbacks", "replies", "credits", "avgDurationMs", "avgLatencyMs", "byModel" ] } }, "models": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "model", "other", "unknown" ] }, "label": { "type": "string" }, "provider": { "type": "string" }, "replies": { "type": "number" }, "share": { "type": "number" }, "credits": { "type": "number" }, "ownKey": { "type": "boolean" } }, "required": [ "key", "kind", "label", "provider", "replies", "share", "credits", "ownKey" ] } }, "topics": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } }, "procedures": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": {} } }, "unmatched": { "type": "number" }, "total": { "type": "number" } }, "required": [ "items", "unmatched", "total" ] }, "alerts": { "type": "object", "properties": { "unpublishedChanges": { "type": "boolean" }, "failedJobs": { "type": "number" }, "recentHandoffIds": { "type": "array", "items": { "type": "string" } }, "waitingHandoffs": { "type": "array", "items": { "type": "object", "properties": {} } }, "waitingCount": { "type": "number" } }, "required": [ "unpublishedChanges", "failedJobs", "recentHandoffIds" ] } }, "required": [ "days", "timeZone", "from", "to", "unpublishedChanges", "totals", "previous", "series", "models", "topics", "alerts" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/system-prompt": { "post": { "operationId": "generateGiovBotSystemPrompt", "summary": "Generate Giov Bot System Prompt", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstMessage": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "systemPrompt": { "type": "string" }, "generatedBy": { "type": "string", "enum": [ "ai", "template" ] } }, "required": [ "systemPrompt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/tests": { "get": { "operationId": "listGiovBotTests", "summary": "List Giov Bot Tests", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "messages": { "type": "object", "properties": {} }, "expectContains": { "type": "string" }, "expectNotContains": { "type": "string" }, "expectHandoff": { "type": "boolean" }, "expectProcedureId": { "type": "string" }, "expectToolId": { "type": "string" }, "mockToolResponse": { "type": "string" }, "lastRun": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "messages", "expectContains", "expectNotContains", "expectHandoff", "expectProcedureId", "expectToolId", "mockToolResponse", "lastRun", "createdAt", "updatedAt" ] } } }, "required": [ "tests" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "createGiovBotTest", "summary": "Create Giov Bot Test", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "messages": { "type": "object", "properties": {} }, "expectContains": { "type": "string" }, "expectNotContains": { "type": "string" }, "expectHandoff": { "type": "boolean" }, "expectProcedureId": { "type": "string" }, "expectToolId": { "type": "string" }, "mockToolResponse": { "type": "string" }, "lastRun": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "messages", "expectContains", "expectNotContains", "expectHandoff", "expectProcedureId", "expectToolId", "mockToolResponse", "lastRun", "createdAt", "updatedAt" ] } } }, "required": [ "tests" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/tests/{id}": { "delete": { "operationId": "deleteGiovBotTest", "summary": "Delete Giov Bot Test", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "messages": { "type": "object", "properties": {} }, "expectContains": { "type": "string" }, "expectNotContains": { "type": "string" }, "expectHandoff": { "type": "boolean" }, "expectProcedureId": { "type": "string" }, "expectToolId": { "type": "string" }, "mockToolResponse": { "type": "string" }, "lastRun": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "messages", "expectContains", "expectNotContains", "expectHandoff", "expectProcedureId", "expectToolId", "mockToolResponse", "lastRun", "createdAt", "updatedAt" ] } } }, "required": [ "tests" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/tests/{id}/run": { "post": { "operationId": "runGiovBotTest", "summary": "Run Giov Bot Test", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/tests/run-all": { "post": { "operationId": "runAllGiovBotTests", "summary": "Run All Giov Bot Tests", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } } }, "required": [ "results" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/agents/{agentId}/versions": { "get": { "operationId": "getGiovBotAgentVersions", "summary": "Get Giov Bot Agent Versions", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "number" }, "publishedAt": { "type": "number" }, "kind": { "type": "string", "enum": [ "publish", "rollback", "baseline" ] }, "isCurrent": { "type": "boolean" }, "canRollback": { "type": "boolean" }, "rollbackExpiresAt": { "type": "number" }, "restoredFromVersionId": { "type": "string" } }, "required": [ "id", "version", "publishedAt", "kind", "isCurrent", "canRollback", "rollbackExpiresAt", "restoredFromVersionId" ] } }, "rollbackExpiresAt": { "type": "number" }, "targetVersionId": { "type": "string" } }, "required": [ "versions", "rollbackExpiresAt", "targetVersionId" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/config": { "patch": { "operationId": "patchGiovBotConfig", "summary": "Patch Giov Bot Config", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/llm/provider-models": { "get": { "operationId": "getGiovBotProviderModels", "summary": "Get Giov Bot Provider Models", "description": "Every chat model the workspace's own provider key can call, read live from the provider.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ] } }, "error": { "type": "string" } }, "required": [ "provider", "models" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/sources/{id}": { "delete": { "operationId": "deleteGiovBotSource", "summary": "Delete Giov Bot Source", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/sources/{id}/resync": { "post": { "operationId": "resyncGiovBotSource", "summary": "Resync Giov Bot Source", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/sources/{sourceId}": { "patch": { "operationId": "patchGiovBotSourceRag", "summary": "Patch Giov Bot Source Rag", "parameters": [ { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxPages": { "type": "number" }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/sources/{sourceId}/pages": { "delete": { "operationId": "excludeGiovBotSourcePage", "summary": "Exclude Giov Bot Source Page", "parameters": [ { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/sources/text": { "post": { "operationId": "createGiovBotTextSource", "summary": "Create Giov Bot Text Source", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "content": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "markdown", "csv" ] }, "agentId": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/sources/url": { "post": { "operationId": "queueGiovBotWebsite", "summary": "Queue Giov Bot Website", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "published": { "type": "boolean" }, "name": { "type": "string" }, "businessType": { "type": "string", "enum": [ "general", "service", "store" ] }, "primaryWebsiteUrl": { "type": "string" }, "avatarUrl": { "type": "string" }, "promise": { "type": "string" }, "supportedChannels": { "type": "array", "items": { "type": "string" } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": {} } }, "starterFaqs": { "type": "array", "items": { "type": "object", "properties": {} } }, "tone": { "type": "string", "enum": [ "helpful", "concise", "sales", "technical" ] }, "responseStyle": { "type": "string", "enum": [ "conversational", "structured" ] }, "answerLength": { "type": "string", "enum": [ "short", "balanced", "detailed" ] }, "businessHoursMode": { "type": "string", "enum": [ "always", "business-hours" ] }, "confidenceThreshold": { "type": "number" }, "escalationKeywords": { "type": "array", "items": { "type": "string" } }, "fallbackMessage": { "type": "string" }, "handoffTarget": { "type": "string", "enum": [ "team", "inbox" ] }, "assignAgentId": { "type": "string" }, "captureVisitorDetails": { "type": "boolean" } }, "required": [ "enabled", "published", "name", "businessType", "primaryWebsiteUrl", "avatarUrl", "promise", "supportedChannels", "knowledgeSources", "starterFaqs", "tone", "responseStyle", "answerLength", "businessHoursMode", "confidenceThreshold", "escalationKeywords", "fallbackMessage", "handoffTarget", "assignAgentId", "captureVisitorDetails" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document", "text", "url", "faq" ] }, "label": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "draft", "ready", "syncing" ] }, "contextCount": { "type": "number" }, "updatedAt": { "type": "number" }, "lastProcessedAt": { "type": "number" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "id", "type", "label", "status" ] } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "jobType": { "type": "string", "enum": [ "document", "crawl", "faq_import" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "queued", "running" ] }, "progressMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "stats": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "id", "sourceId", "sourceLabel", "jobType", "status", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "config", "sources", "jobs", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/studio": { "get": { "operationId": "getGiovBotStudio", "summary": "Get Giov Bot Studio", "description": "Full studio payload. Admin-only: agent-role users receive the redacted shape (see getGiovBotStudioAgents).", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "canEnable": { "type": "boolean" }, "byoAiKeyAllowed": { "type": "boolean" }, "byokConfigured": { "type": "boolean" }, "creditsLimit": { "type": "number" }, "publishedLimit": { "type": "number" }, "setup": { "type": "object", "properties": { "agentId": { "type": "string" }, "confirmed": { "type": "array", "items": { "type": "string", "enum": [ "personality", "try" ] } }, "dismissed": { "type": "boolean" } }, "required": [ "agentId", "confirmed", "dismissed" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "language": { "type": "string" }, "firstMessage": { "type": "string" }, "systemPrompt": { "type": "string" }, "examples": { "type": "object", "properties": {} }, "tone": { "type": "string" }, "responseStyle": { "type": "string" }, "answerLength": { "type": "string" }, "modelOverride": { "type": "string" }, "llm": { "type": "object", "properties": {} }, "channelBehavior": { "type": "object", "properties": {} }, "settings": { "type": "object", "properties": {} }, "isDefault": { "type": "boolean" }, "published": { "type": "boolean" }, "unpublishedChanges": { "type": "boolean" }, "guardrails": { "type": "object", "properties": {} }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "tenantId", "name", "role", "avatarUrl", "language", "firstMessage", "systemPrompt", "examples", "tone", "responseStyle", "answerLength", "modelOverride", "isDefault", "published", "unpublishedChanges", "guardrails", "createdAt", "updatedAt" ] } }, "summary": { "type": "object", "properties": { "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "readySources", "syncingSources", "failedSources", "totalContexts", "pendingJobs" ] } }, "required": [ "enabled", "canEnable", "byoAiKeyAllowed", "creditsLimit", "publishedLimit", "agents", "summary" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/triage": { "get": { "operationId": "getGiovbotTriage", "summary": "Get Giovbot Triage", "description": "GiovBot automatic priority settings; `entitled` is false when the plan does not include it.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "triage": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "rules": { "type": "string" }, "notifyUrgent": { "type": "boolean" } }, "required": [ "enabled", "rules", "notifyUrgent" ] }, "entitled": { "type": "boolean" } }, "required": [ "triage", "entitled" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:read", "security": [ { "apiKey": [] } ] }, "put": { "operationId": "updateGiovbotTriage", "summary": "Update Giovbot Triage", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "rules": { "type": "string" }, "notifyUrgent": { "type": "boolean" } }, "required": [ "enabled", "rules", "notifyUrgent" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "triage": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "rules": { "type": "string" }, "notifyUrgent": { "type": "boolean" } }, "required": [ "enabled", "rules", "notifyUrgent" ] }, "entitled": { "type": "boolean" } }, "required": [ "triage", "entitled" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/variables": { "post": { "operationId": "createGiovBotVariable", "summary": "Create Giov Bot Variable", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "object", "list", "null" ] }, "agentId": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "object", "list", "null" ] }, "scope": { "type": "string", "enum": [ "workspace", "agent" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "agentId", "name", "value", "valueType", "scope", "createdAt", "updatedAt" ] } } }, "required": [ "variables" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/variables/{id}": { "delete": { "operationId": "deleteGiovBotVariable", "summary": "Delete Giov Bot Variable", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "patchGiovBotVariable", "summary": "Patch Giov Bot Variable", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean", "object", "list", "null" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/giovbot/workspace": { "patch": { "operationId": "patchGiovBotWorkspace", "summary": "Patch Giov Bot Workspace", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setup": { "type": "object", "properties": { "agentId": { "type": "string" }, "confirmed": { "type": "array", "items": { "type": "string", "enum": [ "personality", "try" ] } }, "dismissed": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "canEnable": { "type": "boolean" }, "setup": { "type": "object", "properties": { "agentId": { "type": "string" }, "confirmed": { "type": "array", "items": { "type": "string", "enum": [ "personality", "try" ] } }, "dismissed": { "type": "boolean" } }, "required": [ "agentId", "confirmed", "dismissed" ] } }, "required": [ "enabled", "canEnable", "setup" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks giovbot:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "giovbot:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/google-analytics": { "get": { "operationId": "getGoogleAnalytics", "summary": "Get Google Analytics", "description": "Google Analytics 4 connection (admins; Business and Advanced). Never returns the API secret.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "plan": { "type": "string" }, "configured": { "type": "boolean" }, "measurementId": { "type": "string" }, "hasSecret": { "type": "boolean" }, "enabled": { "type": "boolean" }, "includeMessaging": { "type": "boolean" }, "lastTestAt": { "type": "number" }, "lastTestOk": { "type": "boolean" }, "updatedAt": { "type": "number" } }, "required": [ "available", "plan", "configured", "measurementId", "hasSecret", "enabled", "includeMessaging", "lastTestAt", "lastTestOk", "updatedAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/invitations/{id}": { "delete": { "operationId": "revokeInvitation", "summary": "Revoke Invitation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks team:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "team:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/invitations/{id}/resend": { "post": { "operationId": "resendInvitation", "summary": "Resend Invitation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "inviteToken": { "type": "string" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks team:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "team:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/settings": { "get": { "operationId": "getAdminSettings", "summary": "Get Admin Settings", "parameters": [], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "patchAdminSettings", "summary": "Patch Admin Settings", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyName": { "type": "object" }, "useCase": { "type": "object" }, "defaultAgentName": { "type": "object" }, "defaultAgentAvatar": { "type": "object" }, "widget": { "type": "object" }, "businessHours": { "type": "object" }, "autoReply": { "type": "object" } }, "additionalProperties": { "type": "string" } } } } }, "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/widget/identifiers": { "get": { "operationId": "getWidgetIdentifiers", "summary": "Get Widget Identifiers", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "id", "type", "value", "createdAt" ] } } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/widget/identifiers/{id}": { "delete": { "operationId": "deleteWidgetIdentifier", "summary": "Delete Widget Identifier", "description": "Removes an allowed domain or app; with none left the widget loads on any website.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "ok", "id" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/widget/identity": { "get": { "operationId": "getWidgetIdentity", "summary": "Get Widget Identity", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "required": { "type": "boolean" } }, "required": [ "configured", "required" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:read", "security": [ { "apiKey": [] } ] } }, "/v1/admin/widget/push": { "get": { "operationId": "getVisitorPush", "summary": "Get Visitor Push", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storageReady": { "type": "boolean" }, "showMessageText": { "type": "boolean" }, "apns": { "type": "object", "properties": { "keyId": { "type": "string" }, "teamId": { "type": "string" }, "bundleId": { "type": "string" }, "lastError": { "type": "string" }, "lastErrorAt": { "type": "number" } }, "required": [ "keyId", "teamId", "bundleId", "lastError", "lastErrorAt" ] }, "fcm": { "type": "object", "properties": { "projectId": { "type": "string" }, "clientEmail": { "type": "string" }, "lastError": { "type": "string" }, "lastErrorAt": { "type": "number" } }, "required": [ "projectId", "clientEmail", "lastError", "lastErrorAt" ] }, "devices": { "type": "object", "properties": { "apns": { "type": "number" }, "fcm": { "type": "number" } }, "required": [ "apns", "fcm" ] } }, "required": [ "storageReady", "showMessageText", "apns", "fcm", "devices" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "setVisitorPushShowMessageText", "summary": "Set Visitor Push Show Message Text", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "showMessageText": { "type": "boolean" } }, "required": [ "showMessageText" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storageReady": { "type": "boolean" }, "showMessageText": { "type": "boolean" }, "apns": { "type": "object", "properties": { "keyId": { "type": "string" }, "teamId": { "type": "string" }, "bundleId": { "type": "string" }, "lastError": { "type": "string" }, "lastErrorAt": { "type": "number" } }, "required": [ "keyId", "teamId", "bundleId", "lastError", "lastErrorAt" ] }, "fcm": { "type": "object", "properties": { "projectId": { "type": "string" }, "clientEmail": { "type": "string" }, "lastError": { "type": "string" }, "lastErrorAt": { "type": "number" } }, "required": [ "projectId", "clientEmail", "lastError", "lastErrorAt" ] }, "devices": { "type": "object", "properties": { "apns": { "type": "number" }, "fcm": { "type": "number" } }, "required": [ "apns", "fcm" ] } }, "required": [ "storageReady", "showMessageText", "apns", "fcm", "devices" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:write", "security": [ { "apiKey": [] } ] } }, "/v1/admin/widget/register-identifier": { "post": { "operationId": "registerWidgetIdentifier", "summary": "Register Widget Identifier", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "id", "type", "value", "createdAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks channels:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "channels:write", "security": [ { "apiKey": [] } ] } }, "/v1/agents/me": { "get": { "operationId": "getAgentMe", "summary": "Get Agent Me", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": "string" }, "availability": { "type": "string", "enum": [ "online", "busy", "offline" ] }, "createdAt": { "type": "number" }, "email": { "type": "string" }, "role": { "type": "string" }, "isSuperAdmin": { "type": "boolean" } }, "required": [ "id", "tenantId", "name", "avatarUrl", "availability", "createdAt", "email", "role", "isSuperAdmin" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "patchAgentMe", "summary": "Patch Agent Me", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } }, "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:write", "security": [ { "apiKey": [] } ] } }, "/v1/agents/me/docs-context": { "get": { "operationId": "getDocsContext", "summary": "Get Docs Context", "description": "Public docs personalisation: workspace, plan and Copilot setup state. Never includes secrets.", "parameters": [ { "name": "workspace", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:read", "security": [ { "apiKey": [] } ] } }, "/v1/agents/transfer-targets": { "get": { "operationId": "getTransferTargets", "summary": "Get Transfer Targets", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "department": { "type": "string" }, "avatarUrl": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "number" }, "availability": { "type": "string", "enum": [ "online", "busy", "offline" ] }, "online": { "type": "boolean" }, "openConversations": { "type": "number" } }, "required": [ "id", "tenantId", "name", "department", "avatarUrl", "email", "role", "createdAt" ] } } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/analytics/overview": { "get": { "operationId": "getAnalyticsOverview", "summary": "Get Analytics Overview", "description": "Days follow the viewer's time zone.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "timeZone", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "totalVisitors": { "type": "number" }, "totalContacts": { "type": "number" }, "openConversations": { "type": "number" }, "resolvedToday": { "type": "number" }, "messages30d": { "type": "number" }, "messagesInRange": { "type": "number" }, "registeredSurfaces": { "type": "number" }, "readySources": { "type": "number" }, "syncingSources": { "type": "number" }, "failedSources": { "type": "number" }, "totalContexts": { "type": "number" }, "failedJobs": { "type": "number" }, "pendingJobs": { "type": "number" } }, "required": [ "totalVisitors", "totalContacts", "openConversations", "resolvedToday", "messages30d", "messagesInRange", "registeredSurfaces", "readySources", "syncingSources", "failedSources", "totalContexts", "failedJobs", "pendingJobs" ] }, "days": { "type": "number" }, "timeZone": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "totals": { "type": "object", "properties": { "visitors": { "type": "number" }, "contacts": { "type": "number" }, "conversationsOpened": { "type": "number" }, "conversationsResolved": { "type": "number" }, "messages": { "type": "number" } }, "required": [ "visitors", "contacts", "conversationsOpened", "conversationsResolved", "messages" ] }, "previous": { "type": "object", "properties": { "visitors": { "type": "number" }, "contacts": { "type": "number" }, "conversationsOpened": { "type": "number" }, "conversationsResolved": { "type": "number" }, "messages": { "type": "number" } }, "required": [ "visitors", "contacts", "conversationsOpened", "conversationsResolved", "messages" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "visitors": { "type": "number" }, "contacts": { "type": "number" }, "conversationsOpened": { "type": "number" }, "conversationsResolved": { "type": "number" }, "messages": { "type": "number" } }, "required": [ "day", "visitors", "contacts", "conversationsOpened", "conversationsResolved", "messages" ] } }, "giovbot": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "conversations": { "type": "number" }, "success": { "type": "number" }, "handoffs": { "type": "number" }, "open": { "type": "number" }, "fallbacks": { "type": "number" }, "replies": { "type": "number" }, "successRate": { "type": "number" }, "handoffRate": { "type": "number" }, "fallbackRate": { "type": "number" }, "avgLatencyMs": { "type": "number" }, "avgDurationMs": { "type": "number" }, "credits": { "type": "number" } }, "required": [ "conversations", "success", "handoffs", "open", "fallbacks", "replies", "successRate", "handoffRate", "fallbackRate", "avgLatencyMs", "avgDurationMs", "credits" ] }, "previous": { "type": "object", "properties": { "conversations": { "type": "number" }, "success": { "type": "number" }, "handoffs": { "type": "number" }, "open": { "type": "number" }, "fallbacks": { "type": "number" }, "replies": { "type": "number" }, "successRate": { "type": "number" }, "handoffRate": { "type": "number" }, "fallbackRate": { "type": "number" }, "avgLatencyMs": { "type": "number" }, "avgDurationMs": { "type": "number" }, "credits": { "type": "number" } }, "required": [ "conversations", "success", "handoffs", "open", "fallbacks", "replies", "successRate", "handoffRate", "fallbackRate", "avgLatencyMs", "avgDurationMs", "credits" ] }, "series": { "type": "array", "items": { "type": "object", "properties": {} } }, "models": { "type": "array", "items": { "type": "object", "properties": {} } } }, "required": [ "totals", "previous", "series", "models" ] } }, "required": [ "summary", "days", "timeZone", "from", "to", "totals", "previous", "series", "giovbot" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks analytics:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "analytics:read", "security": [ { "apiKey": [] } ] } }, "/v1/audit-logs": { "get": { "operationId": "getAuditLogs", "summary": "Get Audit Logs", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks analytics:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "analytics:read", "security": [ { "apiKey": [] } ] } }, "/v1/billing/overview": { "get": { "operationId": "getBillingOverview", "summary": "Get Billing Overview", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "status": { "type": "string" }, "priceId": { "type": "string" }, "plan": { "type": "string" }, "interval": { "type": "string", "enum": [ "month", "year" ] } }, "required": [ "subscriptionId", "status", "priceId", "plan", "interval" ] }, "pendingDowngrade": { "type": "object", "properties": { "priceId": { "type": "string" }, "plan": { "type": "string" }, "interval": { "type": "string", "enum": [ "month", "year" ] }, "effectiveAt": { "type": "number" } }, "required": [ "priceId", "plan", "interval", "effectiveAt" ] }, "nextPayment": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "at": { "type": "number" }, "total": { "type": "object", "properties": { "amount": { "type": "string" }, "currencyCode": { "type": "string" } }, "required": [ "amount", "currencyCode" ] } }, "required": [ "subscriptionId", "at", "total" ] }, "addon": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "status": { "type": "string" }, "interval": { "type": "string", "enum": [ "month", "year" ] }, "nextBilledAt": { "type": "number" } }, "required": [ "subscriptionId", "status", "interval", "nextBilledAt" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "priceId": { "type": "string" }, "plan": { "type": "string" }, "interval": { "type": "string", "enum": [ "month", "year" ] } }, "required": [ "priceId", "plan", "interval" ] } }, "duplicatePlanSubscriptions": { "type": "number" }, "planSubscriptions": { "type": "array", "items": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "status": { "type": "string" }, "priceId": { "type": "string" }, "plan": { "type": "string" }, "interval": { "type": "string", "enum": [ "month", "year" ] }, "currentPeriodStartsAt": { "type": "number" }, "currentPeriodEndsAt": { "type": "number" }, "nextBilledAt": { "type": "number" }, "scheduledChangeAction": { "type": "string" }, "scheduledChangeAt": { "type": "number" } }, "required": [ "subscriptionId", "status", "priceId", "plan", "interval", "currentPeriodStartsAt", "currentPeriodEndsAt", "nextBilledAt", "scheduledChangeAction", "scheduledChangeAt" ] } }, "usage": { "type": "object", "properties": { "resetsAt": { "type": "number" } }, "required": [ "resetsAt" ] } }, "required": [ "current", "pendingDowngrade", "nextPayment", "addon", "options", "duplicatePlanSubscriptions", "planSubscriptions", "usage" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:read", "security": [ { "apiKey": [] } ] } }, "/v1/billing/summary": { "get": { "operationId": "getBillingSummary", "summary": "Get Billing Summary", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "usageResetsAt": { "type": "number" }, "plan": { "type": "string" }, "trialEndsAt": { "type": "number" }, "usage": { "type": "object", "properties": { "messagesThisMonth": { "type": "number" }, "conversationsActive": { "type": "number" }, "agentsCount": { "type": "number" } } }, "limits": { "type": "object", "properties": { "messages": { "type": "number" }, "agents": { "type": "number" }, "activeChats": { "type": "number" } } }, "giovaiEnabled": { "type": "boolean" }, "giovbot": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "addonEnabled": { "type": "boolean" }, "creditsLimit": { "type": "number" }, "creditsUsed": { "type": "number" }, "publishedLimit": { "type": "number" } } }, "channels": { "type": "array", "items": { "type": "string" } }, "byoAiKeyAllowed": { "type": "boolean" }, "crmEnabled": { "type": "boolean" }, "emailMailboxLimit": { "type": "number" }, "copilotEnabled": { "type": "boolean" }, "paddleSubscription": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "priceId": { "type": "string" }, "scheduledChangeAction": { "type": "string" }, "scheduledChangeAt": { "type": "number" }, "nextBilledAt": { "type": "number" } }, "required": [ "id", "status", "priceId" ] } }, "required": [ "plan" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:read", "security": [ { "apiKey": [] } ] } }, "/v1/billing/transactions": { "get": { "operationId": "getBillingTransactions", "summary": "Get Billing Transactions", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "failed", "paid", "past_due", "refunded", "partially_refunded", "disputed", "canceled" ] }, "kind": { "type": "string", "enum": [ "subscription", "renewal", "plan_change", "charge" ] }, "invoiceNumber": { "type": "string" }, "items": { "type": "object", "properties": {} }, "period": { "type": "object", "properties": {} }, "currencyCode": { "type": "string" }, "subtotal": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "refunded": { "type": "string" }, "failedAttempts": { "type": "number" }, "lastFailure": { "type": "object", "properties": {} }, "paymentMethod": { "type": "object", "properties": {} }, "invoiceAvailable": { "type": "boolean" } }, "required": [ "id", "date", "status", "kind", "invoiceNumber", "items", "period", "currencyCode", "subtotal", "tax", "total", "refunded", "failedAttempts", "lastFailure", "paymentMethod", "invoiceAvailable" ] } }, "nextCursor": { "type": "string" } }, "required": [ "items", "nextCursor" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:read", "security": [ { "apiKey": [] } ] } }, "/v1/billing/transactions/{id}/invoice": { "get": { "operationId": "getBillingInvoice", "summary": "Get Billing Invoice", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations": { "get": { "operationId": "getConversations", "summary": "Get Conversations", "description": "Lists inbox conversations with their actual conversation id and customer identity fields. Omit optional filters to list all visible conversations; priority only accepts low, normal, high or urgent. To find a contact's conversations, search getContacts by q, then getCrmHistory with its contact id and kind=conversations.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Omit for the first page. For later pages use only the nextCursor returned by this same action for the same record and filters. Never invent a cursor or use a page number." } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "description": "Optional filter: omit unless a specific priority was requested. Use only a listed enum value; never an empty string, null or 'all'." } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "priority" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "prioritySource": { "type": "string", "enum": [ "default", "ai", "human" ] }, "priorityReason": { "type": "string" }, "pageUrl": { "type": "string" }, "userId": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "assignedAgentId": { "type": "string" }, "primaryChannel": { "type": "string" }, "subject": { "type": "string" }, "source": { "type": "string", "enum": [ "copilot" ] }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string" }, "avatarUrl": { "type": "string" }, "lastMessage": { "type": "string" }, "unreadCount": { "type": "number" }, "pinned": { "type": "boolean" }, "botHandled": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "object", "properties": {} } }, "assignedAgentName": { "type": "string" }, "assignedAgentAvatarUrl": { "type": "string" }, "emailParticipant": { "type": "string" }, "requiresTemplate": { "type": "boolean" }, "replyWindowExpiresAt": { "type": "number" }, "channelConnection": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "displayName": { "type": "string" }, "historyStatus": { "type": "string" } }, "required": [ "id", "status", "displayName", "historyStatus" ] }, "giovbot": { "type": "object", "properties": { "available": { "type": "boolean" }, "active": { "type": "boolean" }, "replyReady": { "type": "boolean" }, "replyAgentId": { "type": "string" }, "agentId": { "type": "string" }, "agentName": { "type": "string" } }, "required": [ "available", "active", "agentId", "agentName" ] } }, "required": [ "id", "tenantId", "status", "priority", "pageUrl", "userId", "createdAt", "updatedAt", "assignedAgentId", "primaryChannel", "subject", "labels" ] } } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversationId}/giovbot-draft": { "post": { "operationId": "generateGiovBotDraft", "summary": "Generate Giov Bot Draft", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" } }, "required": [ "messageId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "string" }, "agentId": { "type": "string" }, "agentName": { "type": "string" }, "confidence": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "draft", "agentId", "agentName", "confidence", "reason" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversationId}/labels": { "post": { "operationId": "toggleConversationLabel", "summary": "Toggle Conversation Label", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labelId": { "type": "string" } }, "required": [ "labelId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "id", "name", "color" ] } } }, "required": [ "labels" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversationId}/messages/{messageId}/bookmark": { "post": { "operationId": "toggleMessageBookmark", "summary": "Toggle Message Bookmark", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bookmarked": { "type": "boolean" } }, "required": [ "bookmarked" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversationId}/messages/{messageId}/flag": { "delete": { "operationId": "unflagMessage", "summary": "Unflag Message", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "flagReason": { "type": "object" } }, "required": [ "ok", "flagReason" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "flagMessage", "summary": "Flag Message", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "flagReason": { "type": "string" } }, "required": [ "ok", "flagReason" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversationId}/messages/{messageId}/retry": { "post": { "operationId": "retryEmailMessage", "summary": "Retry Email Message", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deliveryStatus": { "type": "string", "enum": [ "queued" ] } }, "required": [ "ok", "deliveryStatus" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversationId}/send-whatsapp-template": { "post": { "operationId": "sendWhatsAppTemplate", "summary": "Send Whats App Template", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" }, "parameters": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } }, "required": [ "name", "language" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "channel": { "type": "string", "enum": [ "whatsapp" ] }, "deliveryStatus": { "type": "string", "enum": [ "queued" ] }, "createdAt": { "type": "number" } }, "required": [ "id", "content", "channel", "deliveryStatus", "createdAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversationId}/whatsapp-templates": { "get": { "operationId": "getWhatsAppTemplates", "summary": "Get Whats App Templates", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "preview": { "type": "string" }, "supported": { "type": "boolean" }, "limitation": { "type": "string" }, "inputFields": { "type": "object", "properties": {} } }, "required": [ "name", "language", "status", "preview", "supported", "limitation", "inputFields" ] } } }, "required": [ "templates" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}": { "get": { "operationId": "getConversation", "summary": "Get Conversation", "description": "Reads a conversation using a conversation id returned by getConversations or getCrmHistory(kind=conversations). An email address, contact id or user id is not a conversation id.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "prioritySource": { "type": "string", "enum": [ "default", "ai", "human" ] }, "priorityReason": { "type": "string" }, "pageUrl": { "type": "string" }, "userId": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "assignedAgentId": { "type": "string" }, "primaryChannel": { "type": "string" }, "subject": { "type": "string" }, "source": { "type": "string", "enum": [ "copilot" ] }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string" }, "avatarUrl": { "type": "string" }, "lastMessage": { "type": "string" }, "unreadCount": { "type": "number" }, "pinned": { "type": "boolean" }, "botHandled": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "id", "name", "color" ] } }, "assignedAgentName": { "type": "string" }, "assignedAgentAvatarUrl": { "type": "string" }, "emailParticipant": { "type": "string" }, "requiresTemplate": { "type": "boolean" }, "replyWindowExpiresAt": { "type": "number" }, "channelConnection": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "displayName": { "type": "string" }, "historyStatus": { "type": "string" } }, "required": [ "id", "status", "displayName", "historyStatus" ] }, "giovbot": { "type": "object", "properties": { "available": { "type": "boolean" }, "active": { "type": "boolean" }, "replyReady": { "type": "boolean" }, "replyAgentId": { "type": "string" }, "agentId": { "type": "string" }, "agentName": { "type": "string" } }, "required": [ "available", "active", "agentId", "agentName" ] } }, "required": [ "id", "tenantId", "status", "priority", "pageUrl", "userId", "createdAt", "updatedAt", "assignedAgentId", "primaryChannel", "subject", "labels" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/accept": { "post": { "operationId": "acceptConversation", "summary": "Accept Conversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/activity": { "get": { "operationId": "getConversationActivity", "summary": "Get Conversation Activity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Omit for the first page. For later pages use only the nextCursor returned by this same action for the same record and filters. Never invent a cursor or use a page number." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "closed", "conversation_started", "assigned", "transferred", "reopened", "note_added", "priority_changed" ] }, "createdAt": { "type": "number" }, "actorType": { "type": "string", "enum": [ "customer", "human", "ai_agent", "system" ] }, "actorId": { "type": "string" }, "actorName": { "type": "string" }, "details": { "type": "object", "properties": {} } }, "required": [ "id", "type", "createdAt", "actorType", "actorId", "actorName", "details" ] } }, "nextCursor": { "type": "string" }, "contactId": { "type": "string" }, "capabilities": { "type": "object", "properties": { "timeline": { "type": "boolean" }, "contactNotes": { "type": "boolean" } }, "required": [ "timeline", "contactNotes" ] } }, "required": [ "entries", "nextCursor", "contactId", "capabilities" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/close": { "post": { "operationId": "closeConversation", "summary": "Close Conversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/customer-history": { "get": { "operationId": "getConversationHistory", "summary": "Get Conversation History", "description": "Lists other conversations for the customer linked to an existing conversation id. This id must be a conversation id, not a contact id or email; use getCrmHistory(kind=conversations) when starting with a contact. Omit cursor initially, then use only nextCursor returned by this action for the same conversation.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Omit for the first page. For later pages use only the nextCursor returned by this same action for the same record and filters. Never invent a cursor or use a page number." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "primaryChannel": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "preview": { "type": "string" } }, "required": [ "id", "status", "subject", "primaryChannel", "createdAt", "updatedAt", "preview" ] } }, "nextCursor": { "type": "string" }, "contactId": { "type": "string" } }, "required": [ "conversations", "nextCursor", "contactId" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/messages": { "get": { "operationId": "getConversationMessages", "summary": "Get Conversation Messages", "description": "Reads the transcript for an actual conversation id. Omit cursor for the first page; subsequent pages use only nextCursor from this same action and conversation, never an email, contact id or page number.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Omit for the first page. For later pages use only the nextCursor returned by this same action for the same record and filters. Never invent a cursor or use a page number." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "role": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "type": "number" }, "channel": { "type": "string" }, "attachmentId": { "type": "string" }, "replyToMessageId": { "type": "string" }, "deliveryStatus": { "type": "string" } }, "required": [ "id", "conversationId", "role", "content", "createdAt", "channel", "attachmentId", "replyToMessageId", "deliveryStatus" ] } }, "nextCursor": { "type": "string" }, "attachmentAccess": { "type": "object", "properties": { "token": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "token", "expiresAt" ] } }, "required": [ "messages" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/metadata": { "get": { "operationId": "getConversationMetadata", "summary": "Get Conversation Metadata", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "patchConversationMetadata", "summary": "Patch Conversation Metadata", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } }, "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/notes": { "get": { "operationId": "getConversationNotes", "summary": "Get Conversation Notes", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Omit for the first page. For later pages use only the nextCursor returned by this same action for the same record and filters. Never invent a cursor or use a page number." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "scope": { "type": "string", "enum": [ "conversation", "contact" ] }, "authorId": { "type": "string" }, "authorName": { "type": "string" }, "createdAt": { "type": "number" }, "conversationId": { "type": "string" }, "editedAt": { "type": "number" }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" } }, "required": [ "id", "body", "scope", "authorId", "authorName", "createdAt", "conversationId" ] } }, "nextCursor": { "type": "string" }, "contactId": { "type": "string" }, "canWriteContactNotes": { "type": "boolean" } }, "required": [ "notes", "nextCursor", "contactId", "canWriteContactNotes" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "addConversationNote", "summary": "Add Conversation Note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "scope": { "type": "string", "enum": [ "conversation", "contact" ] } }, "required": [ "body", "scope" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "scope": { "type": "string", "enum": [ "conversation", "contact" ] }, "authorId": { "type": "string" }, "authorName": { "type": "string" }, "createdAt": { "type": "number" }, "conversationId": { "type": "string" }, "editedAt": { "type": "number" }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" } }, "required": [ "id", "body", "scope", "authorId", "authorName", "createdAt", "conversationId" ] } }, "required": [ "note" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/notes/{noteId}": { "delete": { "operationId": "deleteConversationNote", "summary": "Delete Conversation Note", "description": "Deletes a note shown on this conversation (its author, or an admin).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "ok", "id" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "editConversationNote", "summary": "Edit Conversation Note", "description": "Edits a note shown on this conversation (its author only).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "scope": { "type": "string", "enum": [ "conversation", "contact" ] }, "authorId": { "type": "string" }, "authorName": { "type": "string" }, "createdAt": { "type": "number" }, "conversationId": { "type": "string" }, "editedAt": { "type": "number" }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" } }, "required": [ "id", "body", "scope", "authorId", "authorName", "createdAt", "conversationId" ] } }, "required": [ "note" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/pin": { "delete": { "operationId": "unpinConversation", "summary": "Unpin Conversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean" } }, "required": [ "pinned" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] }, "put": { "operationId": "pinConversation", "summary": "Pin Conversation", "description": "Pins are personal: they reorder only the signed-in agent's inbox.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean" } }, "required": [ "pinned" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/priority": { "patch": { "operationId": "setConversationPriority", "summary": "Set Conversation Priority", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, "required": [ "priority" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, "required": [ "priority" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/read": { "post": { "operationId": "markRead", "summary": "Mark Read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/send": { "post": { "operationId": "sendMessage", "summary": "Send Message", "description": "`blocks` are message blocks (packages/config/message-blocks.ts), typed loosely so the generated Copilot catalog accepts every block type; the API cleans them before storing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "string" } }, "replyToMessageId": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "number" }, "channel": { "type": "string" }, "deliveryStatus": { "type": "string" } }, "required": [ "id", "createdAt", "channel", "deliveryStatus" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{id}/transfer": { "post": { "operationId": "transferConversation", "summary": "Transfer Conversation", "description": "To a teammate, a department (whoever in it is online with the fewest open chats) or GiovBot.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Actual conversation id returned by a conversation list or getCrmHistory(kind=conversations). Do not use an email address, user id or contact id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "department": { "type": "string" }, "giovbotAgentId": { "type": "string" }, "returnToGiovBot": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "assignedAgentId": { "type": "string" }, "giovbotAgentId": { "type": "string" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/count": { "get": { "operationId": "getConversationCount", "summary": "Get Conversation Count", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "description": "Optional filter: omit unless a specific priority was requested. Use only a listed enum value; never an empty string, null or 'all'." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/labels": { "get": { "operationId": "getConversationLabels", "summary": "Get Conversation Labels", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "id", "name", "color" ] } } }, "required": [ "labels" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/conversations/unread-count": { "get": { "operationId": "getUnreadCount", "summary": "Get Unread Count", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/contacts": { "get": { "operationId": "getContacts", "summary": "Get Contacts", "description": "Searches contacts by q (email, name or phone). The returned contacts[].id is a contact id: pass it to getCrmHistory with kind=conversations to obtain actual conversationId values before reading or sending messages.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "identity", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "conversations", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "location": { "type": "string" }, "conversationCount": { "type": "number" }, "firstSeenAt": { "type": "number" }, "lastSeenAt": { "type": "number" } }, "required": [ "id", "name", "conversationCount", "firstSeenAt", "lastSeenAt" ] } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] } }, "required": [ "contacts" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/contacts/{sourceId}/merge": { "post": { "operationId": "mergeContacts", "summary": "Merge Contacts", "parameters": [ { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetContactId": { "type": "string" } }, "required": [ "targetContactId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "contactId": { "type": "string" } }, "required": [ "ok", "contactId" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/companies": { "get": { "operationId": "getCrmCompanies", "summary": "Get CRM Companies", "description": "Companies (Pro and up), a page at a time: q searches name and domain, sort is name, domain, peopleCount, ownerName, createdAt or updatedAt. Each has peopleCount.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "ownerId": { "type": "string" }, "ownerName": { "type": "string" }, "tags": { "type": "object", "properties": {} }, "tagMeta": { "type": "object", "properties": {} }, "peopleCount": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "domain", "ownerId", "ownerName", "tags", "peopleCount", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] } }, "required": [ "companies", "pagination" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "createCrmCompany", "summary": "Create CRM Company", "description": "Creates a company. The domain is stored lowercase without www and must be unique in the workspace; contacts whose email uses it join automatically.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "ownerId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "ownerId": { "type": "string" }, "ownerName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "tagMeta": { "type": "array", "items": { "type": "object", "properties": {} } }, "peopleCount": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "domain", "ownerId", "ownerName", "tags", "peopleCount", "createdAt", "updatedAt" ] } }, "required": [ "company" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/companies/{id}": { "delete": { "operationId": "deleteCrmCompany", "summary": "Delete CRM Company", "description": "Deletes a company (admins only). Its people stay and are unlinked.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "unlinked": { "type": "number" } }, "required": [ "ok", "unlinked" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] }, "get": { "operationId": "getCrmCompany", "summary": "Get CRM Company", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "ownerId": { "type": "string" }, "ownerName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "tagMeta": { "type": "array", "items": { "type": "object", "properties": {} } }, "peopleCount": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "domain", "ownerId", "ownerName", "tags", "peopleCount", "createdAt", "updatedAt" ] } }, "required": [ "company" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "updateCrmCompany", "summary": "Update CRM Company", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "ownerId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "ownerId": { "type": "string" }, "ownerName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "tagMeta": { "type": "array", "items": { "type": "object", "properties": {} } }, "peopleCount": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "name", "domain", "ownerId", "ownerName", "tags", "peopleCount", "createdAt", "updatedAt" ] } }, "required": [ "company" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/companies/{id}/history": { "get": { "operationId": "getCrmCompanyHistory", "summary": "Get CRM Company History", "description": "Read-only conversations, notes or tasks across the people of one company, newest first. Page with offset.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "conversations", "notes", "tasks" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "conversationId": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "preview": { "type": "string" }, "primaryChannel": { "type": "string" }, "updatedAt": { "type": "number" }, "body": { "type": "string" }, "authorName": { "type": "string" }, "createdAt": { "type": "number" }, "title": { "type": "string" }, "dueAt": { "type": "number" }, "assigneeName": { "type": "string" } }, "required": [ "contactId", "contactName" ] } }, "hasMore": { "type": "boolean" } }, "required": [ "entries", "hasMore" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/companies/backfill": { "post": { "operationId": "startCrmCompanyBackfill", "summary": "Start CRM Company Backfill", "description": "Starts linking existing contacts by email domain (admins only) and runs the first batch. Call stepCrmCompanyBackfill until status is completed.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "backfill": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "idle", "running" ] }, "total": { "type": "number" }, "processed": { "type": "number" }, "linked": { "type": "number" }, "startedAt": { "type": "number" }, "finishedAt": { "type": "number" } }, "required": [ "status", "total", "processed", "linked", "startedAt", "finishedAt" ] } }, "required": [ "backfill" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/companies/backfill/step": { "post": { "operationId": "stepCrmCompanyBackfill", "summary": "Step CRM Company Backfill", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "backfill": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "idle", "running" ] }, "total": { "type": "number" }, "processed": { "type": "number" }, "linked": { "type": "number" }, "startedAt": { "type": "number" }, "finishedAt": { "type": "number" } }, "required": [ "status", "total", "processed", "linked", "startedAt", "finishedAt" ] } }, "required": [ "backfill" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/companies/settings": { "get": { "operationId": "getCrmCompanySettings", "summary": "Get CRM Company Settings", "description": "Whether contacts join companies by email domain, plus the progress of linking existing contacts.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "autoLink": { "type": "boolean" }, "ignoredDomains": { "type": "array", "items": { "type": "string" } }, "canManage": { "type": "boolean" }, "backfill": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "idle", "running" ] }, "total": { "type": "number" }, "processed": { "type": "number" }, "linked": { "type": "number" }, "startedAt": { "type": "number" }, "finishedAt": { "type": "number" } }, "required": [ "status", "total", "processed", "linked", "startedAt", "finishedAt" ] } }, "required": [ "autoLink", "ignoredDomains", "canManage", "backfill" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "put": { "operationId": "saveCrmCompanySettings", "summary": "Save CRM Company Settings", "description": "Turns automatic linking by email domain on or off (admins only).", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autoLink": { "type": "boolean" } }, "required": [ "autoLink" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "autoLink": { "type": "boolean" }, "ignoredDomains": { "type": "array", "items": { "type": "string" } }, "backfill": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "idle", "running" ] }, "total": { "type": "number" }, "processed": { "type": "number" }, "linked": { "type": "number" }, "startedAt": { "type": "number" }, "finishedAt": { "type": "number" } }, "required": [ "status", "total", "processed", "linked", "startedAt", "finishedAt" ] } }, "required": [ "autoLink", "ignoredDomains", "backfill" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/config": { "get": { "operationId": "getCrmConfig", "summary": "Get CRM Config", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "number", "boolean", "text", "date" ] } }, "required": [ "id", "name", "type" ] } }, "canManageFields": { "type": "boolean" }, "canManageTags": { "type": "boolean" }, "canExportContacts": { "type": "boolean" }, "canMergeContacts": { "type": "boolean" }, "canManageCompanies": { "type": "boolean" }, "canWriteContactNotes": { "type": "boolean" }, "subjectId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "tagCatalog": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "green", "amber", "red", "purple" ] } }, "required": [ "id", "name", "color" ] } }, "archivedTags": { "type": "array", "items": { "type": "string" } }, "features": { "type": "object", "properties": { "contactHub": { "type": "boolean" }, "savedViews": { "type": "boolean" }, "lifecycle": { "type": "boolean" }, "bulkActions": { "type": "boolean" }, "importExport": { "type": "boolean" }, "duplicates": { "type": "boolean" }, "aiSummary": { "type": "boolean" }, "companies": { "type": "boolean" } }, "required": [ "contactHub", "savedViews", "lifecycle", "bulkActions", "importExport", "duplicates", "aiSummary", "companies" ] } }, "required": [ "operators", "fields", "canManageFields", "canManageTags", "canWriteContactNotes", "subjectId", "tags" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts": { "get": { "operationId": "getCrmContacts", "summary": "Get CRM Contacts", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lifecycle", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "followUp", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "conversations", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "inactivityDays", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "duplicates", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "company", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "timezoneOffset", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] } }, "required": [ "contacts", "pagination" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "createCrmContact", "summary": "Create CRM Contact", "description": "Create a contact from verified details. At least one non-empty name, email address or phone number is needed; the remaining fields are optional. Ask for missing contact details instead of inventing them.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email", "description": "The email address supplied by the user or verified for this contact through an authorized lookup. If they ask to add an email without identifying an address, ask for it before creating the contact." }, "phone": { "type": "string" }, "country": { "type": "string" }, "location": { "type": "string" }, "lifecycle": { "type": "string", "enum": [ "customer", "lead", "qualified", "inactive" ] }, "ownerId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object" } }, "required": [ "contact" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/{contactId}/company": { "put": { "operationId": "setCrmContactCompany", "summary": "Set CRM Contact Company", "description": "Sets a contact's company, or clears it with companyId null. A choice made here is never changed by automatic linking.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" } }, "required": [ "companyId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object" } }, "required": [ "contact" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/{id}": { "get": { "operationId": "getCrmContact", "summary": "Get CRM Contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object" } }, "required": [ "contact" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "updateCrmContact", "summary": "Update CRM Contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "location": { "type": "string" }, "lifecycle": { "type": "string", "enum": [ "customer", "lead", "qualified", "inactive" ] }, "ownerId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object" } }, "required": [ "contact" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/{id}/duplicates": { "get": { "operationId": "getCrmContactDuplicates", "summary": "Get CRM Contact Duplicates", "description": "Contacts that look like the same person as this one (same email or phone), not dismissed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "duplicates": { "type": "array", "items": { "type": "object", "properties": { "contact": { "type": "object", "properties": {} }, "reasons": { "type": "object", "properties": {} } }, "required": [ "contact", "reasons" ] } }, "hasMore": { "type": "boolean" } }, "required": [ "duplicates", "hasMore" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/{id}/history": { "get": { "operationId": "getCrmHistory", "summary": "Get CRM History", "description": "Reads a contact's history using the contact id from getContacts or getCrmContacts. kind=conversations returns entries[].conversationId for getConversation, getConversationMessages and sendMessage. Omit cursor on the first call; use only this action's nextCursor for the same contact and kind.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "conversations", "notes", "activity" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Omit for the first page. For later pages use only the nextCursor returned by this same action for the same record and filters. Never invent a cursor or use a page number." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "number" }, "conversationId": { "type": "string" }, "type": { "type": "string" }, "actorType": { "type": "string" }, "actorName": { "type": "string" }, "actorId": { "type": "string" }, "details": { "type": "object", "properties": {} }, "body": { "type": "string" }, "authorName": { "type": "string" }, "authorId": { "type": "string" }, "editedAt": { "type": "number" }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "conversation", "contact" ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "preview": { "type": "string" }, "primaryChannel": { "type": "string" }, "assignedAgentName": { "type": "string" }, "updatedAt": { "type": "number" } }, "required": [ "id", "createdAt" ] } }, "nextCursor": { "type": "string" } }, "required": [ "entries", "nextCursor" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/{id}/notes": { "post": { "operationId": "addCrmNote", "summary": "Add CRM Note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "number" }, "conversationId": { "type": "string" }, "type": { "type": "string" }, "actorType": { "type": "string" }, "actorName": { "type": "string" }, "actorId": { "type": "string" }, "details": { "type": "object", "properties": {} }, "body": { "type": "string" }, "authorName": { "type": "string" }, "authorId": { "type": "string" }, "editedAt": { "type": "number" }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "conversation", "contact" ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "preview": { "type": "string" }, "primaryChannel": { "type": "string" }, "assignedAgentName": { "type": "string" }, "updatedAt": { "type": "number" } }, "required": [ "id", "createdAt" ] } }, "required": [ "note" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/{id}/notes/{noteId}": { "delete": { "operationId": "deleteCrmNote", "summary": "Delete CRM Note", "description": "Deletes a note shown on this contact (its author, or an admin).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "ok", "id" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "editCrmNote", "summary": "Edit CRM Note", "description": "Edits a note shown on this contact (its author only).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "number" }, "conversationId": { "type": "string" }, "type": { "type": "string" }, "actorType": { "type": "string" }, "actorName": { "type": "string" }, "actorId": { "type": "string" }, "details": { "type": "object", "properties": {} }, "body": { "type": "string" }, "authorName": { "type": "string" }, "authorId": { "type": "string" }, "editedAt": { "type": "number" }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "conversation", "contact" ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "preview": { "type": "string" }, "primaryChannel": { "type": "string" }, "assignedAgentName": { "type": "string" }, "updatedAt": { "type": "number" } }, "required": [ "id", "createdAt" ] } }, "required": [ "note" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/{id}/summary": { "get": { "operationId": "getCrmContactSummary", "summary": "Get CRM Contact Summary", "description": "The cached AI summary of a contact (Pro and up): short lines plus a suggested next step, and `stale` when newer messages, notes or tasks exist. summary is null before the first one. Costs nothing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" } }, "nextStep": { "type": "object", "properties": { "title": { "type": "string" }, "dueInDays": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "title", "dueInDays", "reason" ] }, "model": { "type": "string" }, "locale": { "type": "string" }, "generatedAt": { "type": "number" } }, "required": [ "lines", "nextStep", "model", "locale", "generatedAt" ] }, "stale": { "type": "boolean" }, "latestActivityAt": { "type": "number" } }, "required": [ "summary", "stale", "latestActivityAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "generateCrmContactSummary", "summary": "Generate CRM Contact Summary", "description": "Writes (or refreshes) the AI summary of a contact in the given language (en, fr, es, pt or de); `today` is the user's local date (YYYY-MM-DD) for the model's sense of today. Uses AI credits; errors ai_credits_exhausted, summary_rate_limited and ai_unavailable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Contact id returned by getContacts or getCrmContacts, not an email address or conversation id." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "today": { "type": "string" }, "locale": { "type": "string" } }, "required": [ "locale" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" } }, "nextStep": { "type": "object", "properties": { "title": { "type": "string" }, "dueInDays": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "title", "dueInDays", "reason" ] }, "model": { "type": "string" }, "locale": { "type": "string" }, "generatedAt": { "type": "number" } }, "required": [ "lines", "nextStep", "model", "locale", "generatedAt" ] }, "stale": { "type": "boolean" }, "latestActivityAt": { "type": "number" } }, "required": [ "summary", "stale", "latestActivityAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/bulk": { "post": { "operationId": "bulkUpdateCrmContacts", "summary": "Bulk Update CRM Contacts", "description": "Changes many contacts at once (Pro and up): set_owner, add_tag, remove_tag, set_lifecycle (Business and up) or create_task (one follow-up per contact). Choose them with ids (up to 5000 contact ids from getCrmContacts) or with query (the same filters as getCrmContacts, for every matching contact, up to 5000). Never deletes. Returns how many matched, were updated and were left unchanged.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "action": { "type": "string", "enum": [ "set_owner" ] }, "ownerId": { "type": "string" } }, "required": [ "ids", "action", "ownerId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "set_owner", "add_tag", "remove_tag", "set_lifecycle", "create_task" ] }, "matched": { "type": "number" }, "updated": { "type": "number" }, "skipped": { "type": "number" }, "atLimit": { "type": "number" } }, "required": [ "action", "matched", "updated", "skipped" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/import": { "post": { "operationId": "importCrmContacts", "summary": "Import CRM Contacts", "description": "Imports up to 500 contacts from a CSV file (Pro and up) in one transaction. importId is a UUID the client makes once per import and repeats on every batch. Matches by email, then phone (a phone only when it cannot be someone else's): mode upsert updates or creates, create only adds, update only changes. Rows are { line, name, email, phone, country, location, lifecycle (Business and up), owner (agent email), tags (only admins may add tags that are not in the workspace list), customFields (field id to text) }. The body is limited to 2 MB. Returns counts, the rows that were refused (errors: { line, code, field, value }) and rows imported with a note (warnings).", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "upsert", "create", "update" ] }, "importId": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "number" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "location": { "type": "string" }, "lifecycle": { "type": "string" }, "owner": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } }, "required": [ "line" ] } } }, "required": [ "mode", "importId", "rows" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "updated": { "type": "number" }, "skipped": { "type": "number" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "number" }, "code": { "type": "string" }, "field": { "type": "string" }, "value": { "type": "string" } }, "required": [ "line", "code" ] } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "number" }, "code": { "type": "string" }, "field": { "type": "string" }, "value": { "type": "string" } }, "required": [ "line", "code" ] } }, "lifecycleIgnored": { "type": "boolean" } }, "required": [ "created", "updated", "skipped", "errors", "warnings", "lifecycleIgnored" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/contacts/import/complete": { "post": { "operationId": "completeCrmImport", "summary": "Complete CRM Import", "description": "Marks an import as finished in the audit log, once. Counts are not sent; each batch was audited by the server.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "importId": { "type": "string" } }, "required": [ "importId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/deletion-requests": { "get": { "operationId": "getCrmDeletionRequests", "summary": "Get CRM Deletion Requests", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "verified", "approved", "deleting", "completed", "rejected", "cancelled" ] }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "source": { "type": "string", "enum": [ "customer", "representative", "internal" ] }, "note": { "type": "string" }, "submittedBy": { "type": "object", "properties": {} }, "submittedAt": { "type": "number" }, "verification": { "type": "object", "properties": {} }, "decision": { "type": "object", "properties": {} }, "preview": { "type": "object", "properties": {} }, "failureReason": { "type": "string" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "reference", "status", "contactId", "contactName", "source", "note", "submittedBy", "submittedAt", "verification", "decision", "preview", "failureReason", "startedAt", "completedAt", "updatedAt" ] } }, "counts": { "type": "object", "properties": { "open": { "type": "number" }, "closed": { "type": "number" }, "awaitingApproval": { "type": "number" } }, "required": [ "open", "closed", "awaitingApproval" ] }, "canApprove": { "type": "boolean" }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] } }, "required": [ "requests", "counts", "canApprove", "pagination" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "submitCrmDeletionRequest", "summary": "Submit CRM Deletion Request", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "source": { "type": "string", "enum": [ "customer", "representative", "internal" ] }, "note": { "type": "string" } }, "required": [ "contactId", "source", "note" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "verified", "approved", "deleting", "completed", "rejected", "cancelled" ] }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "source": { "type": "string", "enum": [ "customer", "representative", "internal" ] }, "note": { "type": "string" }, "submittedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "submittedAt": { "type": "number" }, "verification": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "email_on_file", "verified_identity", "phone_callback", "document", "internal_decision" ] }, "note": { "type": "string" }, "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" } }, "required": [ "method", "note", "by", "byId", "at" ] }, "decision": { "type": "object", "properties": { "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" }, "note": { "type": "string" } }, "required": [ "by", "byId", "at", "note" ] }, "preview": { "type": "object", "properties": { "conversations": { "type": "number" }, "messages": { "type": "number" }, "attachments": { "type": "number" }, "attachmentBytes": { "type": "number" }, "visitorRecords": { "type": "number" }, "channelIdentities": { "type": "number" }, "notes": { "type": "number" }, "tasks": { "type": "number" }, "activityEntries": { "type": "number" }, "sharedConversations": { "type": "number" }, "openConversations": { "type": "number" }, "heldConversations": { "type": "number" } }, "required": [ "conversations", "messages", "attachments", "attachmentBytes", "visitorRecords", "channelIdentities", "notes", "tasks", "activityEntries", "sharedConversations", "openConversations", "heldConversations" ] }, "failureReason": { "type": "string" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "reference", "status", "contactId", "contactName", "source", "note", "submittedBy", "submittedAt", "verification", "decision", "preview", "failureReason", "startedAt", "completedAt", "updatedAt" ] } }, "required": [ "request" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/deletion-requests/{id}": { "get": { "operationId": "getCrmDeletionRequest", "summary": "Get CRM Deletion Request", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "verified", "approved", "deleting", "completed", "rejected", "cancelled" ] }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "source": { "type": "string", "enum": [ "customer", "representative", "internal" ] }, "note": { "type": "string" }, "submittedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "submittedAt": { "type": "number" }, "verification": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "email_on_file", "verified_identity", "phone_callback", "document", "internal_decision" ] }, "note": { "type": "string" }, "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" } }, "required": [ "method", "note", "by", "byId", "at" ] }, "decision": { "type": "object", "properties": { "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" }, "note": { "type": "string" } }, "required": [ "by", "byId", "at", "note" ] }, "preview": { "type": "object", "properties": { "conversations": { "type": "number" }, "messages": { "type": "number" }, "attachments": { "type": "number" }, "attachmentBytes": { "type": "number" }, "visitorRecords": { "type": "number" }, "channelIdentities": { "type": "number" }, "notes": { "type": "number" }, "tasks": { "type": "number" }, "activityEntries": { "type": "number" }, "sharedConversations": { "type": "number" }, "openConversations": { "type": "number" }, "heldConversations": { "type": "number" } }, "required": [ "conversations", "messages", "attachments", "attachmentBytes", "visitorRecords", "channelIdentities", "notes", "tasks", "activityEntries", "sharedConversations", "openConversations", "heldConversations" ] }, "failureReason": { "type": "string" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "reference", "status", "contactId", "contactName", "source", "note", "submittedBy", "submittedAt", "verification", "decision", "preview", "failureReason", "startedAt", "completedAt", "updatedAt" ] }, "canApprove": { "type": "boolean" }, "canCancel": { "type": "boolean" } }, "required": [ "request", "canApprove", "canCancel" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/deletion-requests/{id}/{outcome}": { "post": { "operationId": "closeCrmDeletionRequest", "summary": "Close CRM Deletion Request", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "outcome", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "verified", "approved", "deleting", "completed", "rejected", "cancelled" ] }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "source": { "type": "string", "enum": [ "customer", "representative", "internal" ] }, "note": { "type": "string" }, "submittedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "submittedAt": { "type": "number" }, "verification": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "email_on_file", "verified_identity", "phone_callback", "document", "internal_decision" ] }, "note": { "type": "string" }, "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" } }, "required": [ "method", "note", "by", "byId", "at" ] }, "decision": { "type": "object", "properties": { "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" }, "note": { "type": "string" } }, "required": [ "by", "byId", "at", "note" ] }, "preview": { "type": "object", "properties": { "conversations": { "type": "number" }, "messages": { "type": "number" }, "attachments": { "type": "number" }, "attachmentBytes": { "type": "number" }, "visitorRecords": { "type": "number" }, "channelIdentities": { "type": "number" }, "notes": { "type": "number" }, "tasks": { "type": "number" }, "activityEntries": { "type": "number" }, "sharedConversations": { "type": "number" }, "openConversations": { "type": "number" }, "heldConversations": { "type": "number" } }, "required": [ "conversations", "messages", "attachments", "attachmentBytes", "visitorRecords", "channelIdentities", "notes", "tasks", "activityEntries", "sharedConversations", "openConversations", "heldConversations" ] }, "failureReason": { "type": "string" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "reference", "status", "contactId", "contactName", "source", "note", "submittedBy", "submittedAt", "verification", "decision", "preview", "failureReason", "startedAt", "completedAt", "updatedAt" ] } }, "required": [ "request" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/deletion-requests/{id}/approve": { "post": { "operationId": "approveCrmDeletionRequest", "summary": "Approve CRM Deletion Request", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "verified", "approved", "deleting", "completed", "rejected", "cancelled" ] }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "source": { "type": "string", "enum": [ "customer", "representative", "internal" ] }, "note": { "type": "string" }, "submittedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "submittedAt": { "type": "number" }, "verification": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "email_on_file", "verified_identity", "phone_callback", "document", "internal_decision" ] }, "note": { "type": "string" }, "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" } }, "required": [ "method", "note", "by", "byId", "at" ] }, "decision": { "type": "object", "properties": { "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" }, "note": { "type": "string" } }, "required": [ "by", "byId", "at", "note" ] }, "preview": { "type": "object", "properties": { "conversations": { "type": "number" }, "messages": { "type": "number" }, "attachments": { "type": "number" }, "attachmentBytes": { "type": "number" }, "visitorRecords": { "type": "number" }, "channelIdentities": { "type": "number" }, "notes": { "type": "number" }, "tasks": { "type": "number" }, "activityEntries": { "type": "number" }, "sharedConversations": { "type": "number" }, "openConversations": { "type": "number" }, "heldConversations": { "type": "number" } }, "required": [ "conversations", "messages", "attachments", "attachmentBytes", "visitorRecords", "channelIdentities", "notes", "tasks", "activityEntries", "sharedConversations", "openConversations", "heldConversations" ] }, "failureReason": { "type": "string" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "reference", "status", "contactId", "contactName", "source", "note", "submittedBy", "submittedAt", "verification", "decision", "preview", "failureReason", "startedAt", "completedAt", "updatedAt" ] } }, "required": [ "request" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/deletion-requests/{id}/verify": { "post": { "operationId": "verifyCrmDeletionRequest", "summary": "Verify CRM Deletion Request", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "email_on_file", "verified_identity", "phone_callback", "document", "internal_decision" ] }, "note": { "type": "string" } }, "required": [ "method", "note" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "verified", "approved", "deleting", "completed", "rejected", "cancelled" ] }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "source": { "type": "string", "enum": [ "customer", "representative", "internal" ] }, "note": { "type": "string" }, "submittedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "submittedAt": { "type": "number" }, "verification": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "email_on_file", "verified_identity", "phone_callback", "document", "internal_decision" ] }, "note": { "type": "string" }, "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" } }, "required": [ "method", "note", "by", "byId", "at" ] }, "decision": { "type": "object", "properties": { "by": { "type": "string" }, "byId": { "type": "string" }, "at": { "type": "number" }, "note": { "type": "string" } }, "required": [ "by", "byId", "at", "note" ] }, "preview": { "type": "object", "properties": { "conversations": { "type": "number" }, "messages": { "type": "number" }, "attachments": { "type": "number" }, "attachmentBytes": { "type": "number" }, "visitorRecords": { "type": "number" }, "channelIdentities": { "type": "number" }, "notes": { "type": "number" }, "tasks": { "type": "number" }, "activityEntries": { "type": "number" }, "sharedConversations": { "type": "number" }, "openConversations": { "type": "number" }, "heldConversations": { "type": "number" } }, "required": [ "conversations", "messages", "attachments", "attachmentBytes", "visitorRecords", "channelIdentities", "notes", "tasks", "activityEntries", "sharedConversations", "openConversations", "heldConversations" ] }, "failureReason": { "type": "string" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "reference", "status", "contactId", "contactName", "source", "note", "submittedBy", "submittedAt", "verification", "decision", "preview", "failureReason", "startedAt", "completedAt", "updatedAt" ] } }, "required": [ "request" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/deletion-requests/preview/{contactId}": { "get": { "operationId": "getCrmDeletionPreview", "summary": "Get CRM Deletion Preview", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "conversations": { "type": "number" }, "messages": { "type": "number" }, "attachments": { "type": "number" }, "attachmentBytes": { "type": "number" }, "visitorRecords": { "type": "number" }, "channelIdentities": { "type": "number" }, "notes": { "type": "number" }, "tasks": { "type": "number" }, "activityEntries": { "type": "number" }, "sharedConversations": { "type": "number" }, "openConversations": { "type": "number" }, "heldConversations": { "type": "number" } }, "required": [ "conversations", "messages", "attachments", "attachmentBytes", "visitorRecords", "channelIdentities", "notes", "tasks", "activityEntries", "sharedConversations", "openConversations", "heldConversations" ] }, "openRequest": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "verified", "approved", "deleting", "completed", "rejected", "cancelled" ] } }, "required": [ "id", "status" ] } }, "required": [ "preview", "openRequest" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/duplicates": { "get": { "operationId": "getCrmDuplicateGroups", "summary": "Get CRM Duplicate Groups", "description": "Groups of contacts that look like the same person (same email, or same phone), a page at a time (Pro and up). Pass nextCursor from the previous answer to continue. Merge a pair with mergeContacts; dismissCrmDuplicate marks a pair as not duplicates.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Omit for the first page. For later pages use only the nextCursor returned by this same action for the same record and filters. Never invent a cursor or use a page number." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reasons": { "type": "object", "properties": {} }, "size": { "type": "number" }, "suggestedKeepId": { "type": "string" }, "members": { "type": "object", "properties": {} }, "dismissedPairs": { "type": "object", "properties": {} } }, "required": [ "key", "reasons", "size", "suggestedKeepId", "members", "dismissedPairs" ] } }, "nextCursor": { "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "groups", "nextCursor", "hasMore" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/duplicates/dismiss": { "delete": { "operationId": "restoreCrmDuplicate", "summary": "Restore CRM Duplicate", "description": "Takes a dismissal back (same ids as dismissCrmDuplicate), so the pairs can be suggested again.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "contactIds" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "restored": { "type": "number" } }, "required": [ "ok", "restored" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "dismissCrmDuplicate", "summary": "Dismiss CRM Duplicate", "description": "Marks contacts as not duplicates of each other (two ids, or up to 25 for a whole group), so no pair among them is suggested again.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "contactIds" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/fields": { "post": { "operationId": "createCrmField", "summary": "Create CRM Field", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "number", "boolean", "text", "date" ] } }, "required": [ "name", "type" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "field": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "number", "boolean", "text", "date" ] } }, "required": [ "id", "name", "type" ] } }, "required": [ "field" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/fields/{id}": { "delete": { "operationId": "deleteCrmField", "summary": "Delete CRM Field", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/reminders": { "get": { "operationId": "getCrmReminders", "summary": "Get CRM Reminders", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reminders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "dueAt": { "type": "number" }, "createdAt": { "type": "number" }, "readAt": { "type": "number" } }, "required": [ "id", "taskId", "contactId", "contactName", "title", "dueAt", "createdAt", "readAt" ] } }, "unreadCount": { "type": "number" }, "nextDueAt": { "type": "number" }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] } }, "required": [ "reminders", "unreadCount", "pagination" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/reminders/{id}": { "patch": { "operationId": "markCrmReminderRead", "summary": "Mark CRM Reminder Read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "read": { "type": "boolean" } }, "required": [ "read" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/reminders/read-all": { "post": { "operationId": "markAllCrmRemindersRead", "summary": "Mark All CRM Reminders Read", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/tags": { "get": { "operationId": "getCrmTags", "summary": "Get CRM Tags", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "green", "amber", "red", "purple" ] } }, "required": [ "id", "name", "color" ] } } }, "required": [ "tags" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "createCrmTag", "summary": "Create CRM Tag", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "green", "amber", "red", "purple" ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "green", "amber", "red", "purple" ] } }, "required": [ "id", "name", "color" ] } }, "required": [ "tag" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/tags/{id}": { "delete": { "operationId": "deleteCrmTag", "summary": "Delete CRM Tag", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "updateCrmTag", "summary": "Update CRM Tag", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "green", "amber", "red", "purple" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "green", "amber", "red", "purple" ] } }, "required": [ "id", "name", "color" ] } }, "required": [ "tag" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/tasks": { "get": { "operationId": "getCrmTasks", "summary": "Get CRM Tasks", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "due", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "timezoneOffset", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "assigneeId": { "type": "string" }, "assigneeName": { "type": "string" }, "dueAt": { "type": "number" }, "status": { "type": "string", "enum": [ "open", "completed" ] }, "completedAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "contactId", "contactName", "title", "body", "assigneeId", "assigneeName", "dueAt", "status", "completedAt", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] }, "counts": { "type": "object", "properties": { "overdue": { "type": "number" }, "today": { "type": "number" } }, "required": [ "overdue", "today" ] } }, "required": [ "tasks", "pagination", "counts" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "createCrmTask", "summary": "Create CRM Task", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "assigneeId": { "type": "string" }, "dueAt": { "type": "number" } }, "required": [ "contactId", "title", "body", "assigneeId", "dueAt" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "assigneeId": { "type": "string" }, "assigneeName": { "type": "string" }, "dueAt": { "type": "number" }, "status": { "type": "string", "enum": [ "open", "completed" ] }, "completedAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "contactId", "contactName", "title", "body", "assigneeId", "assigneeName", "dueAt", "status", "completedAt", "createdAt", "updatedAt" ] } }, "required": [ "task" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/tasks/{id}": { "delete": { "operationId": "deleteCrmTask", "summary": "Delete CRM Task", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] }, "get": { "operationId": "getCrmTask", "summary": "Get CRM Task", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "assigneeId": { "type": "string" }, "assigneeName": { "type": "string" }, "dueAt": { "type": "number" }, "status": { "type": "string", "enum": [ "open", "completed" ] }, "completedAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "contactId", "contactName", "title", "body", "assigneeId", "assigneeName", "dueAt", "status", "completedAt", "createdAt", "updatedAt" ] } }, "required": [ "task" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "updateCrmTask", "summary": "Update CRM Task", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "assigneeId": { "type": "string" }, "assigneeName": { "type": "string" }, "dueAt": { "type": "number" }, "status": { "type": "string", "enum": [ "open", "completed" ] }, "completedAt": { "type": "number" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "contactId", "contactName", "title", "body", "assigneeId", "assigneeName", "dueAt", "status", "completedAt", "createdAt", "updatedAt" ] } }, "required": [ "task" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/views": { "get": { "operationId": "getCrmViews", "summary": "Get CRM Views", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "views": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "filters": { "type": "object", "properties": {} } }, "required": [ "id", "name", "filters" ] } } }, "required": [ "views" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "saveCrmView", "summary": "Save CRM View", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "filters": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } }, "required": [ "name", "filters" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "view": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "filters": { "type": "object", "properties": {} } }, "required": [ "id", "name", "filters" ] } }, "required": [ "view" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/crm/views/{id}": { "delete": { "operationId": "deleteCrmView", "summary": "Delete CRM View", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/visitors": { "get": { "operationId": "getVisitors", "summary": "Get Visitors", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "identity", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "conversations", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "visitors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "contactId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "location": { "type": "string" }, "browser": { "type": "string" }, "lastPageUrl": { "type": "string" }, "status": { "type": "string" }, "enteredAt": { "type": "number" }, "lastSeenAt": { "type": "number" } }, "required": [ "id", "conversationId", "name", "status", "enteredAt", "lastSeenAt" ] } }, "newCount": { "type": "number" }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] } }, "required": [ "visitors", "newCount" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/customers/visitors/mark-seen": { "post": { "operationId": "markVisitorsSeen", "summary": "Mark Visitors Seen", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "seenAt": { "type": "number" } }, "required": [ "seenAt" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:write", "security": [ { "apiKey": [] } ] } }, "/v1/customers/visitors/new-count": { "get": { "operationId": "getNewVisitorCount", "summary": "Get New Visitor Count", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks customers:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "customers:read", "security": [ { "apiKey": [] } ] } }, "/v1/feedback": { "post": { "operationId": "submitFeedback", "summary": "Submit Feedback", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "pagePath": { "type": "string" } }, "required": [ "message", "pagePath" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:write", "security": [ { "apiKey": [] } ] } }, "/v1/notifications": { "get": { "operationId": "getNotifications", "summary": "Get Notifications", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "system", "announcement", "reminder" ] }, "kind": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "params": { "type": "object", "properties": {} }, "link": { "type": "string" }, "createdAt": { "type": "number" }, "readAt": { "type": "number" }, "dismissedAt": { "type": "number" } }, "required": [ "id", "source", "kind", "severity", "title", "body", "params", "link", "createdAt", "readAt", "dismissedAt" ] } }, "unreadCount": { "type": "number" }, "nextDueAt": { "type": "number" }, "pagination": { "type": "object", "properties": { "limit": { "type": "number" }, "offset": { "type": "number" }, "total": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": [ "total" ] } }, "required": [ "notifications", "unreadCount", "pagination" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:read", "security": [ { "apiKey": [] } ] } }, "/v1/notifications/{id}/dismiss": { "post": { "operationId": "dismissNotification", "summary": "Dismiss Notification", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:write", "security": [ { "apiKey": [] } ] } }, "/v1/notifications/{id}/read": { "post": { "operationId": "markNotificationRead", "summary": "Mark Notification Read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:write", "security": [ { "apiKey": [] } ] } }, "/v1/notifications/read-all": { "post": { "operationId": "markAllNotificationsRead", "summary": "Mark All Notifications Read", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:write", "security": [ { "apiKey": [] } ] } }, "/v1/notifications/unread-count": { "get": { "operationId": "getNotificationUnreadCount", "summary": "Get Notification Unread Count", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "unreadCount": { "type": "number" } }, "required": [ "unreadCount" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks profile:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "profile:read", "security": [ { "apiKey": [] } ] } }, "/v1/onboarding": { "patch": { "operationId": "patchOnboarding", "summary": "Patch Onboarding", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "number" }, "companyName": { "type": "string" }, "defaultAgentName": { "type": "string" }, "defaultAgentAvatar": { "type": "string" }, "useCase": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "number" }, "completed": { "type": "boolean" }, "companyName": { "type": "string" }, "useCase": { "type": "string" }, "defaultAgentName": { "type": "string" }, "defaultAgentAvatar": { "type": "string" } }, "required": [ "step", "completed", "companyName", "useCase", "defaultAgentName", "defaultAgentAvatar" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:write", "security": [ { "apiKey": [] } ] } }, "/v1/onboarding/status": { "get": { "operationId": "getOnboardingStatus", "summary": "Get Onboarding Status", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "number" }, "stepId": { "type": "string", "enum": [ "company", "installation", "widget", "team", "app", "done" ] }, "completed": { "type": "boolean" }, "companyName": { "type": "string" }, "useCase": { "type": "string" }, "verification": { "type": "object", "properties": { "verified": { "type": "boolean" }, "locksAt": { "type": "number" }, "locked": { "type": "boolean" } }, "required": [ "verified", "locksAt", "locked" ] }, "installs": { "type": "array", "items": { "type": "object", "properties": { "client": { "type": "string", "enum": [ "web", "react-native", "flutter", "ios", "android" ] }, "host": { "type": "string" }, "version": { "type": "string" }, "blocked": { "type": "boolean" }, "firstSeenAt": { "type": "number" }, "lastSeenAt": { "type": "number" } }, "required": [ "client", "host", "version", "blocked", "firstSeenAt", "lastSeenAt" ] } }, "setup": { "type": "object", "properties": { "workspaceConfigured": { "type": "boolean" }, "widgetConfigured": { "type": "boolean" }, "widgetDetected": { "type": "boolean" }, "teamInvited": { "type": "boolean" }, "channelConnected": { "type": "boolean" }, "agentAppInstalled": { "type": "boolean" }, "giovbotLive": { "type": "boolean" }, "copilotLive": { "type": "boolean" } }, "required": [ "widgetDetected", "teamInvited", "channelConnected", "agentAppInstalled", "giovbotLive", "copilotLive" ] } }, "required": [ "step", "stepId", "completed", "companyName", "useCase", "verification", "installs", "setup" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks settings:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "settings:read", "security": [ { "apiKey": [] } ] } }, "/v1/quick-replies": { "get": { "operationId": "getQuickReplies", "summary": "Get Quick Replies", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quickReplies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "shortcut": { "type": "string" }, "createdBy": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "title", "content", "shortcut", "createdBy", "createdAt", "updatedAt" ] } } }, "required": [ "quickReplies" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] }, "post": { "operationId": "createQuickReply", "summary": "Create Quick Reply", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "shortcut": { "type": "string" } }, "required": [ "title", "content" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quickReply": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "shortcut": { "type": "string" }, "createdBy": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "title", "content", "shortcut", "createdBy", "createdAt", "updatedAt" ] } }, "required": [ "quickReply" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/quick-replies/{id}": { "delete": { "operationId": "deleteQuickReply", "summary": "Delete Quick Reply", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success." }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "updateQuickReply", "summary": "Update Quick Reply", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "shortcut": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quickReply": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "shortcut": { "type": "string" }, "createdBy": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "title", "content", "shortcut", "createdBy", "createdAt", "updatedAt" ] } }, "required": [ "quickReply" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:write, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:write", "security": [ { "apiKey": [] } ] } }, "/v1/search/conversations": { "get": { "operationId": "searchConversations", "summary": "Search Conversations", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/search/global": { "get": { "operationId": "searchGlobal", "summary": "Search Global", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "userId": { "type": "string" }, "pageUrl": { "type": "string" }, "subject": { "type": "string" }, "primaryChannel": { "type": "string", "enum": [ "website", "email", "whatsapp", "messenger", "instagram", "telegram" ] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "required": [ "id", "status", "createdAt" ] } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "role": { "type": "string", "enum": [ "agent", "visitor", "user" ] }, "content": { "type": "string" }, "createdAt": { "type": "number" } }, "required": [ "id", "conversationId", "role", "content", "createdAt" ] } }, "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "contact", "visitor" ] }, "conversationId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "location": { "type": "string" }, "conversationCount": { "type": "number" }, "lastSeenAt": { "type": "number" } }, "required": [ "id", "type", "lastSeenAt" ] } } }, "required": [ "conversations", "messages", "customers" ] } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } }, "/v1/search/messages": { "get": { "operationId": "searchMessages", "summary": "Search Messages", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Missing, invalid, revoked or expired API key." }, "403": { "description": "The key lacks conversations:read, or its creator's role or the workspace's App permissions don't allow it." }, "429": { "description": "Too many calls (300 a minute per key)." } }, "x-giov-permission": "conversations:read", "security": [ { "apiKey": [] } ] } } } }