{
  "openapi": "3.0.3",
  "info": {
    "title": "Umney Connect Live Chat API",
    "version": "1.0.0",
    "description": "Product-scoped public API for conversations_suite (Live Chat). Base path is /api. Docs: https://umneyconnect.com/developers/live-chat"
  },
  "servers": [
    { "url": "https://umneyconnect.com/api", "description": "Production" },
    { "url": "https://www.staging.umneyconnect.com/api", "description": "Staging" }
  ],
  "tags": [
    { "name": "Sessions" },
    { "name": "Conversations" },
    { "name": "Messages" },
    { "name": "Visitors" }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "umk_live_…",
        "description": "Product-scoped Live Chat token from Dashboard → Developers"
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "ConversationId": {
        "name": "conversationId",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "statusCode": { "type": "integer" },
          "error": { "type": "string" },
          "message": { "type": "string" },
          "requestId": { "type": "string" }
        }
      },
      "ChatSessionRequest": {
        "type": "object",
        "required": ["externalId"],
        "properties": {
          "externalId": { "type": "string", "maxLength": 200 },
          "displayName": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "name": { "type": "string" },
          "source": { "type": "string" },
          "attributes": { "type": "object", "additionalProperties": true }
        }
      },
      "ChatSessionResponse": {
        "type": "object",
        "properties": {
          "conversationId": { "type": "string", "format": "uuid" },
          "chatUrl": { "type": "string", "format": "uri" },
          "externalId": { "type": "string" },
          "visitorToken": { "type": "string" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "siteKey": { "type": "string" }
        }
      }
    }
  },
  "security": [{ "ApiKeyBearer": [] }, { "ApiKeyHeader": [] }],
  "paths": {
    "/v1/chat/sessions": {
      "post": {
        "tags": ["Sessions"],
        "summary": "Mint visitor chat session",
        "description": "Requires scope chat:write. Returns a hosted chatUrl for Nest Safety / CRM deep links.",
        "operationId": "createChatSession",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatSessionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created",
            "headers": {
              "X-Request-ID": { "schema": { "type": "string" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatSessionResponse" }
              }
            }
          },
          "403": {
            "description": "Missing scope or entitlement",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/v1/chat/conversations": {
      "get": {
        "tags": ["Conversations"],
        "summary": "List conversations",
        "operationId": "listConversations",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["open", "pending", "resolved", "closed"] } },
          { "name": "source", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Paginated conversation list" }
        }
      },
      "post": {
        "tags": ["Conversations"],
        "summary": "Create conversation",
        "operationId": "createConversation",
        "responses": {
          "200": { "description": "Conversation created" }
        }
      }
    },
    "/v1/chat/conversations/{conversationId}/messages": {
      "get": {
        "tags": ["Messages"],
        "summary": "List messages",
        "operationId": "listMessages",
        "parameters": [{ "$ref": "#/components/parameters/ConversationId" }],
        "responses": { "200": { "description": "Message list" } }
      },
      "post": {
        "tags": ["Messages"],
        "summary": "Send message",
        "operationId": "sendMessage",
        "parameters": [{ "$ref": "#/components/parameters/ConversationId" }],
        "responses": { "200": { "description": "Message created" } }
      }
    },
    "/v1/chat/visitors": {
      "get": {
        "tags": ["Visitors"],
        "summary": "List visitors or lookup by externalId",
        "operationId": "listVisitors",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "externalId", "in": "query", "schema": { "type": "string" }, "description": "Exact visitor externalId lookup" }
        ],
        "responses": { "200": { "description": "Visitor list" } }
      }
    }
  }
}