{
  "openapi": "3.1.0",
  "info": {
    "title": "ConveRact Developer Integration API",
    "version": "1.0.0",
    "description": "Documented tenant integration subset: server APIs and public text chat. Administration is performed in the tenant workspace. ConveRact service integration is free, with no installation charge or one-time fee. Subscription, usage, provider fees, and plan entitlements still apply."
  },
  "servers": [
    {
      "url": "https://api.converact.com/api/v1"
    }
  ],
  "externalDocs": {
    "description": "Step-by-step tenant developer guide",
    "url": "https://www.converact.com/developers"
  },
  "components": {
    "securitySchemes": {
      "workspaceApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Server-only workspace key issued in API keys. Keep the atl_ prefix unchanged; never expose the secret in browser code."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": {
            "const": false
          },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {}
            },
            "additionalProperties": true
          }
        }
      },
      "Record": {
        "type": "object",
        "additionalProperties": true
      },
      "RecordResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "$ref": "#/components/schemas/Record"
          }
        }
      },
      "ListResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Record"
            }
          }
        }
      },
      "ProductPageResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "type": "object",
            "required": ["items", "pagination"],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Record"
                }
              },
              "pagination": {
                "type": "object",
                "required": ["page", "limit", "total", "pages"],
                "properties": {
                  "page": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  },
                  "total": {
                    "type": "integer"
                  },
                  "pages": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        }
      },
      "PaymentLinkInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "conversationId": {
            "type": "string",
            "minLength": 4,
            "maxLength": 160
          },
          "customerName": {
            "type": "string",
            "minLength": 2,
            "maxLength": 100
          },
          "customerEmail": {
            "type": "string",
            "format": "email"
          },
          "customerPhone": {
            "type": "string",
            "minLength": 8,
            "maxLength": 24
          },
          "billingFrequency": {
            "type": "string",
            "enum": ["ONE_TIME", "MONTHLY"],
            "default": "ONE_TIME"
          },
          "billingCycles": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1200
          }
        }
      },
      "ChatInput": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "conversationId": {
            "type": "string"
          },
          "customerId": {
            "type": "string",
            "maxLength": 128
          },
          "clientMessageId": {
            "type": "string",
            "minLength": 8,
            "maxLength": 160
          }
        }
      },
      "ChatResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "const": true
          },
          "data": {
            "type": "object",
            "properties": {
              "conversation": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "customerId": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              },
              "message": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "action": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true
              },
              "products": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            },
            "additionalProperties": true
          }
        }
      }
    }
  },
  "paths": {
    "/external/products": {
      "get": {
        "summary": "List non-archived products, including drafts",
        "description": "Required workspace API key permission: products:read. Records are tenant-scoped; record fields can vary by offering or provider.",
        "operationId": "getExternalProducts",
        "tags": ["Server API"],
        "security": [
          {
            "workspaceApiKey": []
          }
        ],
        "x-required-permission": "products:read",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductPageResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error. Edge or rate-limit responses may be non-JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ]
      }
    },
    "/external/products/{id}": {
      "get": {
        "summary": "Read one tenant product",
        "description": "Required workspace API key permission: products:read. Records are tenant-scoped; record fields can vary by offering or provider.",
        "operationId": "getExternalProductsId",
        "tags": ["Server API"],
        "security": [
          {
            "workspaceApiKey": []
          }
        ],
        "x-required-permission": "products:read",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error. Edge or rate-limit responses may be non-JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/external/quotes": {
      "get": {
        "summary": "List tenant quotes",
        "description": "Required workspace API key permission: quotes:read. Records are tenant-scoped; record fields can vary by offering or provider.",
        "operationId": "getExternalQuotes",
        "tags": ["Server API"],
        "security": [
          {
            "workspaceApiKey": []
          }
        ],
        "x-required-permission": "quotes:read",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error. Edge or rate-limit responses may be non-JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/external/payments": {
      "get": {
        "summary": "List tenant payments",
        "description": "Required workspace API key permission: payments:read. Records are tenant-scoped; record fields can vary by offering or provider.",
        "operationId": "getExternalPayments",
        "tags": ["Server API"],
        "security": [
          {
            "workspaceApiKey": []
          }
        ],
        "x-required-permission": "payments:read",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error. Edge or rate-limit responses may be non-JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/external/payments/{id}": {
      "get": {
        "summary": "Read one tenant payment",
        "description": "Required workspace API key permission: payments:read. Records are tenant-scoped; record fields can vary by offering or provider.",
        "operationId": "getExternalPaymentsId",
        "tags": ["Server API"],
        "security": [
          {
            "workspaceApiKey": []
          }
        ],
        "x-required-permission": "payments:read",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error. Edge or rate-limit responses may be non-JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/external/quotes/{id}/payment-link": {
      "post": {
        "summary": "Create a payment link for an existing quote",
        "description": "Required workspace API key permission: payment-links:write. Records are tenant-scoped; record fields can vary by offering or provider. Configure customer payments first. No generic idempotency-key guarantee: reconcile a timed-out write before repeating it.",
        "operationId": "postExternalQuotesIdPayment-Link",
        "tags": ["Server API"],
        "security": [
          {
            "workspaceApiKey": []
          }
        ],
        "x-required-permission": "payment-links:write",
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error. Edge or rate-limit responses may be non-JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentLinkInput"
              },
              "example": {
                "billingFrequency": "ONE_TIME"
              }
            }
          }
        }
      }
    },
    "/public/widget/{publicKey}/config": {
      "get": {
        "summary": "Read widget configuration",
        "operationId": "widgetConfig",
        "tags": ["Public widget"],
        "security": [],
        "description": "Use your tenant public key, not a workspace API secret. Chat browser requests must originate from an allowed website. Use the shipped widget for complete contact verification and commerce flows.",
        "parameters": [
          {
            "name": "publicKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/public/widget/{publicKey}/chat": {
      "post": {
        "summary": "Send a customer text message",
        "operationId": "widgetChat",
        "tags": ["Public widget"],
        "security": [],
        "description": "Use your tenant public key, not a workspace API secret. Chat browser requests must originate from an allowed website. Use the shipped widget for complete contact verification and commerce flows.",
        "parameters": [
          {
            "name": "publicKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                }
              }
            }
          },
          "default": {
            "description": "Application error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatInput"
              },
              "example": {
                "message": "Which service fits my business?",
                "customerId": "YOUR_RANDOM_VISITOR_ID",
                "clientMessageId": "YOUR_UNIQUE_MESSAGE_ID"
              }
            }
          }
        }
      }
    }
  }
}