openapi.json

{
  "swagger": "2.0",
  "schemes": [
    "https"
  ],
  "host": "aiaas.pandorabots.com",
  "basePath": "/",
  "info": {
    "description": "AIaaS provides API access to our bot hosting platform and SDKs, allowing developers to easily integrate conversational interfaces into applications.",
    "title": "Pandorabots AIaaS",
    "version": "1.0.0",
    "x-apisguru-categories": [
      "machine_learning"
    ],
    "x-origin": [
      {
        "converter": {
          "url": "https://github.com/lucybot/api-spec-converter",
          "version": "2.7.11"
        },
        "format": "swagger",
        "url": "https://developer.pandorabots.com/swagger/spec.json",
        "version": "1.2"
      }
    ],
    "x-preferred": true,
    "x-providerName": "pandorabots.com",
    "x-datafire": {
      "name": "pandorabots",
      "type": "openapi"
    }
  },
  "securityDefinitions": {
    "user_key": {
      "description": "Your application's user key.",
      "in": "query",
      "name": "user_key",
      "type": "apiKey"
    }
  },
  "security": [
    {
      "user_key": []
    }
  ],
  "tags": [
    {
      "description": "New API added \"Anonymous Talk\"",
      "name": "pandorabots_api_swagger_1_3"
    }
  ],
  "paths": {
    "/atalk/{app_id}/{botname}": {
      "post": {
        "description": "Start a conversation with the bot using the Anonymous Talk API. This method will allow you to request creation of an end-user client_name that can maintain persistent predicates per end-user talking to your bot. If client_name is NOT sent in the request, then Pandorabots will create a end-user client_name and return it in the response. Similar to the Talk to Bot API, Pandorabots will also return a new session ID if not included in the call. Use the session ID returned to group interactions together. <p>In addition to bot response and session ID, the HTTP response will include a new end-user client_name in the following format:<br>aiaas-XXX-user-nnnn, where XXX is your app_ID and nnnn is numeric starting with 0000 and incrementing after each request.<br/> </p><p>Malformed requests such as exceeding size of input or unknown end-user client_name returns 400 error code. Error code 412 is returned if the bot is not compiled or does not exist. Error code 429 is returned if your application has reached maximum plan API call limit.</p><p><pre class='prettyprint'>curl -v  -X POST 'https://aiaas.pandorabots.com/atalk/APP_ID/BOTNAME?user_key=USER_KEY&input=INPUT'</pre></p>",
        "operationId": "atalkBot",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "The name of the bot. Format required is 3-64 characters in length and only numbers or lower-case letters [0-9][a-z]",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Message to be sent to the bot. This can contain multiple sentences. Currently the limit is 500 characters.",
            "in": "query",
            "name": "input",
            "required": true,
            "type": "string"
          },
          {
            "description": "Leave blank to request Pandorabots to create a client_name which will support persistent predicates. Including a valid client_name in this parameter will work in the same way that Talk to Bot API but with persistent predicates. It is recommended to use this API only to create an end-user client_name, and then use normal Talk to Bot API to continue conversation with the bot.",
            "in": "query",
            "name": "client_name",
            "required": false,
            "type": "string"
          },
          {
            "description": "Session ID generated by Pandorabots. This allows the application to group individual conversations into a collection as needed. If not included in the call, Pandorabots will issue a new session ID. (4-byte integer type)",
            "in": "query",
            "name": "sessionid",
            "required": false,
            "type": "string"
          },
          {
            "description": "If true, the system will not signal an error if the bot is uncompiled, and will instead look for a previous version of the bot that is available.",
            "in": "query",
            "name": "recent",
            "required": false,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Anonymous Talk",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      }
    },
    "/bot/{app_id}": {
      "get": {
        "description": "Retrieve a list of your application's bots. Response returns JSON object with info for each bot.<p>Returns a 401 error code for invalid app_ID or user_key, or if applicable, invalid referrer.</p><p><pre class='prettyprint'>curl -v  -X GET 'https://aiaas.pandorabots.com/bot/APP_ID?user_key=USER_KEY'</pre></p>",
        "operationId": "listBots",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "List of bots",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      }
    },
    "/bot/{app_id}/{botname}": {
      "delete": {
        "description": "Delete a bot on the Pandorabots server.<p>Deleting a bot that does not exist returns a 412 error. Invalid botname will return a 400 error. Invalid app_id, user_key, or referrer filter will return a 401 error.</p><p><pre class='prettyprint'>curl -v  -X DELETE 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME?user_key=USER_KEY'</pre></p>",
        "operationId": "deleteBot",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Name of the bot to delete.",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Delete a bot",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      },
      "get": {
        "description": "Retrieve a list of a bot's files. Returns a JSON object with each bot file associated with bot specified.<p>Returns a 404 error code for bot not found. Returns a 401 error code for invalid app_ID, user_key, or referrer filter.</p><p>The <code color=blue>return=zip</code> option may not behave as expected using Active Docs 1.2</p><p><pre class='prettyprint'>curl -v  -X GET 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME?user_key=USER_KEY'</pre></p>",
        "operationId": "listBotFiles",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "The name of the bot.",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "If set to zip, a zip file with all bot files will be returned.",
            "in": "query",
            "name": "return",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "List of bot files",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      },
      "put": {
        "description": "Create a new instance of a bot on the Pandorabots server.<p>If there is already a bot under the same app_id and botname, a 409 error is returned. Invalid botname will return a 400 error.</p><p>Creating more bots than your plan allows or using an invalid app_id or user_key (or if applicable referrer filter) returns a 401 error.</p><p><pre class='prettyprint'>curl -v  -X PUT 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME?user_key=USER_KEY'</pre></p>",
        "operationId": "createBot",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Must be unique from all the other bots you have created under this app_id. Can only be numbers and lowercase letters, and must be between 3 and 64 characters long.",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Create a bot",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      }
    },
    "/bot/{app_id}/{botname}/verify": {
      "get": {
        "description": "A bot personality is created by uploading AIML and other file types to Pandorabots. The files must compile correctly in order for the bot to run. By issuing a call to this API, Pandorabots will compile the bot, updating any changes that have been made to the files.<p>Compiling the bot makes its most recent version available for talk. A 400 error means that we were unable to compile your bot (you should check your files for syntax issues) or the botname was not found. </p><p>You can see any thrown errors in the results field of the returned JSON object:</p><p><pre class='prettyprint'>curl -v  -X GET 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/verify?user_key=USER_KEY'</pre></p>",
        "operationId": "compileBot",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Your bot's name",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Compile a bot",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      }
    },
    "/bot/{app_id}/{botname}/{file-kind}": {
      "delete": {
        "description": "Delete pdefaults or properties bot file.<p>For malformed file-kind, a 404 error is returned. For invalid botname, a 412 error is returned.</p><pre><p>curl -v -X DELETE 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND?user_key=USER_KEY'</p></pre>",
        "operationId": "deleteBotFile2",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Name of the bot.",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Specify the type of file being deleted: pdefaults, properties",
            "in": "path",
            "name": "file-kind",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Delete a bot file (pdefaults, properties)",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      },
      "get": {
        "description": "Retrieve pdefaults or properties bot file.<p>For malformed file-kind, a 404 error is returned. For invalid botname, a 400 error is returned. For unknown bot or file, a 412 error is returned.</p><pre><p>curl -v -X GET 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND?user_key=USER_KEY'</p></pre>",
        "operationId": "getBotFile2",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Name of the bot.",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Specify the type of file being retrieved: pdefaults, properties",
            "in": "path",
            "name": "file-kind",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Retrieve a bot file (pdefaults, properties)",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      },
      "put": {
        "consumes": [
          "application/xml"
        ],
        "description": "Upload bot personality files to your bot. Files must be named with only lowercase letters and numbers with one of the following extensions: <p><b>Properties: </b>Extension - .properties, file-kind - properties, No filename required in path</p><p><b>Predicate defaults: </b>Extension - .pdefaults, file-kind - pdefaults, No filename required in path</p><p>The system will overwrite existing files with the file being uploaded.</p><p>For malformed JSON in non-AIML files, a 400 error is returned. For malformed file-kind, a 404 error is returned. For invalid file or botname, a 412 error is returned. </p><p>If Active Doc spec is not working with this API, please use the following curl command examples:</p><pre class='prettyprint'><p>curl -v -X PUT 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/properties?user_key=USER_KEY'<br/>&nbsp;&nbsp;--data-binary @/home/foo/foobot.properties</p></pre>",
        "operationId": "uploadFile2",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Your bot's name",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Specify the type of file being uploaded: pdefaults, properties",
            "in": "path",
            "name": "file-kind",
            "required": true,
            "type": "string"
          },
          {
            "description": "Type or Paste in file contents.",
            "in": "body",
            "name": "content",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Upload a bot file (pdefaults, properties)",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      }
    },
    "/bot/{app_id}/{botname}/{file-kind}/{filename}": {
      "delete": {
        "description": "Delete an AIML, set, map or substitution bot file<p>For malformed file-kind, a 404 error is returned. For invalid file or botname, a 412 error is returned.</p><pre><p>curl -v -X DELETE 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND/FILENAME?user_key=USER_KEY'</p></pre>",
        "operationId": "deleteBotFile1",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Name of the bot.",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Specify the type of file being deleted: file (for AIML files), map, substitution, set",
            "in": "path",
            "name": "file-kind",
            "required": true,
            "type": "string"
          },
          {
            "description": "Filename to delete. Note: for non-AIML files, do not include the file extension in the path.",
            "in": "path",
            "name": "filename",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Delete a bot file (AIML, set, map, substitution)",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      },
      "get": {
        "description": "Retrieve an AIML, set, map or substitution bot file.<p>For malformed file-kind, a 404 error is returned. For invalid filename or botname, a 400 error is returned. For unknown bot or file, a 412 error is returned.</p><pre><p>curl -v -X GET 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND/FILENAME?user_key=USER_KEY'</p></pre>",
        "operationId": "getBotFile1",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Name of the bot.",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Specify the type of file being retrieved: file (for AIML files), map, substitution, set",
            "in": "path",
            "name": "file-kind",
            "required": true,
            "type": "string"
          },
          {
            "description": "Filename to retrieve. Note: for non-AIML files, do not include the file extension in the path.",
            "in": "path",
            "name": "filename",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Retrieve a bot file (AIML, set, map, substitution)",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      },
      "put": {
        "consumes": [
          "application/xml"
        ],
        "description": "Upload bot personality files to your bot. Files must be named with only lowercase letters and numbers with one of the following extensions: <p><b>AIML: </b>Extention - .aiml, file-kind - file</p><p><b>Sets: </b>Extension - .set, file-kind - set</p><p><b>Maps: </b>Extension - .map, file-kind - map</p><p><b>Substitutions: </b>Extension - .substitution, file-kind - substitution</p><p>The system will overwrite existing files with the file being uploaded.</p><p>If the request is malformed because the file name is invalid or malformed JSON for non-AIML files, a 400 error is returned. For malformed file-kind, a 404 error is returned. For invalid file or botname, a 412 error is returned. </p><p>If Active Doc spec is not working with this API, please use the following curl command examples:</p><pre class='prettyprint'><p>curl -v -X PUT 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/file/foobot.aiml?user_key=USER_KEY'<br/>&nbsp;&nbsp;--data-binary @/home/foo/foobot.aiml</p></pre><br/><pre class='prettyprint'><p>curl -v -X PUT 'https://aiaas.pandorabots.com/bot/APP_ID/BOTNAME/set/colors?user_key=USER_KEY'<br/>&nbsp;&nbsp;--data-binary @/home/foo/colors.set</p></pre>",
        "operationId": "uploadFile1",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "Your bot's name",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Specify the type of file being uploaded: file (for AIML files), map, substitution, set",
            "in": "path",
            "name": "file-kind",
            "required": true,
            "type": "string"
          },
          {
            "description": "Filename to upload, must be named with only lowercase letters and numbers. Note: for non-AIML files, do not include the file extension in the path.",
            "in": "path",
            "name": "filename",
            "required": true,
            "type": "string"
          },
          {
            "description": "Type or Paste in file contents.",
            "in": "body",
            "name": "content",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Upload a bot file (AIML, set, substitution, map)",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      }
    },
    "/talk/{app_id}/{botname}": {
      "post": {
        "description": "Use these tools to test/debug/trace bot categories. <p>Malformed requests such as exceeding size of input or invalid clientname returns 400 error code. Error code 412 is returned if the bot is not compiled or does not exist.</p><p><pre class='prettyprint'>curl -v  -X POST 'https://aiaas.pandorabots.com/talk/APP_ID/BOTNAME?user_key=USER_KEY&input=INPUT'</pre></p>",
        "operationId": "debugBot",
        "parameters": [
          {
            "description": "Your Application ID",
            "in": "path",
            "name": "app_id",
            "required": true,
            "type": "string"
          },
          {
            "description": "The name of the bot. Format required is 3-64 characters in length and only numbers or lower-case letters [0-9][a-z]",
            "in": "path",
            "name": "botname",
            "required": true,
            "type": "string"
          },
          {
            "description": "Message to be sent to the bot. This can contain multiple sentences. Currently the limit is 500 characters.",
            "in": "query",
            "name": "input",
            "required": true,
            "type": "string"
          },
          {
            "description": "Identifies your application's end user. You can assign each of your end users a unique client_name. This will allow you to set predicates and other variable information that is specific to an individual. Format required is 3-64 characters in length and only numbers or lower-case letters [0-9][a-z]",
            "in": "query",
            "name": "client_name",
            "required": false,
            "type": "string"
          },
          {
            "description": "Session ID generated by Pandorabots. This allows the application to group individual conversations into a collection. While testing your bot, not including this parameter, Pandorabots will issue a new session ID. (4-byte integer type)",
            "in": "query",
            "name": "sessionid",
            "type": "string"
          },
          {
            "description": "For debugging purposes, you can specify a 'that' with the input that supersedes the existing that in bot memory.",
            "in": "query",
            "name": "that",
            "type": "string"
          },
          {
            "description": "For debugging purposes, you can specify a 'topic' with the input that supersedes the existing topic in bot memory.",
            "in": "query",
            "name": "topic",
            "type": "string"
          },
          {
            "description": "Return extra conversation information. If true, input, pattern, that, topic, filename, and template associated with the pattern matched are returned in addition to response and sessionid.",
            "in": "query",
            "name": "extra",
            "type": "string"
          },
          {
            "description": "Reset the bot memory. If true, all predicate values in the bot will be discarded, and the user can talk to the bot as if it is the first time",
            "in": "query",
            "name": "reset",
            "type": "string"
          },
          {
            "description": "Include trace data in the response. If true, the system will generate AIML trace information for the input. Trace data includes pattern matched, filename, input, template for all recursion levels. NOTE: for security reasons, trace does not work with client_name.",
            "in": "query",
            "name": "trace",
            "type": "string"
          },
          {
            "description": "If true, the system will force a reload of the bot into memory. This can be useful if you've recently uploaded an AIML file, recompiled your bot and want access to your bot's latest changes.",
            "in": "query",
            "name": "reload",
            "type": "string"
          },
          {
            "description": "If true, the system will not signal an error if the bot is uncompiled, and will instead look for a previous version of the bot that is available.",
            "in": "query",
            "name": "recent",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "No response was specified"
          }
        },
        "summary": "Debug a bot conversation",
        "tags": [
          "pandorabots_api_swagger_1_3"
        ]
      }
    }
  }
}