{
  "openapi": "3.0.3",
  "info": {
    "title": "Stonly Public API",
    "description": "The Stonly Public REST API allows developers to programmatically manage knowledge base content and user access. This API provides capabilities to synchronize users, manage groups, organize folder structures, and automate the creation and publication of guides.\n\n### Key Capabilities\n* **Content Management**: Create, move, copy, and publish guides and folders.\n* **User Management**: Invite users, manage team membership, and handle user permissions.\n* **Group Management**: Organize users into groups for easier permission handling.\n* **AI Integration**: Programmatically query Stonly's AI to retrieve answers from your knowledge base.\n\n### Authentication\nAll requests must be authenticated using **Basic Auth**.\n* **Username**: This field is ignored by the server; you may pass any string (e.g., your team name).\n* **Password**: Provide your private **Stonly API Key**.",
    "termsOfService": "https://stonly.com/terms",
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "contact": {
      "email": "server@stonly.com"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://public.stonly.com/api/v3",
      "description": "Production Server (EU)"
    },
    {
      "url": "https://public.us.stonly.com/api/v3",
      "description": "Production Server (US)"
    }
  ],
  "tags": [
    {
      "name": "guide",
      "description": "Create, edit, move, copy, and publish interactive guides and articles."
    },
    {
      "name": "folder",
      "description": "Manage the directory structure (create, list, and organize folders)."
    },
    {
      "name": "ai",
      "description": "Interact with Stonly AI to generate answers from your knowledge base."
    },
    {
      "name": "user",
      "description": "Manage individual user accounts, invitations, and profile details."
    },
    {
      "name": "user access",
      "description": "Inspect user memberships and group associations."
    },
    {
      "name": "group",
      "description": "Create and manage user groups."
    },
    {
      "name": "group access",
      "description": "Manage membership within groups."
    },
    {
      "name": "team access",
      "description": "Control high-level access to the Team."
    },
    {
      "name": "job",
      "description": "Check the status of asynchronous background tasks."
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "paths": {
    "/guide": {
      "post": {
        "tags": [
          "guide"
        ],
        "summary": "Create a new guide",
        "description": "Initializes a new guide, article, or guided tour container. Returns the `guideId` and the ID of the automatically created first step.",
        "operationId": "createGuide",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/GuideCreate"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/GuideCreateSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "tags": [
          "guide"
        ],
        "summary": "Delete a guide",
        "description": "Permanently deletes a guide and all its associated steps. This action cannot be undone.",
        "operationId": "deleteGuide",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "name": "guideId",
            "in": "query",
            "description": "The unique identifier of the guide to delete.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Guide successfully deleted."
          },
          "400": {
            "description": "Bad request (e.g., invalid guideId)."
          },
          "403": {
            "description": "Forbidden - User does not have permission to delete this guide."
          },
          "404": {
            "description": "Guide not found."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/guide/step": {
      "post": {
        "tags": [
          "guide"
        ],
        "summary": "Append a step",
        "description": "Appends a new step to an existing guide after a specific parent step. Returns the newly created `stepId`.",
        "operationId": "appendStep",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/AppendStep"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/AppendStepSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/guide/step/link": {
      "post": {
        "tags": [
          "guide"
        ],
        "summary": "Link existing steps",
        "description": "Connects two existing steps with a navigation transition.",
        "operationId": "linkSteps",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/LinkSteps"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/LinkStepsSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/guide/publish": {
      "post": {
        "tags": [
          "guide"
        ],
        "summary": "Publish guides",
        "description": "Initiates an asynchronous background job to publish changes for a list of guides. Returns a `jobId` to track progress.",
        "operationId": "guidePublish",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/PublishGuide"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/CreateJobSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/guide/access": {
      "post": {
        "tags": [
          "guide"
        ],
        "summary": "Update guide permissions",
        "description": "Updates the access level (public/private) for multiple guides. Returns a `jobId` to track progress.",
        "operationId": "guideAccess",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/GuideAccess"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/CreateJobSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/guide/move": {
      "post": {
        "tags": [
          "guide"
        ],
        "summary": "Move guides",
        "description": "Moves a list of guides into a specific target folder. Returns a `jobId` to track progress.",
        "operationId": "guideMove",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/GuideMove"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/CreateJobSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/guide/copy": {
      "post": {
        "tags": [
          "guide"
        ],
        "summary": "Copy guides",
        "description": "Duplicates a list of guides into a target folder, optionally renaming them. Returns a `jobId` to track progress.",
        "operationId": "guideCopy",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/GuideCopy"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/CreateJobSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/guide/export": {
      "get": {
        "tags": [
          "guide"
        ],
        "summary": "Export guide content",
        "description": "Retrieves the full structure of a guide, including steps, transitions, and metadata.",
        "operationId": "guideExport",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/contentId"
          },
          {
            "$ref": "#/components/parameters/language"
          },
          {
            "$ref": "#/components/parameters/version"
          },
          {
            "$ref": "#/components/parameters/purpose"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ExportedStep"
                  }
                },
                "example": [
                  {
                    "id": 101,
                    "title": "Welcome",
                    "isFirstStep": true,
                    "content": "Welcome to the guide",
                    "type": "regular",
                    "nextSteps": [
                      {
                        "choiceLabel": "Open docs",
                        "id": 9001
                      },
                      {
                        "choiceLabel": "View embedded guide",
                        "id": 102
                      }
                    ],
                    "tags": [
                      "Product",
                      "Onboarding"
                    ]
                  },
                  {
                    "id": 102,
                    "title": "Embedded Guide",
                    "isFirstStep": false,
                    "content": "ueXQMf0CGM",
                    "type": "embeddedContent",
                    "nextSteps": [],
                    "tags": [
                      "Product"
                    ],
                    "meta": {
                      "embeddedStepId": 26244,
                      "embeddedGuideId": "ueXQMf0CGM"
                    }
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/folder": {
      "post": {
        "tags": [
          "folder"
        ],
        "summary": "Create a new folder",
        "description": "Creates a new directory for organizing content. Returns the `folderId` of the new folder.",
        "operationId": "createFolder",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/FolderCreate"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/FolderSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "get": {
        "tags": [
          "folder"
        ],
        "summary": "List folders",
        "description": "Retrieves a paginated list of folders residing in a specific folder.",
        "operationId": "getFolderList",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/folderId"
          },
          {
            "$ref": "#/components/parameters/page"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/nameList"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FoldersSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/folder/guide": {
      "get": {
        "tags": [
          "folder"
        ],
        "summary": "List guides within a folder",
        "description": "Retrieves a paginated list of guides residing in a specific folder.",
        "operationId": "getGuideList",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/folderId"
          },
          {
            "$ref": "#/components/parameters/page"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/guideStatus"
          },
          {
            "$ref": "#/components/parameters/nameList"
          },
          {
            "$ref": "#/components/parameters/tagList"
          },
          {
            "$ref": "#/components/parameters/updatedDateFrom"
          },
          {
            "$ref": "#/components/parameters/updatedDateTo"
          },
          {
            "$ref": "#/components/parameters/publishedDateFrom"
          },
          {
            "$ref": "#/components/parameters/publishedDateTo"
          },
          {
            "$ref": "#/components/parameters/recursive"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/GuidesSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/folder/structure": {
      "get": {
        "tags": [
          "folder"
        ],
        "summary": "Retrieve full folder structure",
        "description": "Retrieves the complete hierarchy of a folder and all its nested subfolders as a flat list.",
        "operationId": "folderStructure",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/folderId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FolderStructureSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/ai/search": {
      "post": {
        "tags": [
          "ai"
        ],
        "summary": "Initiate AI answer generation",
        "description": "Submits a natural language query to the AI engine. Returns a `questionAnswerId` used to poll for the result.",
        "operationId": "requestSearch",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/RequestSearch"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/RequestSearchSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/ai/answer": {
      "get": {
        "tags": [
          "ai"
        ],
        "summary": "Retrieve AI answer",
        "description": "Polls for the result of a search request. Returns the generated answer and metadata once ready.",
        "operationId": "getSearchResult",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/questionAnswerId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/GetAnswerSuccess"
          },
          "202": {
            "$ref": "#/components/responses/AnswerNotReady"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/ai/recommendGuides": {
      "post": {
        "tags": [
          "ai"
        ],
        "summary": "Get guide recommendations for an issue",
        "description": "Analyzes an issue/subproblem and returns recommended guides with relevance scores. Uses the AI Agent recommendation pipeline including query expansion, semantic search, keyword search, re-ranking, and sufficiency checking.",
        "operationId": "getGuideRecommendation",
        "requestBody": {
          "$ref": "#/components/requestBodies/GuideRecommendation"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/GuideRecommendationSuccess"
          },
          "404": {
            "description": "Knowledge base not found or AI configuration not found"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/user": {
      "post": {
        "tags": [
          "user"
        ],
        "summary": "Create a new user",
        "description": "Provisions a new user account within the team. Returns the created user's details including `userId`.",
        "operationId": "createUser",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/User"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/UserSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/user/byEmail": {
      "get": {
        "tags": [
          "user"
        ],
        "summary": "Find user by email",
        "description": "Retrieves profile details for a specific user identified by email.",
        "operationId": "getUserByEmail",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/userEmailRequired"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/UserSuccess"
          },
          "404": {
            "description": "User not found."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "tags": [
          "user"
        ],
        "summary": "Update user details",
        "description": "Updates profile information (name, role) for a specific user. Returns the updated user profile.",
        "operationId": "updateUser",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/userEmailRequired"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/UserUpdate"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/UserSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/user/invite": {
      "post": {
        "tags": [
          "user"
        ],
        "summary": "Invite user to team",
        "description": "Sends an email invitation to join the team with a specific role.",
        "operationId": "inviteUser",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "$ref": "#/components/schemas/User/properties/role"
                  },
                  "email": {
                    "$ref": "#/components/schemas/User/properties/email"
                  }
                },
                "required": [
                  "role",
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Invitation sent successfully."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/user/access": {
      "get": {
        "tags": [
          "user access"
        ],
        "summary": "Get user memberships",
        "description": "Retrieves a list of groups that the specified user belongs to.",
        "operationId": "getUserWithGroups",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/userEmailRequired"
          },
          {
            "$ref": "#/components/parameters/page"
          },
          {
            "$ref": "#/components/parameters/limit"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/UserGroupsSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/group": {
      "post": {
        "tags": [
          "group"
        ],
        "summary": "Create a group",
        "description": "Creates a new user group for organizing permissions. Returns the created group details including `groupId`.",
        "operationId": "addGroup",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/Group"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/GroupSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "get": {
        "tags": [
          "group"
        ],
        "summary": "Get group details",
        "description": "Retrieves details for a specific group by ID.",
        "operationId": "getGroupById",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/groupId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/GroupSuccess"
          },
          "404": {
            "description": "Group not found."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "tags": [
          "group"
        ],
        "summary": "Update group",
        "description": "Updates the name or description of an existing group. Returns the updated group details.",
        "operationId": "updateGroup",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/groupId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/Group"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/GroupSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "tags": [
          "group"
        ],
        "summary": "Delete group",
        "description": "Permanently deletes a group entity. Does not delete the users within it.",
        "operationId": "deleteGroup",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/groupId"
          }
        ],
        "responses": {
          "204": {
            "description": "Group successfully deleted."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/group/all": {
      "get": {
        "tags": [
          "group"
        ],
        "summary": "List all groups",
        "description": "Retrieves a paginated list of all user groups in the team.",
        "operationId": "getGroupList",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/page"
          },
          {
            "$ref": "#/components/parameters/limit"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/GroupsSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/group/access": {
      "post": {
        "tags": [
          "group access"
        ],
        "summary": "Add user to groups",
        "description": "Adds a user to one or more specified groups.",
        "operationId": "addAccess",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/Access"
        },
        "responses": {
          "201": {
            "description": "User added to groups successfully."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "tags": [
          "group access"
        ],
        "summary": "Set user groups",
        "description": "Overwrites a user's memberships, removing them from current groups and adding them only to the specified ones.",
        "operationId": "updateAccess",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/Access"
        },
        "responses": {
          "200": {
            "description": "User group memberships updated successfully."
          },
          "404": {
            "description": "User not found."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "tags": [
          "group access"
        ],
        "summary": "Remove user from groups",
        "description": "Removes a user from specific groups.",
        "operationId": "deleteAccess",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/userEmailRequired"
          },
          {
            "$ref": "#/components/parameters/groupIdList"
          }
        ],
        "responses": {
          "204": {
            "description": "User removed from groups successfully."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "get": {
        "tags": [
          "group access"
        ],
        "summary": "List group members",
        "description": "Retrieves a paginated list of users belonging to a specific group.",
        "operationId": "listAccess",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/groupId"
          },
          {
            "$ref": "#/components/parameters/page"
          },
          {
            "$ref": "#/components/parameters/limit"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/GroupMembersSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/team/access": {
      "post": {
        "tags": [
          "team access"
        ],
        "summary": "Add user to team",
        "description": "Grants a user access to the specified team(s).",
        "operationId": "addTeamMember",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/TeamAccess"
        },
        "responses": {
          "201": {
            "description": "User added to team successfully."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "tags": [
          "team access"
        ],
        "summary": "Remove user from team",
        "description": "Revokes a user's access to the specified team(s).",
        "operationId": "deleteTeamAccess",
        "parameters": [
          {
            "$ref": "#/components/parameters/teamId"
          },
          {
            "$ref": "#/components/parameters/userEmailRequired"
          },
          {
            "$ref": "#/components/parameters/teamIdList"
          }
        ],
        "responses": {
          "204": {
            "description": "User removed from team successfully."
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/job": {
      "get": {
        "tags": [
          "job"
        ],
        "summary": "Check job status",
        "description": "Checks the progress of an asynchronous background task. Returns the current status (e.g., completed, processing) and result details.",
        "operationId": "getStatus",
        "parameters": [
          {
            "$ref": "#/components/parameters/jobId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/GetJobSuccess"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "GuideCreateSuccess": {
        "description": "Guide successfully created.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "guideId": {
                  "type": "string",
                  "example": "ioTkq4uNhy",
                  "description": "The unique ID of the newly created guide."
                },
                "firstStepId": {
                  "type": "integer",
                  "format": "int64",
                  "example": 123456789,
                  "description": "The ID of the initial step created within the guide."
                }
              }
            }
          }
        }
      },
      "AppendStepSuccess": {
        "description": "Step successfully appended.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "stepId": {
                  "type": "integer",
                  "format": "int64",
                  "example": 123456789,
                  "description": "The ID of the newly created step."
                }
              }
            }
          }
        }
      },
      "LinkStepsSuccess": {
        "description": "Steps successfully linked.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "success": {
                  "type": "boolean",
                  "example": true,
                  "description": "Indicates successful link creation."
                }
              }
            }
          }
        }
      },
      "FolderSuccess": {
        "description": "Folder successfully created.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "folderId": {
                  "$ref": "#/components/parameters/folderId/schema"
                }
              }
            }
          }
        }
      },
      "FolderStructureSuccess": {
        "description": "Folder structure retrieved successfully.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FolderStructureItem"
                  },
                  "description": "List of folders found in the hierarchy."
                },
                "itemsCounter": {
                  "$ref": "#/components/schemas/ItemCounter"
                },
                "existsNext": {
                  "$ref": "#/components/schemas/ExistsNext"
                }
              }
            }
          }
        }
      },
      "FoldersSuccess": {
        "description": "Folder list retrieved successfully.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FolderItem"
                  },
                  "description": "List of folders in the current page."
                },
                "itemsCounter": {
                  "$ref": "#/components/schemas/ItemCounter"
                },
                "existsNext": {
                  "$ref": "#/components/schemas/ExistsNext"
                }
              }
            }
          }
        }
      },
      "GuidesSuccess": {
        "description": "Guide list retrieved successfully.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GuideItem"
                  },
                  "description": "List of guides in the current page."
                },
                "itemsCounter": {
                  "$ref": "#/components/schemas/ItemCounter"
                },
                "existsNext": {
                  "$ref": "#/components/schemas/ExistsNext"
                }
              }
            }
          }
        }
      },
      "UserSuccess": {
        "description": "User operation successful.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/User"
            }
          }
        }
      },
      "GroupsSuccess": {
        "description": "Group list retrieved successfully.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Group"
                  },
                  "description": "List of groups in the current page."
                },
                "itemsCounter": {
                  "$ref": "#/components/schemas/ItemCounter"
                },
                "existsNext": {
                  "$ref": "#/components/schemas/ExistsNext"
                }
              }
            }
          }
        }
      },
      "GroupSuccess": {
        "description": "Group operation successful.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Group"
            }
          }
        }
      },
      "Error": {
        "description": "Standard error response.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "number",
                  "example": 400,
                  "description": "HTTP status code."
                },
                "message": {
                  "type": "string",
                  "example": "Invalid parameter provided.",
                  "description": "Descriptive error message."
                }
              }
            }
          }
        }
      },
      "UserGroupsSuccess": {
        "description": "User memberships retrieved successfully.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "groups": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Group"
                  },
                  "description": "List of groups the user belongs to."
                },
                "itemsCounter": {
                  "$ref": "#/components/schemas/ItemCounter"
                },
                "existsNext": {
                  "$ref": "#/components/schemas/ExistsNext"
                }
              }
            }
          }
        }
      },
      "GroupMembersSuccess": {
        "description": "Group members retrieved successfully.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "users": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  },
                  "description": "List of users in the group."
                },
                "itemsCounter": {
                  "$ref": "#/components/schemas/ItemCounter"
                },
                "existsNext": {
                  "$ref": "#/components/schemas/ExistsNext"
                }
              }
            }
          }
        }
      },
      "CreateJobSuccess": {
        "description": "Job successfully queued.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "jobId": {
                  "type": "string",
                  "format": "uuid",
                  "example": "bb80fed6-5e0a-46a3-9245-18feaed5a59b",
                  "description": "Unique ID to track the background job."
                }
              }
            }
          }
        }
      },
      "GetJobSuccess": {
        "description": "Job status retrieved successfully.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "jobStatus": {
                  "type": "string",
                  "enum": [
                    "completed",
                    "pending",
                    "processing"
                  ],
                  "description": "Current state of the job."
                },
                "entities": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/JobElement"
                  },
                  "description": "Details of the items processed by the job."
                }
              }
            }
          }
        }
      },
      "RequestSearchSuccess": {
        "description": "Successful search request. Returns a questionAnswerId that can be used to poll for results.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "questionAnswerId"
              ],
              "properties": {
                "questionAnswerId": {
                  "$ref": "#/components/schemas/QuestionAnswerId"
                }
              }
            }
          }
        }
      },
      "GetAnswerSuccess": {
        "description": "Answer successfully generated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AiAnswersResult"
            }
          }
        }
      },
      "AnswerNotReady": {
        "description": "Answer is still generating. Retry after a short delay.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "conversationId",
                "query",
                "queryMetadata",
                "status"
              ],
              "properties": {
                "conversationId": {
                  "$ref": "#/components/schemas/ConversationId"
                },
                "query": {
                  "$ref": "#/components/schemas/Query"
                },
                "queryMetadata": {
                  "$ref": "#/components/schemas/QueryMetadata"
                },
                "status": {
                  "$ref": "#/components/schemas/Status"
                }
              }
            }
          }
        }
      },
      "GuideRecommendationSuccess": {
        "description": "Successful guide recommendation response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GuideRecommendationResult"
            }
          }
        }
      }
    },
    "schemas": {
      "Guide": {
        "type": "object",
        "properties": {
          "guideId": {
            "type": "string",
            "example": "ioTkq4uNhy"
          }
        }
      },
      "GuideCreate": {
        "type": "object",
        "required": [
          "folderId",
          "contentType",
          "contentTitle",
          "content",
          "language"
        ],
        "additionalProperties": false,
        "properties": {
          "folderId": {
            "$ref": "#/components/parameters/folderId/schema"
          },
          "contentType": {
            "type": "string",
            "enum": [
              "GUIDE",
              "ARTICLE",
              "GUIDED_TOUR"
            ],
            "description": "Type of content to create"
          },
          "contentTitle": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^(?!\\s*$).+",
            "example": "Getting Started Guide",
            "description": "Title of the guide/article (max 255 characters)"
          },
          "firstStepTitle": {
            "type": "string",
            "maxLength": 255,
            "example": "Welcome Step",
            "description": "Title of the first step (optional, max 255 characters)"
          },
          "content": {
            "type": "string",
            "maxLength": 50000,
            "example": "<p>Welcome to our guide!</p>",
            "description": "HTML content for the first step (max 50000 characters)"
          },
          "language": {
            "description": "The language of the content being created.\n\n| Code | Language | Code | Language | Code | Language |\n|---|---|---|---|---|---|\n| `af` | Afrikaans | `sq` | Albanian | `am` | Amharic |\n| `ar` | Arabic | `hy` | Armenian | `az` | Azerbaijani |\n| `eu` | Basque | `be` | Belarusian | `bn` | Bengali |\n| `bs` | Bosnian | `bg` | Bulgarian | `ca` | Catalan |\n| `ceb` | Cebuano | `zh` | Chinese (Simplified) | `zh-Hant` | Chinese (Traditional) |\n| `co` | Corsican | `hr` | Croatian | `cs` | Czech |\n| `da` | Danish | `nl` | Dutch | `en` | English |\n| `en-GB` | English (UK) | `en-US` | English (US) | `eo` | Esperanto |\n| `et` | Estonian | `fi` | Finnish | `fr` | French |\n| `fr-BE` | French (Belgium) | `fr-CA` | French (Canada) | `fy` | Frisian |\n| `gl` | Galician | `ka` | Georgian | `de` | German |\n| `de-AT` | German (Austria) | `el` | Greek | `gu` | Gujarati |\n| `ht` | Haitian Creole | `ha` | Hausa | `haw` | Hawaiian |\n| `he` | Hebrew | `hi` | Hindi | `hmn` | Hmong |\n| `hu` | Hungarian | `is` | Icelandic | `ig` | Igbo |\n| `id` | Indonesian | `ga` | Irish | `it` | Italian |\n| `ja` | Japanese | `jv` | Javanese | `kn` | Kannada |\n| `kk` | Kazakh | `km` | Khmer | `rw` | Kinyarwanda |\n| `ko` | Korean | `ku` | Kurdish | `ky` | Kyrgyz |\n| `lo` | Lao | `lv` | Latvian | `lt` | Lithuanian |\n| `lb` | Luxembourgish | `mk` | Macedonian | `mg` | Malagasy |\n| `ms` | Malay | `ml` | Malayalam | `mt` | Maltese |\n| `mi` | Maori | `mr` | Marathi | `mn` | Mongolian |\n| `my` | Myanmar (Burmese) | `nb` | Norwegian Bokmål | `ne` | Nepali |\n| `nn` | Norwegian Nynorsk | `no` | Norwegian | `ny` | Nyanja (Chichewa) |\n| `or` | Odia (Oriya) | `ps` | Pashto | `fa` | Persian |\n| `pl` | Polish | `pt` | Portuguese | `pa` | Punjabi |\n| `ro` | Romanian | `ru` | Russian | `sm` | Samoan |\n| `gd` | Scots Gaelic | `sr` | Serbian | `st` | Sesotho |\n| `sn` | Shona | `sd` | Sindhi | `si` | Sinhala |\n| `sk` | Slovak | `sl` | Slovenian | `so` | Somali |\n| `es` | Spanish | `su` | Sundanese | `sw` | Swahili |\n| `sv` | Swedish | `tl` | Tagalog (Filipino) | `tg` | Tajik |\n| `ta` | Tamil | `tt` | Tatar | `te` | Telugu |\n| `th` | Thai | `tr` | Turkish | `tk` | Turkmen |\n| `uk` | Ukrainian | `ur` | Urdu | `ug` | Uyghur |\n| `uz` | Uzbek | `vi` | Vietnamese | `cy` | Welsh |\n| `xh` | Xhosa | `yi` | Yiddish | `yo` | Yoruba |\n| `zu` | Zulu | | | | |",
            "$ref": "#/components/schemas/SupportedLanguages"
          },
          "media": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri",
              "example": "https://example.com/image.png"
            },
            "description": "Array of media URLs to attach to the guide"
          }
        }
      },
      "AppendStep": {
        "type": "object",
        "required": [
          "guideId",
          "parentStepId",
          "content"
        ],
        "additionalProperties": false,
        "properties": {
          "guideId": {
            "type": "string",
            "example": "ioTkq4uNhy",
            "description": "Unique guide ID (public identifier)"
          },
          "parentStepId": {
            "type": "integer",
            "format": "int64",
            "example": 123,
            "description": "ID of the parent step after which the new step will be added"
          },
          "title": {
            "type": "string",
            "maxLength": 255,
            "example": "Step Title",
            "description": "Title of the new step (optional, max 255 characters)"
          },
          "choiceLabel": {
            "type": "string",
            "example": "Next",
            "description": "Label for the navigation button to this step (optional)"
          },
          "content": {
            "type": "string",
            "maxLength": 50000,
            "example": "<p>This is the step content</p>",
            "description": "HTML content for the step (max 50000 characters)"
          },
          "language": {
            "description": "The language of the content being created.\n\n| Code | Language | Code | Language | Code | Language |\n|---|---|---|---|---|---|\n| `af` | Afrikaans | `sq` | Albanian | `am` | Amharic |\n| `ar` | Arabic | `hy` | Armenian | `az` | Azerbaijani |\n| `eu` | Basque | `be` | Belarusian | `bn` | Bengali |\n| `bs` | Bosnian | `bg` | Bulgarian | `ca` | Catalan |\n| `ceb` | Cebuano | `zh` | Chinese (Simplified) | `zh-Hant` | Chinese (Traditional) |\n| `co` | Corsican | `hr` | Croatian | `cs` | Czech |\n| `da` | Danish | `nl` | Dutch | `en` | English |\n| `en-GB` | English (UK) | `en-US` | English (US) | `eo` | Esperanto |\n| `et` | Estonian | `fi` | Finnish | `fr` | French |\n| `fr-BE` | French (Belgium) | `fr-CA` | French (Canada) | `fy` | Frisian |\n| `gl` | Galician | `ka` | Georgian | `de` | German |\n| `de-AT` | German (Austria) | `el` | Greek | `gu` | Gujarati |\n| `ht` | Haitian Creole | `ha` | Hausa | `haw` | Hawaiian |\n| `he` | Hebrew | `hi` | Hindi | `hmn` | Hmong |\n| `hu` | Hungarian | `is` | Icelandic | `ig` | Igbo |\n| `id` | Indonesian | `ga` | Irish | `it` | Italian |\n| `ja` | Japanese | `jv` | Javanese | `kn` | Kannada |\n| `kk` | Kazakh | `km` | Khmer | `rw` | Kinyarwanda |\n| `ko` | Korean | `ku` | Kurdish | `ky` | Kyrgyz |\n| `lo` | Lao | `lv` | Latvian | `lt` | Lithuanian |\n| `lb` | Luxembourgish | `mk` | Macedonian | `mg` | Malagasy |\n| `ms` | Malay | `ml` | Malayalam | `mt` | Maltese |\n| `mi` | Maori | `mr` | Marathi | `mn` | Mongolian |\n| `my` | Myanmar (Burmese) | `nb` | Norwegian Bokmål | `ne` | Nepali |\n| `nn` | Norwegian Nynorsk | `no` | Norwegian | `ny` | Nyanja (Chichewa) |\n| `or` | Odia (Oriya) | `ps` | Pashto | `fa` | Persian |\n| `pl` | Polish | `pt` | Portuguese | `pa` | Punjabi |\n| `ro` | Romanian | `ru` | Russian | `sm` | Samoan |\n| `gd` | Scots Gaelic | `sr` | Serbian | `st` | Sesotho |\n| `sn` | Shona | `sd` | Sindhi | `si` | Sinhala |\n| `sk` | Slovak | `sl` | Slovenian | `so` | Somali |\n| `es` | Spanish | `su` | Sundanese | `sw` | Swahili |\n| `sv` | Swedish | `tl` | Tagalog (Filipino) | `tg` | Tajik |\n| `ta` | Tamil | `tt` | Tatar | `te` | Telugu |\n| `th` | Thai | `tr` | Turkish | `tk` | Turkmen |\n| `uk` | Ukrainian | `ur` | Urdu | `ug` | Uyghur |\n| `uz` | Uzbek | `vi` | Vietnamese | `cy` | Welsh |\n| `xh` | Xhosa | `yi` | Yiddish | `yo` | Yoruba |\n| `zu` | Zulu | | | | |",
            "$ref": "#/components/schemas/SupportedLanguages"
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "example": 0,
            "description": "Position index for inserting the step among existing next steps (optional, defaults to end)"
          },
          "media": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "string",
              "format": "uri",
              "example": "https://example.com/image.png"
            },
            "description": "Array of media URLs to attach to the step (maximum 3)"
          }
        }
      },
      "LinkSteps": {
        "type": "object",
        "required": [
          "guideId",
          "sourceStepId",
          "targetStepId"
        ],
        "additionalProperties": false,
        "properties": {
          "guideId": {
            "type": "string",
            "example": "ioTkq4uNhy",
            "description": "Unique guide ID (public identifier)"
          },
          "sourceStepId": {
            "type": "integer",
            "format": "int64",
            "example": 123,
            "description": "ID of the source step from which the link will be created. Cannot be END_OF_GUIDE (-1), INTRODUCTION_TO_GUIDE (-2), EXTERNAL_LINK_FROM_GUIDE (-3), STEP_AD (-4), STEP_WIDGET_ACTION (-5), or STEP_AI_ACTION (-6)"
          },
          "targetStepId": {
            "type": "integer",
            "format": "int64",
            "example": 456,
            "description": "ID of the target step to which the link will point"
          },
          "choiceLabel": {
            "type": "string",
            "example": "Next Option",
            "description": "Label for the navigation button to the target step in the guide's default language (optional)"
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "example": 0,
            "description": "Position index for inserting the link among existing next steps (optional, defaults to end)"
          }
        }
      },
      "Access": {
        "required": [
          "email",
          "groups"
        ],
        "type": "object",
        "properties": {
          "email": {
            "$ref": "#/components/parameters/userEmailRequired/schema"
          },
          "groups": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "properties": {
                "groupId": {
                  "$ref": "#/components/parameters/groupId/schema"
                }
              }
            }
          }
        }
      },
      "Folder": {
        "type": "object",
        "properties": {
          "parentFolderId": {
            "type": "number",
            "example": 1,
            "description": "ID of the parent folder. Omit to create at the root level."
          },
          "name": {
            "type": "string",
            "example": "Example folder name",
            "description": "Name of the new folder."
          },
          "description": {
            "type": "string",
            "maxLength": 255,
            "example": "Human readable folder description",
            "description": "Optional description."
          },
          "publicAccess": {
            "type": "number",
            "enum": [
              0,
              1
            ],
            "default": 0,
            "description": "1 = Public, 0 = Private/Restricted."
          },
          "language": {
            "description": "The language of the folder.\n\n| Code | Language | Code | Language | Code | Language |\n|---|---|---|---|---|---|\n| `af` | Afrikaans | `sq` | Albanian | `am` | Amharic |\n| `ar` | Arabic | `hy` | Armenian | `az` | Azerbaijani |\n| `eu` | Basque | `be` | Belarusian | `bn` | Bengali |\n| `bs` | Bosnian | `bg` | Bulgarian | `ca` | Catalan |\n| `ceb` | Cebuano | `zh` | Chinese (Simplified) | `zh-Hant` | Chinese (Traditional) |\n| `co` | Corsican | `hr` | Croatian | `cs` | Czech |\n| `da` | Danish | `nl` | Dutch | `en` | English |\n| `en-GB` | English (UK) | `en-US` | English (US) | `eo` | Esperanto |\n| `et` | Estonian | `fi` | Finnish | `fr` | French |\n| `fr-BE` | French (Belgium) | `fr-CA` | French (Canada) | `fy` | Frisian |\n| `gl` | Galician | `ka` | Georgian | `de` | German |\n| `de-AT` | German (Austria) | `el` | Greek | `gu` | Gujarati |\n| `ht` | Haitian Creole | `ha` | Hausa | `haw` | Hawaiian |\n| `he` | Hebrew | `hi` | Hindi | `hmn` | Hmong |\n| `hu` | Hungarian | `is` | Icelandic | `ig` | Igbo |\n| `id` | Indonesian | `ga` | Irish | `it` | Italian |\n| `ja` | Japanese | `jv` | Javanese | `kn` | Kannada |\n| `kk` | Kazakh | `km` | Khmer | `rw` | Kinyarwanda |\n| `ko` | Korean | `ku` | Kurdish | `ky` | Kyrgyz |\n| `lo` | Lao | `lv` | Latvian | `lt` | Lithuanian |\n| `lb` | Luxembourgish | `mk` | Macedonian | `mg` | Malagasy |\n| `ms` | Malay | `ml` | Malayalam | `mt` | Maltese |\n| `mi` | Maori | `mr` | Marathi | `mn` | Mongolian |\n| `my` | Myanmar (Burmese) | `nb` | Norwegian Bokmål | `ne` | Nepali |\n| `nn` | Norwegian Nynorsk | `no` | Norwegian | `ny` | Nyanja (Chichewa) |\n| `or` | Odia (Oriya) | `ps` | Pashto | `fa` | Persian |\n| `pl` | Polish | `pt` | Portuguese | `pa` | Punjabi |\n| `ro` | Romanian | `ru` | Russian | `sm` | Samoan |\n| `gd` | Scots Gaelic | `sr` | Serbian | `st` | Sesotho |\n| `sn` | Shona | `sd` | Sindhi | `si` | Sinhala |\n| `sk` | Slovak | `sl` | Slovenian | `so` | Somali |\n| `es` | Spanish | `su` | Sundanese | `sw` | Swahili |\n| `sv` | Swedish | `tl` | Tagalog (Filipino) | `tg` | Tajik |\n| `ta` | Tamil | `tt` | Tatar | `te` | Telugu |\n| `th` | Thai | `tr` | Turkish | `tk` | Turkmen |\n| `uk` | Ukrainian | `ur` | Urdu | `ug` | Uyghur |\n| `uz` | Uzbek | `vi` | Vietnamese | `cy` | Welsh |\n| `xh` | Xhosa | `yi` | Yiddish | `yo` | Yoruba |\n| `zu` | Zulu | | | | |",
            "$ref": "#/components/schemas/SupportedLanguages"
          }
        }
      },
      "Group": {
        "required": [
          "name"
        ],
        "type": "object",
        "properties": {
          "groupId": {
            "allOf": [
              {
                "$ref": "#/components/parameters/groupId/schema"
              },
              {
                "readOnly": true
              }
            ]
          },
          "name": {
            "type": "string",
            "maxLength": 100,
            "example": "Support Agents Tier 1",
            "description": "Group name. Must be unique for your account."
          },
          "description": {
            "type": "string",
            "maxLength": 255,
            "example": "Agents handling first-line support inquiries.",
            "description": "Optional description."
          }
        }
      },
      "SupportedLanguages": {
        "type": "string",
        "description": "The ISO 639-1 language code (with some regional variants). Supported values map as follows:\n\n| Code | Language | Code | Language | Code | Language |\n|---|---|---|---|---|---|\n| `am` | Amharic | `ar` | Arabic | `bg` | Bulgarian |\n| `bn` | Bengali | `bs` | Bosnian | `ca` | Catalan |\n| `cn` | Montenegrin | `cs` | Czech | `cy` | Welsh |\n| `da` | Danish | `de` | German | `de-AT` | German (Austria) |\n| `de-CH` | German (Switzerland) | `el` | Greek | `en` | English |\n| `en-GB` | English (UK) | `en-US` | English (US) | `es` | Spanish |\n| `es-CL` | Spanish (Chile) | `es-EC` | Spanish (Ecuador) | `et` | Estonian |\n| `eu` | Basque | `fa` | Persian | `fi` | Finnish |\n| `fr` | French | `fr-BE` | French (Belgium) | `fr-CA` | French (Canada) |\n| `ga` | Irish | `gd` | Scots Gaelic | `he` | Hebrew |\n| `hi` | Hindi | `hr` | Croatian | `hu` | Hungarian |\n| `hy` | Armenian | `id` | Indonesian | `is` | Icelandic |\n| `it` | Italian | `ja` | Japanese | `kn` | Kannada |\n| `ko` | Korean | `lt` | Lithuanian | `lv` | Latvian |\n| `mi` | Maori | `mk` | Macedonian | `nb` | Norwegian Bokmål |\n| `nl` | Dutch | `nl-BE` | Flemish | `nn` | Norwegian Nynorsk |\n| `no` | Norwegian | `pl` | Polish | `pt` | Portuguese |\n| `pt-BR` | Portuguese (Brazil) | `ro` | Romanian | `ru` | Russian |\n| `sk` | Slovak | `sl` | Slovenian | `sq` | Albanian |\n| `sr` | Serbian | `sv` | Swedish | `sw` | Swahili |\n| `th` | Thai | `tl` | Tagalog (Filipino) | `tr` | Turkish |\n| `uk` | Ukrainian | `ur` | Urdu | `vi` | Vietnamese |\n| `zh` | Chinese (Simplified) | `zh-Hant` | Chinese (Traditional) | | |",
        "enum": [
          "am",
          "ar",
          "bg",
          "bn",
          "bs",
          "ca",
          "cn",
          "cs",
          "cy",
          "da",
          "de",
          "de-AT",
          "de-CH",
          "el",
          "en",
          "en-GB",
          "en-US",
          "es",
          "es-CL",
          "es-EC",
          "et",
          "eu",
          "fa",
          "fi",
          "fr",
          "fr-BE",
          "fr-CA",
          "ga",
          "gd",
          "he",
          "hi",
          "hr",
          "hu",
          "hy",
          "id",
          "is",
          "it",
          "ja",
          "kn",
          "ko",
          "lt",
          "lv",
          "mi",
          "mk",
          "nb",
          "nl",
          "nl-BE",
          "nn",
          "no",
          "pl",
          "pt",
          "pt-BR",
          "ro",
          "ru",
          "sk",
          "sl",
          "sq",
          "sr",
          "sv",
          "sw",
          "th",
          "tl",
          "tr",
          "uk",
          "ur",
          "vi",
          "zh",
          "zh-Hant"
        ]
      },
      "SearchSupportedLanguages": {
        "type": "string",
        "description": "Language code used for the AI search query. Supported values map as follows:\n\n| Code | Language |\n|---|---|\n| `en` | English |\n| `en-US` | English (United States) |\n| `en-GB` | English (United Kingdom) |\n| `fr` | French |\n| `fr-BE` | French (Belgium) |\n| `fr-CA` | French (Canada) |\n| `de` | German |\n| `nl` | Dutch |\n| `nl-BE` | Flemish |\n| `es` | Spanish |\n| `it` | Italian |\n| `pt` | Portuguese |\n| `pt-BR` | Portuguese (Brazil) |\n| `pl` | Polish |\n| `sv` | Swedish |\n| `no` | Norwegian |\n| `nb` | Norwegian Bokmål |\n| `nn` | Norwegian Nynorsk |\n| `fi` | Finnish |\n| `hi` | Hindi |\n| `bn` | Bengali |\n| `mr` | Marathi |\n| `te` | Telugu |\n| `ta` | Tamil |\n| `ko` | Korean |\n| `ja` | Japanese |\n| `tr` | Turkish |\n| `ca` | Catalan |",
        "enum": [
          "en",
          "en-US",
          "en-GB",
          "fr",
          "fr-BE",
          "fr-CA",
          "de",
          "nl",
          "nl-BE",
          "es",
          "it",
          "pt",
          "pt-BR",
          "pl",
          "sv",
          "no",
          "nb",
          "nn",
          "fi",
          "hi",
          "bn",
          "mr",
          "te",
          "ta",
          "ko",
          "ja",
          "tr",
          "ca"
        ]
      },
      "TeamAccess": {
        "required": [
          "email",
          "teams"
        ],
        "type": "object",
        "properties": {
          "email": {
            "$ref": "#/components/parameters/userEmailRequired/schema"
          },
          "teams": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "teamId": {
                  "$ref": "#/components/parameters/teamId/schema"
                }
              }
            }
          }
        }
      },
      "User": {
        "required": [
          "email"
        ],
        "type": "object",
        "properties": {
          "userId": {
            "allOf": [
              {
                "$ref": "#/components/parameters/userId/schema"
              },
              {
                "readOnly": true
              }
            ]
          },
          "email": {
            "$ref": "#/components/parameters/userEmail/schema"
          },
          "firstName": {
            "type": "string",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "example": "Smith"
          },
          "role": {
            "type": "string",
            "enum": [
              "member",
              "admin"
            ],
            "description": "Access level in the team."
          }
        }
      },
      "UserUpdate": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "newEmail": {
            "$ref": "#/components/parameters/userEmailRequired/schema"
          },
          "firstName": {
            "type": "string",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "example": "Smith"
          },
          "role": {
            "type": "string",
            "enum": [
              "member",
              "admin"
            ]
          }
        }
      },
      "ItemCounter": {
        "type": "integer",
        "format": "int32",
        "description": "Total number of items available."
      },
      "ExistsNext": {
        "type": "boolean",
        "description": "True if more pages of results are available."
      },
      "Answer": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "conversationId": {
            "$ref": "#/components/parameters/conversationId/schema"
          }
        }
      },
      "PublishGuide": {
        "type": "object",
        "additionalProperties": false,
        "example": {
          "guideList": [
            {
              "guideId": "ioTkq4uNhz"
            },
            {
              "guideId": "oeTk34uLhu"
            }
          ]
        },
        "properties": {
          "guideList": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/Guide"
            },
            "description": "List of guide IDs to publish."
          }
        },
        "required": [
          "guideList"
        ]
      },
      "GuideAccess": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "guideList": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "guideId": {
                  "type": "string",
                  "example": "ioTkq4uNhy"
                },
                "publicAccess": {
                  "type": "number",
                  "enum": [
                    0,
                    1
                  ],
                  "default": 0,
                  "description": "1 - public, 0 - no access"
                }
              }
            }
          }
        },
        "required": [
          "guideList"
        ]
      },
      "GuideMove": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "targetFolderId",
          "guideList"
        ],
        "properties": {
          "targetFolderId": {
            "$ref": "#/components/parameters/folderId/schema"
          },
          "guideList": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/Guide"
            }
          }
        }
      },
      "GuideCopy": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "targetFolderId",
          "guideList"
        ],
        "properties": {
          "targetFolderId": {
            "$ref": "#/components/parameters/folderId/schema"
          },
          "guideList": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "required": [
                "guideId"
              ],
              "type": "object",
              "properties": {
                "guideId": {
                  "$ref": "#/components/schemas/Guide/properties/guideId"
                },
                "defaultName": {
                  "type": "string",
                  "example": "New default name for all languages",
                  "description": "Default name for language versions not defined in the “names” field"
                },
                "names": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  },
                  "example": {
                    "pl": "Nowa nazwa",
                    "en": "New name"
                  },
                  "description": "New name in different languages. An object in which the “key” is the supported language in the guide, and the “value” is the new name in that language."
                }
              }
            }
          }
        }
      },
      "JobElement": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "example": "ioTkq4uNhy",
            "description": "ID of the entity being processed (e.g., guide ID)."
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "pending",
              "failed",
              "processing"
            ]
          },
          "data": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "duplicateGuideId": {
                    "$ref": "#/components/schemas/Guide/properties/guideId"
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "object",
                "additionalProperties": false
              }
            ]
          },
          "error": {
            "type": "string",
            "example": "Guide already published"
          }
        },
        "required": [
          "id",
          "status"
        ]
      },
      "FolderItem": {
        "type": "object",
        "properties": {
          "entityId": {
            "type": "number",
            "example": 1,
            "description": "Folder ID"
          },
          "entityName": {
            "type": "string",
            "example": "Example folder name",
            "description": "Folder Name"
          }
        }
      },
      "GuideItem": {
        "type": "object",
        "properties": {
          "entityId": {
            "type": "string",
            "example": "ioTkq4uNhy",
            "description": "Guide ID"
          },
          "entityName": {
            "type": "string",
            "example": "Example guide name"
          },
          "entityStatus": {
            "type": "string",
            "example": "draft"
          },
          "entityLanguages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SupportedLanguages"
            },
            "example": [
              "en",
              "pl",
              "ru",
              "ar",
              "et"
            ]
          },
          "entityFolder": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "integer",
                "format": "int64",
                "example": 33836
              },
              "name": {
                "type": "string",
                "example": "Cypress Visual Smoke Tests"
              }
            }
          }
        }
      },
      "FolderStructureItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "example": 33836
          },
          "name": {
            "type": "string",
            "example": "Cypress Visual Smoke Tests"
          },
          "parentId": {
            "type": "integer",
            "format": "int64",
            "example": 33836,
            "nullable": true,
            "description": "ID of the parent folder (null for root)."
          }
        },
        "required": [
          "id",
          "name",
          "parentId"
        ]
      },
      "ExportedNextStep": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "choiceLabel": {
            "type": "string",
            "example": "Continue",
            "description": "Text displayed on the button/link leading to this step."
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "example": 123,
            "description": "ID of the next step."
          }
        },
        "required": [
          "choiceLabel",
          "id"
        ]
      },
      "ExportedStep": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "example": 10
          },
          "title": {
            "type": "string",
            "example": "Welcome"
          },
          "isFirstStep": {
            "type": "boolean",
            "example": true
          },
          "content": {
            "type": "string",
            "example": "Step content or metadata depending on type",
            "description": "The meaning of this field depends on the value of the 'type' field. For embedded guides (type='embeddedContent'), this contains the guideId string."
          },
          "type": {
            "type": "string",
            "description": "Step type",
            "enum": [
              "regular",
              "nps",
              "crs",
              "contactForm",
              "guide",
              "iframe",
              "checklist",
              "aiAnswer",
              "automation",
              "endGuide",
              "introduction",
              "link",
              "ad",
              "widgetAction",
              "aiAction"
            ],
            "example": "regular"
          },
          "nextSteps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportedNextStep"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Product",
              "Feature"
            ],
            "description": "Array of tag names for this step in the requested language (or guide's default language as fallback)"
          },
          "meta": {
            "type": "object",
            "properties": {
              "embeddedStepId": {
                "type": "integer",
                "format": "int64",
                "description": "Step ID for embedded guides (type='embeddedContent'). Specifies which step to start from in the embedded guide."
              },
              "embeddedGuideId": {
                "type": "string",
                "description": "Guide ID for embedded guides (type='embeddedContent'). The unique identifier of the embedded guide."
              }
            },
            "description": "Additional metadata for specific step types. Only present for embedded content steps."
          },
          "modules": {
            "type": "array",
            "description": "Step modules included when purpose is 'BPA'. Contains INPUT, CONTACT_FORM, BPA_METADATA and other non-content modules with their properties and localized content.",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Module type identifier (e.g. INPUT, FORM, BPA_METADATA, EMBEDDED_GUIDE, CHECKLIST_ITEM, CONDITIONAL_SECTION)."
                },
                "properties": {
                  "type": "object",
                  "description": "Module-specific properties."
                },
                "content": {
                  "type": "object",
                  "description": "Localized content keyed by language code."
                },
                "options": {
                  "type": "object",
                  "description": "Additional options (e.g. for embedded guides)."
                }
              },
              "required": ["type"]
            }
          }
        },
        "required": [
          "id",
          "title",
          "isFirstStep",
          "content",
          "type",
          "nextSteps",
          "tags"
        ]
      },
      "RequestSearch": {
        "required": [
          "query",
          "language",
          "aiAgentId"
        ],
        "type": "object",
        "properties": {
          "query": {
            "description": "Query for which an answer is to be generated",
            "type": "string",
            "example": "How to create Stonly guide?"
          },
          "language": {
            "description": "Language used for the AI search query.\n\n| Code | Language |\n|---|---|\n| `en` | English |\n| `en-US` | English (United States) |\n| `en-GB` | English (United Kingdom) |\n| `fr` | French |\n| `fr-BE` | French (Belgium) |\n| `fr-CA` | French (Canada) |\n| `de` | German |\n| `nl` | Dutch |\n| `es` | Spanish |\n| `it` | Italian |\n| `pt` | Portuguese |\n| `pt-BR` | Portuguese (Brazil) |\n| `pl` | Polish |\n| `sv` | Swedish |\n| `no` | Norwegian |\n| `nb` | Norwegian Bokmål |\n| `nn` | Norwegian Nynorsk |\n| `fi` | Finnish |",
            "$ref": "#/components/schemas/SearchSupportedLanguages"
          },
          "aiAgentId": {
            "description": "ID of Ai Agent defining configuration for a search",
            "type": "integer",
            "format": "int32",
            "minimum": 1
          },
          "conversationId": {
            "$ref": "#/components/parameters/conversationId/schema"
          },
          "kbBaseUrl": {
            "description": "Optional base URL for the knowledge base. If provided, this value will be prepended to KB links generated in the response.",
            "type": "string",
            "format": "uri",
            "example": "https://example.com"
          },
          "userEmail": {
            "$ref": "#/components/parameters/userEmail/schema"
          },
          "webhookUrl": {
            "$ref": "#/components/parameters/webhookUrl/schema"
          }
        }
      },
      "ConversationId": {
        "type": "string",
        "format": "uuid",
        "example": "928b59ad-f24d-44b2-933f-4c88fbcc75c7",
        "description": "Unique identifier for the current conversation"
      },
      "QuestionAnswerId": {
        "type": "string",
        "format": "uuid",
        "example": "92c3c11c-5a2b-4814-a97d-cf2e0e5256a9",
        "description": "Unique identifier for the generated AI answer"
      },
      "UserEmail": {
        "type": "string",
        "format": "email",
        "example": "user@example.com",
        "description": "Email address of the user who triggered the AI query"
      },
      "WebhookUrl": {
        "type": "string",
        "format": "uri",
        "example": "https://example.com/webhook",
        "description": "Webhook URL used to deliver the final answer asynchronously"
      },
      "KbBaseUrl": {
        "type": "string",
        "format": "uri",
        "example": "https://example.com",
        "description": "Base URL of the knowledge base used by the AI agent"
      },
      "QueryMetadata": {
        "type": "object",
        "description": "Metadata describing the query context",
        "properties": {
          "language": {
            "type": "string",
            "example": "en"
          },
          "aiAgentId": {
            "type": "integer",
            "example": 736
          },
          "userEmail": {
            "$ref": "#/components/schemas/UserEmail"
          },
          "webhookUrl": {
            "$ref": "#/components/schemas/WebhookUrl"
          },
          "kbBaseUrl": {
            "$ref": "#/components/schemas/KbBaseUrl"
          }
        }
      },
      "Status": {
        "type": "string",
        "enum": [
          "NEW",
          "IN_PROGRESS",
          "COMPLETED",
          "FAILED"
        ],
        "example": "IN_PROGRESS",
        "description": "Current processing status of the answer"
      },
      "Query": {
        "type": "string",
        "example": "What is Stonly?",
        "description": "Original query submitted by the user"
      },
      "AnswerMetadata": {
        "type": "object",
        "properties": {
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "example": "https://example.com/"
                }
              }
            }
          },
          "language": {
            "type": "string",
            "example": "en"
          },
          "isFallback": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "AiAnswersResult": {
        "type": "object",
        "required": [
          "questionAnswerId",
          "conversationId",
          "query",
          "queryMetadata",
          "answer",
          "answerMetadata",
          "status"
        ],
        "properties": {
          "questionAnswerId": {
            "$ref": "#/components/schemas/QuestionAnswerId"
          },
          "conversationId": {
            "$ref": "#/components/schemas/ConversationId"
          },
          "query": {
            "$ref": "#/components/schemas/Query"
          },
          "queryMetadata": {
            "$ref": "#/components/schemas/QueryMetadata"
          },
          "answer": {
            "type": "string",
            "example": "<p>Stonly is an AI-powered knowledge management platform...</p>"
          },
          "answerMetadata": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/AnswerMetadata"
              },
              {
                "$ref": "#/components/schemas/ClarificationAnswerMetadata"
              },
              {
                "$ref": "#/components/schemas/GuidedAnswer"
              }
            ],
            "description": "Metadata describing the generated answer; can include fallback, clarification, or guided answer information."
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          }
        }
      },
      "GuidedAnswer": {
        "type": "object",
        "required": [
          "intentRecognised",
          "guideId",
          "stepId",
          "guideLaunchMode",
          "language",
          "originalQuestion",
          "phrase",
          "detectedIntent",
          "answerText",
          "linkText"
        ],
        "properties": {
          "intentRecognised": {
            "type": "integer",
            "example": 1,
            "description": "Indicates if an intent was successfully recognized (1 = yes, 0 = no)"
          },
          "guideId": {
            "type": "string",
            "example": "g123",
            "description": "Identifier of the guide to be launched"
          },
          "stepId": {
            "type": "string",
            "example": "s456",
            "description": "Identifier of the guide step to start from"
          },
          "guideLaunchMode": {
            "type": "string",
            "enum": [
              "redirected",
              "embedded",
              "customMessage",
              "bpa"
            ],
            "example": "embedded",
            "description": "Determines how the guide should be launched"
          },
          "language": {
            "type": "string",
            "example": "en"
          },
          "originalQuestion": {
            "type": "string",
            "example": "How do I reset my password?"
          },
          "phrase": {
            "type": "string",
            "example": "password reset"
          },
          "detectedIntent": {
            "type": "string",
            "example": "reset_password"
          },
          "answerText": {
            "type": "string",
            "example": "You can reset your password by visiting the account settings page."
          },
          "linkText": {
            "type": "string",
            "example": "Open password settings"
          }
        }
      },
      "ClarificationAnswerMetadata": {
        "type": "object",
        "properties": {
          "clarificationOptions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Reset password",
              "Change email"
            ]
          },
          "clarificationCustomerExplanation": {
            "type": "string",
            "example": "The system was unsure which intent you meant."
          },
          "queryIsAmbiguous": {
            "type": "boolean",
            "example": true
          },
          "originalQuestion": {
            "type": "string",
            "example": "How do I change account details?"
          },
          "phrase": {
            "type": "string",
            "example": "account change"
          },
          "gptModel": {
            "type": "string",
            "example": "gpt-4o"
          }
        }
      },
      "RaisedIssue": {
        "type": "object",
        "required": [
          "issue"
        ],
        "properties": {
          "issue": {
            "type": "string",
            "maxLength": 5000,
            "description": "The issue/subproblem text",
            "example": "Trigger is not showing up despite enabling the Stonly extension"
          },
          "resolved": {
            "type": "boolean",
            "default": false,
            "description": "Whether the issue has been resolved"
          },
          "resolutionSummary": {
            "type": "string",
            "description": "Summary of how the issue was resolved (if resolved)"
          }
        }
      },
      "GuideRecommendationInput": {
        "type": "object",
        "required": [
          "raisedIssues"
        ],
        "description": "Input structure matching TicketProblemsAndFacts from v1 AI Agent Assist",
        "properties": {
          "raisedIssues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RaisedIssue"
            },
            "maxItems": 100,
            "description": "List of issues/subproblems to find recommendations for"
          },
          "priorUserActions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Steps the user has already taken"
          },
          "errorMessages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Error messages encountered"
          },
          "technicalDetails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Technical details relevant to the issues"
          }
        }
      },
      "GuideRecommendationRequest": {
        "type": "object",
        "required": [
          "issues",
          "kbId"
        ],
        "properties": {
          "issues": {
            "$ref": "#/components/schemas/GuideRecommendationInput"
          },
          "kbId": {
            "type": "integer",
            "format": "int32",
            "minimum": 1,
            "description": "Knowledge Base ID to search within"
          },
          "tagFilter": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tag IDs to filter search results. Only applied if searchFiltersEnabled is true in AI agent configuration."
          },
          "includeDebug": {
            "type": "boolean",
            "default": false,
            "description": "Include timing and query debug information in the response"
          }
        }
      },
      "RecommendedGuide": {
        "type": "object",
        "properties": {
          "guideId": {
            "type": "string",
            "example": "ULCR6fsl0C",
            "description": "Unique guide identifier"
          },
          "guideType": {
            "type": "string",
            "enum": [
              "GUIDE",
              "ARTICLE",
              "CHECKLIST"
            ],
            "example": "GUIDE",
            "description": "Type of the guide"
          },
          "stepId": {
            "type": "integer",
            "format": "int64",
            "example": 3864161,
            "description": "ID of the most relevant step"
          },
          "stepTitle": {
            "type": "string",
            "example": "Type of trigger",
            "description": "Title of the most relevant step"
          },
          "title": {
            "type": "string",
            "example": "Stonly Widget troubleshooting guide",
            "description": "Title of the guide"
          },
          "type": {
            "type": "string",
            "enum": [
              "keyword",
              "semantic"
            ],
            "example": "keyword",
            "description": "Search type that found this guide"
          },
          "content": {
            "type": "string",
            "description": "Relevant content snippet from the guide"
          },
          "score": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "example": 0.85,
            "description": "Reranked relevance score (0-1, higher is more relevant)"
          }
        }
      },
      "GuideRecommendationDebug": {
        "type": "object",
        "properties": {
          "queryExpansionTime": {
            "type": "integer",
            "example": 1234,
            "description": "Time in milliseconds for query expansion"
          },
          "searchTime": {
            "type": "integer",
            "example": 567,
            "description": "Time in milliseconds for searches and sufficiency checks"
          },
          "issueCount": {
            "type": "integer",
            "example": 2,
            "description": "Number of issues processed after query expansion"
          }
        }
      },
      "GuideRecommendationResultItem": {
        "type": "object",
        "required": [
          "issue",
          "guides",
          "guidesForGeneration",
          "verdict",
          "explanation",
          "generationVerdict",
          "generationExplanation"
        ],
        "properties": {
          "issue": {
            "type": "string",
            "description": "The issue text",
            "example": "Trigger is not showing up despite enabling the Stonly extension"
          },
          "guides": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecommendedGuide"
            },
            "description": "List of recommended guides for display (isClientFacingAnswerGeneration=false)"
          },
          "guidesForGeneration": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecommendedGuide"
            },
            "description": "List of recommended guides optimized for AI answer generation (isClientFacingAnswerGeneration=true)"
          },
          "verdict": {
            "type": "boolean",
            "description": "Whether the display guides are sufficient to address the issue",
            "example": true
          },
          "explanation": {
            "type": "string",
            "description": "Explanation of the display guides sufficiency verdict",
            "example": "The guides provide sufficient information to address the issue"
          },
          "generationVerdict": {
            "type": "boolean",
            "description": "Whether the generation guides are sufficient for AI answer generation",
            "example": true
          },
          "generationExplanation": {
            "type": "string",
            "description": "Explanation of the generation guides sufficiency verdict",
            "example": "The guides contain enough context for generating a comprehensive answer"
          }
        }
      },
      "GuideRecommendationResult": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GuideRecommendationResultItem"
            },
            "description": "Recommendation results for each issue"
          },
          "debug": {
            "$ref": "#/components/schemas/GuideRecommendationDebug"
          }
        }
      }
    },
    "requestBodies": {
      "GuideCreate": {
        "description": "Details for the guide to be created.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GuideCreate"
            }
          }
        },
        "required": true
      },
      "AppendStep": {
        "description": "Details of the step to append.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AppendStep"
            }
          }
        },
        "required": true
      },
      "LinkSteps": {
        "description": "Source and target step IDs to link.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/LinkSteps"
            }
          }
        },
        "required": true
      },
      "FolderCreate": {
        "description": "Details for the folder to be created.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Folder"
            }
          }
        },
        "required": true
      },
      "Group": {
        "description": "Group creation details.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Group"
            }
          }
        },
        "required": true
      },
      "User": {
        "description": "User creation details.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/User"
            }
          }
        },
        "required": true
      },
      "UserUpdate": {
        "description": "User update details.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/UserUpdate"
            }
          }
        },
        "required": true
      },
      "UserWithGroupNames": {
        "description": "User object with group associations.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/User"
                },
                {
                  "properties": {
                    "groupNames": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "example": [
                          "Support Agents",
                          "Admins"
                        ]
                      }
                    }
                  }
                }
              ]
            }
          }
        },
        "required": true
      },
      "Access": {
        "description": "User email and list of groups to modify access for.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Access"
            }
          }
        }
      },
      "TeamAccess": {
        "description": "User email and list of teams to grant access to.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TeamAccess"
            }
          }
        }
      },
      "PublishGuide": {
        "description": "List of guides to publish.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PublishGuide"
            }
          }
        },
        "required": true
      },
      "GuideAccess": {
        "description": "List of guides to update access for.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GuideAccess"
            }
          }
        },
        "required": true
      },
      "GuideMove": {
        "description": "Target folder and list of guides to move.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GuideMove"
            }
          }
        },
        "required": true
      },
      "GuideCopy": {
        "description": "Target folder and list of guides to copy.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GuideCopy"
            }
          }
        },
        "required": true
      },
      "RequestSearch": {
        "description": "Search query and configuration.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RequestSearch"
            }
          }
        }
      },
      "GuideRecommendation": {
        "description": "Guide recommendation request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GuideRecommendationRequest"
            }
          }
        },
        "required": true
      }
    },
    "parameters": {
      "folderId": {
        "name": "folderId",
        "in": "query",
        "description": "The unique identifier of the folder.",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 123
        }
      },
      "userEmailRequired": {
        "name": "email",
        "in": "query",
        "description": "The unique email address of the user.",
        "required": true,
        "schema": {
          "type": "string",
          "format": "email",
          "example": "john@example.com"
        }
      },
      "teamId": {
        "name": "teamId",
        "in": "query",
        "description": "ID of the team to manage. Optional if the API key is associated with a single team.",
        "required": false,
        "schema": {
          "type": "integer",
          "format": "int32"
        }
      },
      "userEmail": {
        "name": "email",
        "in": "query",
        "description": "User email address.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "email",
          "example": "john@example.com"
        }
      },
      "userId": {
        "name": "userId",
        "in": "query",
        "description": "Unique UUID of the user.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "bb80fed6-5e0a-46a3-9245-18feaed5a59b"
        }
      },
      "groupId": {
        "name": "groupId",
        "in": "query",
        "description": "The unique identifier of the group.",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 123
        }
      },
      "groupIdList": {
        "name": "groups",
        "in": "query",
        "description": "A comma-separated list or array of Group IDs.",
        "required": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "integer",
            "format": "int64",
            "example": 123
          }
        }
      },
      "teamIdList": {
        "name": "teams",
        "in": "query",
        "description": "A comma-separated list or array of Team IDs.",
        "required": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "integer",
            "format": "int64",
            "example": 123
          }
        }
      },
      "page": {
        "name": "page",
        "in": "query",
        "description": "Page number for pagination (0-based index).",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 0
        }
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "description": "Number of items to return per page (maximum 100).",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 100
        }
      },
      "guideStatus": {
        "name": "guideStatus",
        "in": "query",
        "description": "Filter guides by their publication status.",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "draft",
            "published"
          ]
        }
      },
      "nameList": {
        "name": "names",
        "in": "query",
        "description": "Filter items where the name contains one of these strings.",
        "required": false,
        "schema": {
          "type": "array",
          "maxItems": 5,
          "items": {
            "type": "string",
            "example": "Folder name"
          }
        }
      },
      "tagList": {
        "name": "tags",
        "in": "query",
        "description": "Filter items that have at least one of these tags.",
        "required": false,
        "schema": {
          "type": "array",
          "maxItems": 5,
          "items": {
            "type": "string",
            "example": "Tag name"
          }
        }
      },
      "jobId": {
        "name": "jobId",
        "in": "query",
        "description": "The unique UUID of the background job.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "contentId": {
        "name": "contentId",
        "in": "query",
        "description": "Unique guide identifier (referred to as contentId in exports).",
        "required": true,
        "schema": {
          "type": "string",
          "example": "ioTkq4uNhy"
        }
      },
      "language": {
        "name": "language",
        "in": "query",
        "description": "Language version to export. If omitted, the default language is used. Supported values:\n\n| Code | Language | Code | Language | Code | Language |\n|---|---|---|---|---|---|\n| `af` | Afrikaans | `sq` | Albanian | `am` | Amharic |\n| `ar` | Arabic | `hy` | Armenian | `az` | Azerbaijani |\n| `eu` | Basque | `be` | Belarusian | `bn` | Bengali |\n| `bs` | Bosnian | `bg` | Bulgarian | `ca` | Catalan |\n| `ceb` | Cebuano | `zh` | Chinese (Simplified) | `zh-Hant` | Chinese (Traditional) |\n| `co` | Corsican | `hr` | Croatian | `cs` | Czech |\n| `da` | Danish | `nl` | Dutch | `en` | English |\n| `en-GB` | English (UK) | `en-US` | English (US) | `eo` | Esperanto |\n| `et` | Estonian | `fi` | Finnish | `fr` | French |\n| `fr-BE` | French (Belgium) | `fr-CA` | French (Canada) | `fy` | Frisian |\n| `gl` | Galician | `ka` | Georgian | `de` | German |\n| `de-AT` | German (Austria) | `el` | Greek | `gu` | Gujarati |\n| `ht` | Haitian Creole | `ha` | Hausa | `haw` | Hawaiian |\n| `he` | Hebrew | `hi` | Hindi | `hmn` | Hmong |\n| `hu` | Hungarian | `is` | Icelandic | `ig` | Igbo |\n| `id` | Indonesian | `ga` | Irish | `it` | Italian |\n| `ja` | Japanese | `jv` | Javanese | `kn` | Kannada |\n| `kk` | Kazakh | `km` | Khmer | `rw` | Kinyarwanda |\n| `ko` | Korean | `ku` | Kurdish | `ky` | Kyrgyz |\n| `lo` | Lao | `lv` | Latvian | `lt` | Lithuanian |\n| `lb` | Luxembourgish | `mk` | Macedonian | `mg` | Malagasy |\n| `ms` | Malay | `ml` | Malayalam | `mt` | Maltese |\n| `mi` | Maori | `mr` | Marathi | `mn` | Mongolian |\n| `my` | Myanmar (Burmese) | `nb` | Norwegian Bokmål | `ne` | Nepali |\n| `nn` | Norwegian Nynorsk | `no` | Norwegian | `ny` | Nyanja (Chichewa) |\n| `or` | Odia (Oriya) | `ps` | Pashto | `fa` | Persian |\n| `pl` | Polish | `pt` | Portuguese | `pa` | Punjabi |\n| `ro` | Romanian | `ru` | Russian | `sm` | Samoan |\n| `gd` | Scots Gaelic | `sr` | Serbian | `st` | Sesotho |\n| `sn` | Shona | `sd` | Sindhi | `si` | Sinhala |\n| `sk` | Slovak | `sl` | Slovenian | `so` | Somali |\n| `es` | Spanish | `su` | Sundanese | `sw` | Swahili |\n| `sv` | Swedish | `tl` | Tagalog (Filipino) | `tg` | Tajik |\n| `ta` | Tamil | `tt` | Tatar | `te` | Telugu |\n| `th` | Thai | `tr` | Turkish | `tk` | Turkmen |\n| `uk` | Ukrainian | `ur` | Urdu | `ug` | Uyghur |\n| `uz` | Uzbek | `vi` | Vietnamese | `cy` | Welsh |\n| `xh` | Xhosa | `yi` | Yiddish | `yo` | Yoruba |\n| `zu` | Zulu | | | | |",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/SupportedLanguages"
        }
      },
      "version": {
        "name": "version",
        "in": "query",
        "description": "Which version of the guide to export. Defaults to 'last_published_version'.",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "last_published_version",
            "last_saved_version",
            "last_saved"
          ],
          "default": "last_published_version"
        }
      },
      "purpose": {
        "name": "purpose",
        "in": "query",
        "description": "Controls which set of step modules to include in the export. 'EXPORT' returns the standard set. 'BPA' additionally includes INPUT and CONTACT_FORM modules. Defaults to 'EXPORT'.",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "EXPORT",
            "BPA"
          ],
          "default": "EXPORT"
        }
      },
      "updatedDateFrom": {
        "name": "updatedDateFrom",
        "in": "query",
        "description": "Filter content updated on or after this date (inclusive). Format: YYYY-MM-DD.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date",
          "example": "2025-09-01"
        }
      },
      "updatedDateTo": {
        "name": "updatedDateTo",
        "in": "query",
        "description": "Filter content updated before this date (exclusive). Format: YYYY-MM-DD.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date",
          "example": "2025-10-01"
        }
      },
      "publishedDateFrom": {
        "name": "publishedDateFrom",
        "in": "query",
        "description": "Filter content published on or after this date (inclusive). Format: YYYY-MM-DD.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date",
          "example": "2025-09-01"
        }
      },
      "publishedDateTo": {
        "name": "publishedDateTo",
        "in": "query",
        "description": "Filter content published before this date (exclusive). Format: YYYY-MM-DD.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date",
          "example": "2025-10-01"
        }
      },
      "recursive": {
        "name": "recursive",
        "in": "query",
        "description": "If `true`, includes items from the specified folder and all its subfolders. If `false`, returns only direct children.",
        "required": false,
        "schema": {
          "type": "boolean",
          "default": false
        }
      },
      "conversationId": {
        "name": "conversationId",
        "in": "query",
        "description": "Unique UUID of the conversation.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "928b59ad-f24d-44b2-933f-4c88fbcc75c7"
        }
      },
      "webhookUrl": {
        "name": "webhookUrl",
        "in": "query",
        "description": "URL callback for asynchronous answer delivery.",
        "required": false,
        "schema": {
          "type": "string",
          "format": "uri",
          "example": "https://example.com/answer"
        }
      },
      "questionAnswerId": {
        "name": "questionAnswerId",
        "in": "query",
        "description": "Unique UUID of the specific question/answer interaction.",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "048a3878-18cb-4aac-a821-6bcef12ac014"
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}