DevOps — QBox documentation
This HTTP API allows you to run QBox tests and get results from them programmatically. All URLs are relative to the base URL, which is: https://api.qbox.ai
All endpoints return responses in JSON format and, when applicable, accept a request body in JSON format.
This guide is an introduction to our API. For more comprehensive information, please check our Open API documentation.
Authentication
The API uses JWT token authentication. Unless otherwise specified all endpoints require authentication. An initial call must be made to get a token which can be used to authenticate subsequent requests.
To authenticate to the initial JWT token retrieval endpoint use the API username and API password found in the QBox user interface. To see this log in as an administrator account and navigate to Account and Settings -> DevOps. If you don’t see the DevOps tab on the Account and Settings page then please contact your QBox sales representative. Credentials are set at the company level.
The token retrieved from the token retrieval endpoint is used as a bearer token, i.e. requests should include an “Authorization” header with a value of “Bearer [token]”. If the token expires then call the token generation endpoint again to get a new one.
Endpoint
Authentication
Retrieve authentication token
URL: /authentication/authenticate
Type: POST
This endpoint allows you to retrieve a JWT token to be used for authenticating to the other endpoints. It does not itself require a JWT token but uses the API username and API password from the QBox interface instead. See “Authentication” above for instructions on how to retrieve these.
Body:
Response:
Retrieve current user
URL: /authentication/me
Type: GET
This endpoint returns the name of the company the current authentication token is for. This can be used for validating an authentication token in a safe way.
Response:
Tests
Run new test
URL: /test/run
Type: POST
This endpoint allows you to start a new QBox test running. It returns an identifier which you can use to poll the test progress endpoint (below) to retrieve details of the test progress and test results.
Note that some setup may need to be done in the QBox front end for you to run certain types of test. If you are able to run a test in the QBox front end then you should be able to run it through the API.
File types
QBox will perform an HTTP GET request to the URLs you provide for the model file and cross-validation file. The body of the response to this request should be the content of the file with no extraneous content.
The file types are the same as those accepted by the QBox web interface. The model file can be one of the following:
- JSON file exported by IBM Watson Assistant or Microsoft LUIS
- ZIP file exported by Google Dialogflow, Wit.ai or Amazon Lex
- Markdown file (.md) generated by Rasa
- TSV file generated by QnA maker
- CSV file with the same format as the cross-validation file (see below)
The cross-validation file may be a CSV file or a markdown file.
If it is a CSV file it should have the following format:
- First row should be a header row with values of “Question” and “Intent” (not necessarily in that order)
- Each row should contain a single question/intent pair
- Values can be enclosed in quotation marks and this should be done if a question or intent contains a comma
If it is a markdown file (.md) it should follow the Rasa format specification. Anything data in the file other than intents and their training samples will be ignored.
Response:
Note that if your request fails validation then an HTTP 400 (Bad Request) response will be returned with the details of the problem. Correct requests return HTTP 200 (OK).
Get test details
Url: /test/get?identifier=[identifier]
Type: GET
Retrieves details of a test which was previously run through the API. If the test has finished then the results will be included as well.
The “identifier” querystring parameter should be set to the value of the “identifier” field in the response to the call to the “Run new test” endpoint.
