API

This section explains the API of Columbo. Using the API you can retrieve information from Columbo and even create and edit Audits, Scenarios, Tests, etc. The API is a simple HTTP interface via GET, POST, PUT and DELETE.

The API can be accessed at https://api.columbo.io.

Authentication

Authentication to the Columbo API is done via BasicAuth. This requires both the email address and the API password from the Columbo user profile. The password used to log in to Columbo cannot be used. However, the API password will change whenever the regular password is changed.

cURL example

curl -u 'email:apiPassword' https://api.columbo.io/accounts

Examples

Retrieve Accounts

Returns all accounts the user has access to as JSON:

curl -u 'email:apiPassword' https://api.columbo.io/accounts

Create scenario

Creates a new (empty) scenario with the name "Test" in the account with the ID 5832c5ec9c01eeab6d20f460

curl \
  -u 'email:apiPassword' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name": "Test"}' \
  https://api.columbo.io/accounts/5832c5ec9c01eeab6d20f460/scenarios

The server response of this POST request is the newly created scenario (or the error messages if it could not be created). The following is an example, formatted for clarity:

{
    "__v": 0,
    "stepCount": 0,
    "name": "test",
    "createdBy": "52e015181203012451000002",
    "account": "5832c5ec9c01eeab6d20f460",
    "_id": "5848358030c13f8d79021a1b",
    }, "tags": [],
    }, "summary": [],
    "deviceType": "desktop",
    "cookies": [],
    "conditions": [],
    "steps": [],
    "updatedAt": "2016-12-07T16:14:56.974Z",
    "createdAt": "2016-12-07T16:14:56.974Z"
}

Edit Scenario

Changes to existing scenarios can be made by sending the attributes to be changed to the server via PUT, similar to the create request.

In the following example, a first step of type page is added to the new scenario to open a website:

curl \
  -u 'email:apiPassword' \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{"steps": [{"type": "page", "url": "http://columbo.io"}]}' \
  https://api.columbo.io/accounts/5832c5ec9c01eeab6d20f460/scenarios/5848358030c13f8d79021a1b

Please note that the cURL target URL is different from the POST call and the method (-X) is now PUT.

Again, the response returns the new Scenario object:

{
  "_id": "5848358030c13f8d79021a1b",
  "stepCount": 1,
  "name": "Test",
  "createdBy": "52e015181203012451000002",
  "account": "5832c5ec9c01eeab6d20f460",
  "__v": 1,
  "tags": [],
  "summary": [],
  "deviceType": "desktop",
  "cookies": [],
  "conditions": [],
  "steps": [{
    "createdAt": "2016-12-07T16:25:21.617Z",
    "updatedAt": "2016-12-07T16:25:21.617Z",
    "type": "page",
    "url": "http://columbo.io",
    "_id": "58483c1321a17f130bf8d815",
    "optional": false,
    "conditions": []
  }],
  "updatedAt": "2016-12-07T16:25:21.617Z",
  "createdAt": "2016-12-07T16:14:56.974Z"
}

Start a Schedule manually

This request will start the schedule with ID 61832c5ec9c01eeab6d20f414 in account 5832c5ec9c01eeab6d20f460 manually

curl \
  -u 'email:apiPassword' \
  -H 'Content-Type: application/json' \
  -X POST \
  https://api.columbo.io/accounts/5832c5ec9c01eeab6d20f460/schedules/61832c5ec9c01eeab6d20f414/runs