{
  "openapi": "3.0.3",
  "info": {
    "title": "bs4 API — BS4 Core",
    "version": "1.02",
    "description": "REST API of each BS4 Core installation. Use your own installation URL, including its subfolder. The documentation domain is not your API server. Class and field aliases and allowed operations are specific to each connector: obtain them from developer help in BS4. API 1.02 requires installation of the corresponding BS4 update. MCP is a separate connector and protocol."
  },
  "tags": [
    {
      "name": "Simple -  Create / Read / Update / Delete",
      "description": "Simple commands for CRUD operations on objects from CRM"
    },
    {
      "name": "Exec - Advanced commands",
      "description": "Exec are commands that perform more advanced operations."
    }
  ],
  "paths": {
    "/api/{className}/{objectID}": {
      "get": {
        "summary": "Reads data about an object with a given ID. It can also read multiple IDs.",
        "description": "Reads data about an object with a given ID. It can also read multiple IDs.",
        "tags": [
          "Simple -  Create / Read / Update / Delete"
        ],
        "operationId": "simpleRead",
        "parameters": [
          {
            "name": "className",
            "in": "path",
            "description": "API alias of a class enabled in this connector. Copy the exact alias from developer help.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "objectID",
            "in": "path",
            "description": "Positive object ID. GET may receive comma-separated IDs. PUT and DELETE accept one ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "This parameter limits the number of returned objects",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Correct response from API. The 'results' list contains data regarding\n read objects.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "code": 200,
                      "results": [
                        {
                          "job": 0,
                          "contractor": 0,
                          "who_downloaded": 0,
                          "id": 45,
                          "name": "File45.pdf",
                          "name_on_disk": "15137762313bba2a14e400d690f75cb3a6428b6a45",
                          "size": "1123",
                          "added_by": 14,
                          "description": "File description",
                          "status": "o",
                          "mime": "application/pdf; charset=binary",
                          "file_type": 2038,
                          "external_id": "",
                          "account_synchronized": 0,
                          "recently_downloaded": "0000-00-00 00:00:00",
                          "archiving_status": "",
                          "archiving_date": "0000-00-00 00:00:00",
                          "id_common_version": "5a3a64231bba0",
                          "last_modification_who": 14,
                          "added_who": 14,
                          "file_source": "1",
                          "how_many_downloads": "0.00",
                          "name_extension": "pdf",
                          "last_modification_date": "2017-12-20 13:23:51",
                          "added_date": "2017-12-20 13:23:51",
                          "icon_type": "4",
                          "cloud_file_address": ""
                        },
                        {
                          "job": 0,
                          "contractor": 0,
                          "who_downloaded": 0,
                          "id": 34,
                          "name": "instruction.pdf",
                          "name_on_disk": "144136427401dasdaf2f124e2b06f69c843c1f5",
                          "size": "8328596",
                          "added_by": 14,
                          "description": "",
                          "status": "y",
                          "mime": "application/pdf; charset=binary",
                          "file_type": 2038,
                          "external_id": "",
                          "account_synchronized": 0,
                          "recently_downloaded": "0000-00-00 00:00:00",
                          "archiving_status": "",
                          "archiving_date": "0000-00-00 00:00:00",
                          "id_common_version": "55e6f24e340c5",
                          "last_modification_who": 14,
                          "added_who": 14,
                          "file_source": "1",
                          "how_many_downloads": "0.00",
                          "name_extension": "pdf",
                          "last_modification_date": "2015-09-04 10:57:54",
                          "added_date": "2015-09-04 10:57:54",
                          "icon_type": "4",
                          "cloud_file_address": ""
                        }
                      ],
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not Found"
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "API command that updates data about object in CRM",
        "description": "This command is responsible for updating data about object in CRM. One request can be used to change multiple fields. This command requires appropriate permissions set in the connector settings. \nIn the request body, we provide pair values - field:value.",
        "tags": [
          "Simple -  Create / Read / Update / Delete"
        ],
        "operationId": "update",
        "parameters": [
          {
            "name": "className",
            "in": "path",
            "description": "API alias of a class enabled in this connector. Copy the exact alias from developer help.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "objectID",
            "in": "path",
            "description": "Positive object ID. GET may receive comma-separated IDs. PUT and DELETE accept one ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fieldToChange": {
                    "type": "string",
                    "example": "valueToSet"
                  },
                  "name": {
                    "type": "string",
                    "example": "filenameABC.jpg"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - data has been updated",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "code": 200,
                      "results": 1,
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found!"
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "API command that deletes object from CRM.",
        "description": "This command is responsible for deleting object of provided class. Request body should be empty - there is no need for additional data.",
        "tags": [
          "Simple -  Create / Read / Update / Delete"
        ],
        "operationId": "delete",
        "parameters": [
          {
            "name": "className",
            "in": "path",
            "description": "API alias of a class enabled in this connector. Copy the exact alias from developer help.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "objectID",
            "in": "path",
            "description": "Positive object ID. GET may receive comma-separated IDs. PUT and DELETE accept one ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success - data has been deleted",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "code": 200,
                      "results": 1,
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found!"
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/{className}/": {
      "post": {
        "summary": "Creates a new object of provided class.",
        "description": "Creates a new object of provided class. Values for object's fields are specified in request body. This command requires appropriate permissions set in the connector settings.",
        "tags": [
          "Simple -  Create / Read / Update / Delete"
        ],
        "operationId": "create",
        "parameters": [
          {
            "name": "className",
            "in": "path",
            "description": "API alias of a class enabled in this connector. Copy the exact alias from developer help.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fieldName1": {
                    "type": "string",
                    "example": "fieldValue1"
                  },
                  "fieldName2": {
                    "type": "string",
                    "example": "fieldValue2"
                  },
                  "fieldName3": {
                    "type": "string",
                    "example": "fieldValue3"
                  },
                  "fieldName4": {
                    "type": "string",
                    "example": "fieldValue4"
                  }
                },
                "description": "Object keyed by API field aliases. Create checks the class create allowlist; the field update allowlist applies only to PUT. Unknown field aliases are ignored and logged, so verify saved values.",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not Found"
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "201": {
            "description": "Created; results contains the new object ID.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "code": 201,
                      "results": 175,
                      "success": true
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Read objects of a class, optionally limiting the result count",
        "description": "Only class and field read allowlists apply. No cursor/offset pagination is provided by this endpoint. Avoid unbounded reads.",
        "tags": [
          "Simple -  Create / Read / Update / Delete"
        ],
        "operationId": "listObjects",
        "parameters": [
          {
            "name": "className",
            "in": "path",
            "description": "API alias of a class enabled in this connector. Copy the exact alias from developer help.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "This parameter limits the number of returned objects",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Correct response from API. The 'results' list contains data regarding\n read objects.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "code": 200,
                      "results": [
                        {
                          "job": 0,
                          "contractor": 0,
                          "who_downloaded": 0,
                          "id": 45,
                          "name": "File45.pdf",
                          "name_on_disk": "15137762313bba2a14e400d690f75cb3a6428b6a45",
                          "size": "1123",
                          "added_by": 14,
                          "description": "File description",
                          "status": "o",
                          "mime": "application/pdf; charset=binary",
                          "file_type": 2038,
                          "external_id": "",
                          "account_synchronized": 0,
                          "recently_downloaded": "0000-00-00 00:00:00",
                          "archiving_status": "",
                          "archiving_date": "0000-00-00 00:00:00",
                          "id_common_version": "5a3a64231bba0",
                          "last_modification_who": 14,
                          "added_who": 14,
                          "file_source": "1",
                          "how_many_downloads": "0.00",
                          "name_extension": "pdf",
                          "last_modification_date": "2017-12-20 13:23:51",
                          "added_date": "2017-12-20 13:23:51",
                          "icon_type": "4",
                          "cloud_file_address": ""
                        },
                        {
                          "job": 0,
                          "contractor": 0,
                          "who_downloaded": 0,
                          "id": 34,
                          "name": "instruction.pdf",
                          "name_on_disk": "144136427401dasdaf2f124e2b06f69c843c1f5",
                          "size": "8328596",
                          "added_by": 14,
                          "description": "",
                          "status": "y",
                          "mime": "application/pdf; charset=binary",
                          "file_type": 2038,
                          "external_id": "",
                          "account_synchronized": 0,
                          "recently_downloaded": "0000-00-00 00:00:00",
                          "archiving_status": "",
                          "archiving_date": "0000-00-00 00:00:00",
                          "id_common_version": "55e6f24e340c5",
                          "last_modification_who": 14,
                          "added_who": 14,
                          "file_source": "1",
                          "how_many_downloads": "0.00",
                          "name_extension": "pdf",
                          "last_modification_date": "2015-09-04 10:57:54",
                          "added_date": "2015-09-04 10:57:54",
                          "icon_type": "4",
                          "cloud_file_address": ""
                        }
                      ],
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not Found"
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/exec/notification": {
      "post": {
        "summary": "API command that creates a bell notification in CRM bs4 CORE.",
        "description": "Notifications are available in CRM under the bell icon. Various messages are sent there to inform the user about certain processes and results of activities. This command creates such a notification.\nParameters classId and objectId are optional - when supplied, the notification will contain link to related object",
        "tags": [
          "Exec - Advanced commands"
        ],
        "operationId": "notification",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "msgs": {
                    "type": "array",
                    "description": "List of notification to send. Each notification contain error code and optional params. Some of the errors have placeholder where text from 'params' will be inserted",
                    "items": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer",
                          "description": "ID of the Error",
                          "example": 500001
                        },
                        "params": {
                          "type": "array",
                          "description": "List of strings that are used for placeholders.",
                          "items": {
                            "type": "string",
                            "description": "Optional text values for placeholders",
                            "example": "example@gmail.com"
                          }
                        }
                      }
                    }
                  },
                  "idUser": {
                    "type": "integer",
                    "description": "ID of CRM user to which a notification should be sent",
                    "example": 14
                  },
                  "classId": {
                    "type": "integer",
                    "description": "ID of class related to that notification. (Optional)",
                    "example": 123
                  },
                  "objectId": {
                    "type": "integer",
                    "description": "ID of object related to that notification. (Optional)",
                    "example": 432
                  }
                },
                "required": [
                  "msgs",
                  "idUser"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - notification has been sent.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "results": "OK",
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/exec/downloadfile": {
      "post": {
        "summary": "API command that downloads file from CRM repository",
        "description": "This command is responsible for downloading the file from the CRM repository. The file content is downloaded in Base64 format, so the requester must decode the content themselves and save it as a file. The API response also includes the filename, making it easier to create the file. ",
        "tags": [
          "Exec - Advanced commands"
        ],
        "operationId": "download",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fileIdCRC": {
                    "type": "string",
                    "example": "1232-25dgd62846fj3764yhnf736trpold34",
                    "description": "ID + Checksum of the file. If the API detects any problems with the checksum, an error will be returned."
                  }
                },
                "required": [
                  "fileIdCRC"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - file has been downloaded.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "results": {
                        "content": "< CONTENT OF A FILE AS BASE64 >",
                        "filename": "filename.extension"
                      },
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "File not found!"
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/exec/uploadfile": {
      "post": {
        "summary": "API command that uploads file to CRM repository",
        "description": "Upload one file in the FileContent multipart field; results contains its ID with checksum. Actual upload size and storage restrictions also depend on PHP, the web server and BS4 configuration.",
        "tags": [
          "Exec - Advanced commands"
        ],
        "operationId": "upload",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "FileContent": {
                    "type": "string",
                    "format": "binary",
                    "description": "File to upload"
                  }
                },
                "required": [
                  "FileContent"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - file has been uploaded.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "results": "< fileIdCRC of added file >",
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/exec/runtrigger": {
      "post": {
        "summary": "API command that executes trigger from CRM",
        "description": "Execute an explicitly allowed trigger. objectId is optional (0 means no related object); a positive ID must exist in the trigger related class. param1–param3 are scalar inputs converted to strings; null is treated as omitted. For queued modes result=1 acknowledges scheduling, not completion. Calls are not idempotent: do not automatically repeat after a timeout.",
        "tags": [
          "Exec - Advanced commands"
        ],
        "operationId": "trigger",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "triggerId"
                ],
                "properties": {
                  "triggerId": {
                    "type": "integer",
                    "minimum": 1,
                    "example": 5000100
                  },
                  "objectId": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Optional related object ID; omit or use 0 for no context.",
                    "example": 123
                  },
                  "param1": {
                    "nullable": true,
                    "description": "Additional parameter 1; converted to a string.",
                    "example": "Jan",
                    "anyOf": [
                      {
                        "type": "string",
                        "nullable": true
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "param2": {
                    "nullable": true,
                    "description": "Additional parameter 2; converted to a string.",
                    "example": "Kowalski",
                    "anyOf": [
                      {
                        "type": "string",
                        "nullable": true
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "param3": {
                    "nullable": true,
                    "description": "Additional parameter 3; converted to a string.",
                    "example": "0",
                    "anyOf": [
                      {
                        "type": "string",
                        "nullable": true
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request handled; inspect results.result and results.execution.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "results"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "description": "Boolean trigger results are 1/0; other native results are retained."
                        },
                        "execution": {
                          "type": "string",
                          "enum": [
                            "immediate",
                            "queued"
                          ]
                        },
                        "queueTaskId": {
                          "type": "integer",
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "Immediate": {
                    "value": {
                      "results": {
                        "result": 1,
                        "execution": "immediate",
                        "queueTaskId": null
                      },
                      "success": true
                    }
                  },
                  "Queued": {
                    "value": {
                      "results": {
                        "result": 1,
                        "execution": "queued",
                        "queueTaskId": 123
                      },
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Allowed trigger or related object does not exist."
          },
          "503": {
            "description": "Triggers are unavailable during maintenance."
          }
        }
      }
    },
    "/api/exec/report": {
      "post": {
        "summary": "API command that creates report from selected CRM page",
        "description": "Run a report page allowed in the connector and return its row IDs in results.ids. reportId is the page ID; criteria is an object of filter values, not a list of filter IDs. Copy the actual filter keys and types from the deployment.",
        "tags": [
          "Exec - Advanced commands"
        ],
        "operationId": "report",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reportId": {
                    "type": "integer",
                    "example": 5000012,
                    "description": "ID of the CRM page"
                  },
                  "criteria": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Filter key/value pairs accepted by the report page."
                  }
                },
                "required": [
                  "reportId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - Returns IDs.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "results": {
                        "ids": [
                          2000,
                          2001,
                          2002,
                          2003,
                          2004,
                          2005,
                          2005
                        ]
                      },
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/exec/read": {
      "post": {
        "summary": "API command that reads objects from based on filters.",
        "description": "Read up to 5000 matching objects. className is the class API alias, criteriaFields maps API field aliases to values. Returned fields are limited by the connector read allowlist. No cursor is returned.",
        "tags": [
          "Exec - Advanced commands"
        ],
        "operationId": "read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "className": {
                    "type": "string",
                    "example": "files",
                    "description": "Name of the CRM class"
                  },
                  "criteriaFields": {
                    "type": "object",
                    "description": "Pairs of criteria for searching. Only objects meeting the criteria will be returned.",
                    "properties": {
                      "id": {
                        "type": "string",
                        "example": 5
                      },
                      "fieldName": {
                        "type": "string",
                        "example": "fieldValue"
                      }
                    }
                  }
                },
                "required": [
                  "className"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results contains objects, not only their IDs.",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "results": [
                        {
                          "id": 5,
                          "comment": "",
                          "product_categories": "0",
                          "full_name": "",
                          "tax_identification_number": "",
                          "promote_on_www": "0",
                          "payment_method": "9",
                          "source_of_customer_acquisition": "0",
                          "importance_of_the_company": "1",
                          "phase": "6",
                          "discounts": "0",
                          "form_of_activity": "1",
                          "contractor_symbol": "SE4VA",
                          "link_to_the_catalogue": "",
                          "documents": "",
                          "number_of_employees": "0",
                          "turnover_2005": "0",
                          "end_of_subscription": "2021-02-04 00:00:00",
                          "crm_tree": "",
                          "nextField": "nextValue"
                        }
                      ],
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/exec/response": {
      "post": {
        "summary": "API command that sends response to action activated by trigger.",
        "description": "Specialized response to an outbound request. The supplied Bearer token is also used as the outbound correlation hash by the current implementation. Use only in a deployed workflow that explicitly supports this convention; an ordinary connector token alone does not prove that a matching outbound record exists. result=1 is not an affected-row count.",
        "tags": [
          "Exec - Advanced commands"
        ],
        "operationId": "response",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "response": {
                    "type": "string",
                    "example": "New ID: 3",
                    "description": "Content of the response"
                  }
                },
                "required": [
                  "response"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - Response has been sent. result 1 - success, 0 - error",
            "content": {
              "application/json": {
                "examples": {
                  "Default": {
                    "value": {
                      "results": {
                        "result": "1"
                      },
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token or inactive connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Operation not allowed in this connector",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal error; inspect connector history before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "summary": "Check API reachability and version without a token",
        "description": "Does not verify connector activity, token, permissions or license availability. Returns an unwrapped object.",
        "security": [],
        "responses": {
          "200": {
            "description": "API responds",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "api",
                    "version"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "api": {
                      "type": "boolean"
                    },
                    "version": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "status": "ok",
                  "api": true,
                  "version": "1.02"
                }
              }
            }
          },
          "405": {
            "description": "Use GET /api/health."
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://twoj-bs4.example.invalid",
      "description": "Replace with the base URL of your BS4 installation; retain any subfolder."
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token generated in an active bs4-API connector. Never use an MCP token."
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "required": [
          "success",
          "errors"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "errors": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}