Projects API

Overview

Tenon's Projects API is a RESTful API that allows you to create and manage projects. This allows, among other things, the creation of projects from within other systems, including the launching of Spidering projects and managing Project URLs.

Common uses for the Projects API would be to set up distinct Project "buckets" for regularly occurring builds or integration with other products

Request Methods

The Projects API supports the following request methods, the use of which follow common REST patterns for CRUD access to Projects
  • GET - retrieves information about Projects
  • POST - adds a new project
  • PUT - edits an existing project
  • DELETE - deletes an existing project

The Projects API does not support HEAD requests.

GET

The GET request method is used to read data from the Projects API. Using this method you can retrieve the details for all, some, or one of your projects.

GET

https://tenon.io/api/projects?key=:apiKey

This request type gets all projects you have access to.

Sample Response
{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T17:26:08.506Z",
    "responseID": "53cc7e6cf762ee12fabbfc7b4985bcaa",
    "request": {
        "key": "[API_KEY_HERE]"
    },
    "projects": [
        {
            "id": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
            "type": "api",
            "name": "DEFAULT_PROJECT",
            "description": "DEFAULT_PROJECT",
            "defaultItem": true,
            "createdAt": "2017-09-11T12:04:44.000Z",
            "updatedAt": "2017-09-11T12:04:44.000Z",
            "apiDefaultCertainty": 0,
            "apiDefaultLevel": "AAA",
            "apiDefaultPriority": 0,
            "apiDefaultStore": false,
            "apiDefaultUAString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36",
            "apiDefaultViewportHeight": 768,
            "apiDefaultViewportWidth": 1024,
            "apiDefaultDelay": 0
        }
    ]
}
GET

https://tenon.io/api/projects/:projectID?key=:apiKey

This request type retrieves the details for a specific project identified by :projectID.

Sample Response
{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T17:27:51.865Z",
    "responseID": "4af884abf1cb827d3bee94eb90ecc047",
    "request": {
        "id": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "key": "[API_KEY_HERE]"
    },
    "project": {
        "id": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "type": "api",
        "name": "DEFAULT_PROJECT",
        "description": "DEFAULT_PROJECT",
        "defaultItem": true,
        "createdAt": "2017-09-11T12:04:44.000Z",
        "updatedAt": "2017-09-11T12:04:44.000Z",
        "apiDefaultCertainty": 0,
        "apiDefaultLevel": "AAA",
        "apiDefaultPriority": 0,
        "apiDefaultStore": false,
        "apiDefaultUAString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36",
        "apiDefaultViewportHeight": 768,
        "apiDefaultViewportWidth": 1024,
        "apiDefaultDelay": 0
    }
}

POST

This request type creates a new project.

POST

https://tenon.io/api/projects?key=:apiKey

Allowed Parameters

Key Type Description
type (required) String

The type parameter allows you to to define what sort of project this will be.

Valid values: must be one of spider or api.

An 'api' project is a traditional type of project where you control what is tested. You can add a pre-defined list of URLs or add URLs during the lifetime of the project.

A 'spider' project is one in which you plan on utilizing the spider to automatically crawl the website to find the URLs to be tested.

name (required) String The name parameter allows you to define a human-readable name for the project.
description (optional) String The description parameter allows for a text-based description of the project. Depending on the nature of the project, this might be useful for others on your team to understand what this project is all about.
defaultItem (optional) Boolean The defaultItem parameter indicates whether or not you wish this project to become the "default" project.
  • Valid values: must be one of true or false.
  • If left unset, the default value is false

Setting this parameter to true will mean that your existing default project will no longer be the default - this one will.

apiDefaultCertainty (optional) Number

The default certainty parameter to be used when running tests against URLs in this project, as described in Understanding request parameters.

If not set in the request, this item's value is inherited from your account's API settings.

Allowed values: 0, 20, 40, 60, 80, 100
apiDefaultLevel (optional) String

The default level parameter to be used when running tests against URLs in this project. As described in Understanding request parameters, this corresponds to the WCAG Level.

If not set in the request, this item's value is inherited from your account's API settings.

Allowed values: A, AA, AAA
apiDefaultPriority (optional) Number

The default priority parameter to be used when running tests against URLs in this project, as described in Understanding request parameters.

If not set in the request, this item's value is inherited from your account's API settings.

Allowed values: 0, 20, 40, 60, 80, 100
apiDefaultStore (optional) Boolean

The default store parameter to be used when running tests against URLs in this project, as described in Understanding request parameters.

Valid values: must be one of true or false.

If not set in the request, this item's value is inherited from your account's API settings.

apiDefaultUAString (optional) String

The default user_agent parameter to be used when running tests against URLs in this project, as described in Understanding request parameters.

If not set in the request, this item's value is inherited from your account's API settings.

apiDefaultViewportHeight (optional) Number

The default viewportWidth parameter to be used when running tests against URLs in this project, as described in Understanding request parameters.

If not set in the request, this item's value is inherited from your account's API settings.

apiDefaultViewportWidth (optional) Number

The default viewportHeight parameter to be used when running tests against URLs in this project, as described in Understanding request parameters.

If not set in the request, this item's value is inherited from your account's API settings.

apiDefaultDelay (optional) Number

The default delay parameter to be used when running tests against URLs in this project.

If not set in the request, this item's value is inherited from your account's API settings.

Sample Request body (API project type)
{
    "type": "api",
    "name": "API project",
    "description": "Testing the API projects flow",
    "apiDefaultLevel": "A",
    "apiDefaultPriority": 20
}
Sample Response (api type project)

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T00:32:14.200Z",
    "responseID": "5b6398ef5fc65d96dcd53bad62ef222f",
    "request": {
        "type": "api",
        "name": "API project",
        "description": "Testing the API projects flow",
        "apiDefaultLevel": "A",
        "apiDefaultPriority": 20,
    },
    "project": {
        "id": "f12bde27-0f61-4ba2-9adf-b56440d8ddbf",
        "type": "api",
        "name": "API project",
        "description": "Testing the API projects flow",
        "defaultItem": false,
        "createdAt": "2017-11-10 00:32:14",
        "updatedAt": "2017-11-10 00:32:14",
        "apiDefaultCertainty": 0,
        "apiDefaultLevel": "A",
        "apiDefaultPriority": 20,
        "apiDefaultStore": false,
        "apiDefaultUAString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36",
        "apiDefaultViewportHeight": 768,
        "apiDefaultViewportWidth": 1024,
        "apiDefaultDelay": 0
    }
}
Spider Parameters

The following additional parameters are available when creating a 'spider' project

Key Type Description
url (required) StringThe URL at which the Spider will begin crawling. For example http://www.example.com
domain (required) StringThe domain that will be crawled. This can be set to limit to a specific domain/ subdomain, or can use a wildcard. For example www.example.com will be limited explicitly to that domain whereas *.example.com will allow crawl all subdomains under 'example.com'
limit (optional) NumberMaximum number of URLs to be crawled and tested. BE CAREFUL If unset, this value will be the total number of API calls you have available.
maxDepth (optional) NumberMaximum distance from the starting URL to crawl within the domain to be tested. By default this will be unlimited.
Sample Request body (Spider project type)
{
    "type": "spider",
    "name": "Spider project",
    "description": "Testing the Spider projects flow",
    "apiDefaultLevel": "A",
    "apiDefaultPriority": 20,
    "url": "http://www.example.com",
    "domain": "www.example.com",
}
Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T00:32:46.521Z",
    "responseID": "5c21f31513d09ef5eb0d623d3424098f",
    "request": {
        "type": "spider",
        "name": "Example",
        "description": "Example",
        "apiDefaultLevel": "AAA",
        "apiDefaultPriority": 0,
        "apiDefaultCertainty": 0,
        "url": "https://www.example.com",
        "domain": "www.example.com",
        "limit": 50000,
        "maxDepth": 10,
        "apiDefaultStore": true,
        "key": "[API_KEY_HERE]"
    },
    "project": {
        "domain": "www.example.com",
        "url": "https://www.example.com",
        "active": false,
        "limit": 50000,
        "ignoreRobots": false,
        "id": "2d148374-abb1-4e79-877e-c2db28adb00f",
        "type": "spider",
        "name": "Example",
        "description": "Example",
        "defaultItem": false,
        "createdAt": "2017-11-10 00:32:46",
        "updatedAt": "2017-11-10 00:32:46",
        "apiDefaultCertainty": 0,
        "apiDefaultLevel": "AAA",
        "apiDefaultPriority": 0,
        "apiDefaultStore": true,
        "apiDefaultUAString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36",
        "apiDefaultViewportHeight": 768,
        "apiDefaultViewportWidth": 1024,
        "apiDefaultDelay": 0
    }
}

PUT

PUT requests are used to update a project. PUT requests are identical to POST requests except that the projectID must match the ID of the project you wish to update

PUT

https://tenon.io/api/projects/:id/?key=:apiKey

Sample Request body (API project type)

{
    "type": "api",
    "name": "Example",
    "description": "Example",
    "apiDefaultLevel": "A",
    "apiDefaultPriority": 20
}
Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T03:12:56.530Z",
    "responseID": "ef750132da1199951980e21eb234ddaf",
    "request": {
        "id": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "type": "api",
        "name": "Example",
        "description": "Example",
        "apiDefaultLevel": "A",
        "apiDefaultPriority": 20,
        "key": "[API_KEY_HERE]"
    },
    "project": {
        "id": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "type": "api",
        "name": "Example",
        "description": "Example",
        "defaultItem": false,
        "updatedAt": "2017-11-10 03:12:56",
        "apiDefaultCertainty": 0,
        "apiDefaultLevel": "A",
        "apiDefaultPriority": 20,
        "apiDefaultStore": false,
        "apiDefaultViewportHeight": 0,
        "apiDefaultViewportWidth": 0,
        "apiDefaultDelay": 0
    }
}

DELETE

DELETE

https://tenon.io/api/projects/:id/?key=:apiKey

This request type deletes a specific project. Note that once deleted all associated project records - including all reports - will also be deleted and cannot be recovered.

Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T03:15:48.901Z",
    "responseID": "7e031f63a1d742a8d2707a9ebd4b217d",
    "projectID": "0af2cf21-ffe7-40a8-b62b-cf7f0958d2cf",
    "request": {
        "id": "0af2cf21-ffe7-40a8-b62b-cf7f0958d2cf",
        "key": "[API_KEY_HERE]"
    }
}

Project URLs

In addition to managing Projects via the API, you also have full RESTful access to the Projects' URLs as well. The following request methods are supported:

  • GET - retrieves information about Project URLs
  • POST - adds a new URL to a Project
  • DELETE - deletes an existing URL from a Project

PUT and the HEAD request methods are not supported

All requests that deal with Project URLs are structured like so: https://tenon.io/api/projects/:projectID/urls?key=:apiKey

GET

Get all URLs in a project

GET
https://tenon.io/api/projects/:projectID/urls?key=:apiKey
Sample Response
{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-11T14:04:05.085Z",
    "responseID": "7fd301fa052a3135aa6ead819bddd129",
    "request": {
        "projectID": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "key": "[API_KEY_HERE]"
    },
    "projectUrls": [
        {
            "id": "bcb020d7-5ce1-4262-82a3-06b5d2f78a82",
            "url": "http://www.foo.com"
        },
        {
            "id": "eb0be0da-e8d8-4bfa-9d66-7eed423fdccf",
            "url": "http://www.bar.com"
        }
    ]
}

Get a single URL by ID

GET
https://tenon.io/api/projects/:projectID/urls/:id?key=:apiKey
Sample Response
{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-11T14:18:06.529Z",
    "responseID": "5ccc569a3413e8732f62cf67565a2681",
    "request": {
        "projectID": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "id": "bcb020d7-5ce1-4262-82a3-06b5d2f78a82",
        "key": "[API_KEY_HERE]"
    },
    "projectUrl": {
        "id": "bcb020d7-5ce1-4262-82a3-06b5d2f78a82",
        "url": "http://www.foo.com"
    }
}

POST

POST

Sample Request
[
    {
        "url": "http://www.foo.com"
    },
    {
        "url": "http://www.bar.com"
    }
]
Sample Response
{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T14:19:55.860Z",
    "responseID": "2e3b51be7f8cc5a2de3e82b2abad7f78",
    "request": [
        {
            "url": "http://www.foo.com"
        },
        {
            "url": "http://www.bar.com"
        }
    ],
    "projectUrls": [
        {
            "id": "7105cdb6-e1d4-4ff7-90f1-f545c89ae660",
            "url": "http://www.foo.com"
        },
        {
            "id": "3fd63cb3-012a-4092-be01-0fa5c9aec1ff",
            "url": "http://www.bar.com"
        }
    ]
}

Special Case: POST URLs from sitemap

If you have an XML sitemap, Tenon's Projects API can consume the content of that file and add them to the project. Like all Project URLs, they'll be inserted into Tenon's queue for testing right away.

POST
https://tenon.io/api/projects/:projectID/urls/sitemap?key=:apiKey
Sample Request
{
  "url":"http://www.karlgroves.com/sitemap-posttype-post.xml"
}
Sample Response
{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T14:16:41.117Z",
    "responseID": "06a50153a3b8574394346263d9bcfca7",
    "request": {
        "projectID": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "url": "http://www.karlgroves.com/sitemap-posttype-post.xml",
        "key": "[API_KEY_HERE]"
    },
    "projectUrls": [
        {
            "id": "1dec6aa2-49c0-402a-8f7f-23a53d36c619",
            "url": "http://www.karlgroves.com/2011/11/15/list-of-web-accessibility-related-litigation-and-settlements/"
        },
        {
            "id": "d75318a6-ec22-404c-b22e-4258d7a68a35",
            "url": "http://www.karlgroves.com/2017/05/23/website-accessibility-in-the-united-states-what-are-your-requirements-under-the-ada/"
        },
        {
            "id": "b14d430d-7435-4f10-a978-2fad05178860",
            "url": "http://www.karlgroves.com/2016/07/13/how-long-does-it-take-to-test-25-billion-web-pages/"
        },
        {
            "id": "9cb2e2b6-6f5f-47a2-8482-25dd5d7089f0",
            "url": "http://www.karlgroves.com/2016/07/24/is-wcag-2-0-too-complicated/"
        },
        {
            "id": "32a26718-d0c0-47f6-8aa8-defa91417d4c",
            "url": "http://www.karlgroves.com/2016/08/13/should-you-use-more-than-one-accessibility-testing-tool/"
        }
    ]
}

DELETE

DELETE

https://tenon.io/api/projects/:projectID/urls/:id?key=:apiKey

Sample Response
{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://tenon.io/documentation/projects.php#success",
    "responseTime": "2017-11-10T18:04:27.140Z",
    "responseID": "00579259972acd9fc666d405a443bf0b",
    "request": {
        "projectID": "237E42A1-F744-D1C7-D22D-BC6877D4CE11",
        "id": "1a3d21d4-202b-4fa1-8b6f-30c10b39a833",
        "key": "[API_KEY_HERE]"
    },
    "deleted": true,
    "projectUrlID": "1a3d21d4-202b-4fa1-8b6f-30c10b39a833"
}

Response Status Codes and Messages

Status Codes

CodeDescription
200 OKThis code is returned whenever the request was successful.
  • In GET requests, it means that the request was successful and results were found. In cases where zero results are displayed, it means there were no records that were applicable.
  • In POST requests, it means that the record was added successfully.
  • In PUT requests, it means that the record was updated successfully.
  • In DELETE requests, it meas that the record was deleted successfully.
400 Bad RequestThis code is returned whenever a required parameter is not set or is set but invalid
401 UnauthorizedThis code is returned whenever the API key supplied was invalid
402 Payment RequiredThis code is returned whenever the API key supplied whenever the plan associated with the supplied API key has expired.
404 Not Found In GET, PUT, and DELETE requests, this status is returned whenever the project requested via the projectID parameter does not exist.
405 Method Not Allowed This code is returned for any request types other than GET,POST, PUT, or DELETE requests.
409 Duplicate Record In POST requests it means that there is an identical record already in the system
500 Internal Server Error This means something went wrong on our end.
522 Connection Timed OutThis means something went wrong on our end. Chances are something took too long to process.

All responses also get a 'message' to provide more details for the response. For 400 responses this can provide more information in determining what went wrong:

  • api_credentials_invalid indicates that the API key supplied was not set, expired, or invalid in some other way
  • invalid_param indicates that one or more request parameters are invalid.
  • abuse_detected indicates that we have detected abusive traffic or other signs of abuse
  • required_param_missing indicates that one or more required parameter has not been supplied as part of the request

Response Format

All responses from the Projects API will contain the following pieces of information:

  • responseTime: Time of your request, localized to GMT
  • status: HTTP status code for your response.
  • code: a token string showing what the response was, as listed above<./li>
  • message: The associated message for the code, per RFC 2616
  • moreInfo: an URL to a more detailed explanation of the code
  • responseID: an autogenerated string identifying the response
  • request: This object is a complete mirror of the request you sent to us.
  • info: This will be a string of text describing any important details for understanding the response.

In addition to the above: Under GET, POST, and PUT requests, the API will return the full details for all of the projects that have been returned, created, or modified.