RESTful APIs

There are a number of API methods available to interact with Trakr. We are continuing to develop the API to make it as flexible as possible to fit all needs.

Access the API

In order to access the API, you will need to generate an API key which you can find on your user account page. API endpoints are available through various request methods below.

API endpoints

When you access each of the API methods, please make sure you include your API key (x-api-key) in the request header in order to authenticate yourself. The response for the API will be a JSON message that looks like:

{"status": "status_message", "result": "message or result set"}

There is only two status message:

  • success
  • error

If the API returns data, it will be encapsulated in the “result” element.

Retrieve the status of a screenshot collection or comparison

This API call will provide the status of a screenshot collection or comparison and let the caller know if the task is complete (or in progress) and in case of the comparison, the amount of difference found.

Endpoint: /api/v1/status/[id]

Request method: GET

Method arguments:

  • id (required) – the numeric id of the screenshot collection or comparison

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request GET https://app.trakr.tech/api/v1/status/1234


Get all comparisons for a project

This API call will retrieve all of the comparisons for a project and some high-level information

Endpoint: /api/v1/project/[id]/get_comparisons

Request method: GET/POST

Method arguments:

  • id (required) – the numeric id of the project.

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request GET https://app.trakr.tech/api/v1/project/41/get_comparisons

Example result {"status":"success","result":[{"id":112,"score":100,"progress":{"done":"1","total":"1"}},{"id":114,"score":100,"progress":{"done":"1","total":"1"}},{"id":117,"score":100,"progress":{"done":"1","total":"1"}}]}

The result set is a nested JSON with the following attributes:

  • id – the comparison id
  • score – relative score (based on 100) of items changed in that comparison, for example, if there are 10 items and 8 had changes detected, the score will be 80.
  • progress – the number of items in the comparison and the overall status

Return a list of objects in a project by a query

This call returns a list of objects (comparison and screenshots) that belong to a particular project.

Endpoint: /api/v1/project/[id]/query

Request method: POST

Method arguments:

  • id (required) – the numeric id of the project.
  • type – either screenshot or comparison (omit this to return both types of objects)
  • title – full or partial title of the screenshot or comparison (omit this to return all objects)

Example: curl --header 'x-api-key: 790805643641389d125d0ce014b72b20' --request POST https://localhost:8888/trakr/api/v1/project/310/query --data '{"title":"PR 11"}'

Example result {"status":"success","result":{"398":"screenshot","399":"screenshot","400":"comparison}}

The result is a set of JSON key/value pair with the key being the object type (screenshot/comparison) and the value equals to the object id.


Delete an object in Trakr

This API call will delete an object in Trakr

Endpoint: /api/v1/delete/[object_type]/[id]

Request method: GET

Method arguments:

  • object_type (required) – The type of object. the value can be: screenshot, comparison, project
  • id (required) – the numeric id of the object.

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request GET https://app.trakr.tech/api/v1/delete/screenshot/123


Create a new screenshot collection

This API call will create a screenshot collection in an existing project on the platform. The API caller user must be the owner of the project or have access to create screenshot collection in the project.

Endpoint: /api/v1/project/[id]/screenshot

Request method: POST

Method arguments:

  • id (required) – the numeric id of the project.
  • environment (optional) – the project (website) environment, accepted values are: production|staging|development. If this is not passed int it will default to the production environment. This argument is passed in as part of the POST data.
  • title (optional) – Specify the screenshot collection title.
  • username (optional) – Enter the username associated with this website environment if applicable. (Learn more)
  • password (optional) – Enter the password associated with this website environment if applicable. (Learn more)

Special note

If you have configured the project environment with user login, then the username and password arguments become required in the API call.

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/screenshot --data '{"environment":"production", "title": "post update (July 30)"}'


Compare with the last screenshot collection (In the same environment)

This API call will create a new screenshot collection (in the specified environment) and then compare with the last screenshot collection created in the project. If there is no previous screenshot collection in the project, it will simply create a new screenshot collection.

Endpoint: /api/v1/project/[id]/compare_self

Request method: POST

Method arguments:

  • id (required) – the numeric id of the project.
  • environment (optional) – the project (website) environment, accepted values are: production|staging|development. If this is not passed int it will default to the production environment. This argument is passed in as part of the POST data.
  • username (optional) – Enter the username associated with this website environment if applicable. (Learn more)
  • password (optional) – Enter the password associated with this website environment if applicable. (Learn more)

Special note

If you have configured the project environment with user login, then the username and password arguments become required in the API call.

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/compare_self --data '{"environment":"development"}'


Compare between 2 pre-defined environments (For example, production vs. staging)

This API call will compare the latest screenshot collections in the given environments. If there is no screenshot collection available, it will create them first.

Endpoint: /api/v1/project/[id]/compare_environments

Request method: POST

Method arguments:

  • id (required) – the numeric id of the project.
  • environment1 (required) – the project (website) environment, accepted values are: production|staging|development.This argument is passed in as part of the POST data.
  • environment2 (required) – the project (website) environment, accepted values are: production|staging|development.This argument is passed in as part of the POST data.
  • username1 (optional) – Enter the username associated with this project environment1 if applicable. (Learn more)
  • password1 (optional) – Enter the password associated with this project environment1 if applicable. (Learn more)
  • username2 (optional) – Enter the username associated with this website environment2 if applicable. (Learn more)
  • password2 (optional) – Enter the password associated with this website environment2 if applicable. (Learn more)

Special note

If you have configured the one of the project environment with user login, then the username(1 or 2) and password(1 or 2) arguments become required in the API call.

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/compare_environments --data '{"environment1":"production", "environment2":"staging"}'


Compare between a pre-defined screenshot collection and a build environment

This API call is designed to create a comparison test between a screenshot collection in a predefined environment such as production or staging against a (continuous integration) build environment.

Endpoint: /api/v1/project/[id]/compare_build

Request method: POST

Method arguments:

  • id (required) – the numeric id of the project.
  • build_url (required) – The base URL for the build (from CI)
  • environment – One of the pre-defined environment (production/staging/development)
  • collection_id – The id of an existing screenshot collection used as the baseline (before) screenshot in the comparison test
  • comparison_name (optional) – The name (title) of the comparison test generated
  • title (optional) – The name (title) of the screenshot collection if we did not specify a collection_id in this call

Note: You must supply either a (pre-defined) environment or collection_id to be used as the baseline (before) screenshot. If you supply an environment, the API will either use the last available screenshot collection in that environment or create a new screenshot collection in that environment to compare with the build environment.

Example1: Create a comparison test between the production environment and a build environment.

curl --header 'x-api-key: c1702607d373687432a34e7db2ff4c39' --request POST https://app.trakr.tech/api/v1/project/310/compare_build --data '{"environment":"production", "build_url": "http://build123.example.com"}'

Example2:  Create a comparison test between an existing screenshot collection and a build environment.

curl --header 'x-api-key: c1702607d373687432a34e7db2ff4c39' --request POST https://app.trakr.tech/api/v1/project/310/compare_build --data '{"collection_id":"321", "build_url": "http://build123.example.com", "comparison_name": "foo vs. bar"}'


Perform a quick comparison

This API call will quickly perform comparisons for 2 URLs. This method is useful when you are trying to compare different “build” in continuous integration, continuous deployment environment. Please note that your custom environment SHOULD contain the same path/URIs as your other environments set up on the project.

Endpoint: /api/v1/project/[id]/compare_custom

Request method: POST

Method arguments:

  • id (required) – the numeric id of the project.
  • url1 (required) – A valid URL (base URL), for example (https://build154.example.com). This argument is passed in as part of the POST data.
  • url2 (required) – A valid URL (base URL), for example (https://build155.example.com). This argument is passed in as part of the POST data.
  • comparison_name (optional) – Name of the comparison. This argument is passed in as part of the POST data

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/41/compare_custom --data '{"url1": "https://build154.example.com", "url2": "https://build155.example.com"}'

Example result {"status":"success","result":{"message":"Task of comparing https:\/\/build154.example.com and https:\/\/build155.example.com has started","url":"https:\/\/app.trakr.tech\/comparisons\/c-mar-3-2018-golf-vs-c-mar-3-2018-victor","id":"127"}}

The result set is a JSON with the following attributes

  • id – the comparison id
  • url – URL to view the comparison

Create a new project

This call will create a new project on Trakr

Endpoint: /api/v1/project

Request method: POST

Method arguments: Arguments for this method needs to be passed in a nested JSON, which will be denoted with sub-list below:

  • production
    • url (required) – The base URL for the project (in its production/live environment), e.g. http://www.example.com (no trailing slash)
    • username – If the URL has basic authentication (.htpasswd), the associated username
    • password – If the URL has basic authentication (.htpasswd), the associated password
  • uris (required) – a nested list of URIs (e.g. /contact), you must supply at least one URI
    • [uri1]
    • [uri2]
    • [uri3]
  • title – Title of the project (if not given, the URL of the production environment will be used)
  • staging
    • url – The base URL for the staging environment
    • username – If the URL has basic authentication (.htpasswd), the associated username
    • password – If the URL has basic authentication (.htpasswd), the associated password
  • development
    • url – The base URL for the staging environment
    • username – If the URL has basic authentication (.htpasswd), the associated username
    • password – If the URL has basic authentication (.htpasswd), the associated password
  • schedule
    • interval – interval to take a screenshot collection in the project in days, for example, “1” will take a screenshot collection every day, max value is 14.
    • comparison – if the system should create a comparison after taking the screenshot collection (0 or 1)
  • notification
    • emails – a nested list of email addresses to receive notifications when new screenshot/comparisons are complete in the project
      • [email 1]
      • [email 2]
      • [email 3]

Example: curl --header 'x-api-key: cf160643934c3628fc736f7f6f124f35' --request POST https://app.trakr.tech/api/v1/project/ --data '{"production":{"url":"https:\/\/www.w3.org"},"staging":{"url":"https:\/\/staging.w3.org","username":"test","password":"123456"},"uris":["\/","\/standards","\/participate\/"],"title":"W3C website","schedule":{"interval":1,"comparison":1},"notification":{"emails":["john@email.com","jane@email.com"]}}'