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.

Note on all Projects API routes, the Content-Type header explicitly needs to be set to application/json. Get a full list of samples as a Postman Collection.

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://www.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://www.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://www.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://www.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://www.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

The defaultItem parameter indicates whether or not you wish this project to become the "default" project.
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 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.
apiDefaultViewportWidth (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.
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 

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://www.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) String The URL at which the Spider will begin crawling. For example http://www.example.com
domain (required) String The 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) Number Maximum 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) Number Maximum 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://www.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://www.tenon.io/api/projects/:projectID?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://www.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

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.

DELETE

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

Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://www.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://www.tenon.io/api/projects/:projectID/urls?key=:apiKey

GET

Get all URLs in a project

GET

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

Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://www.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://www.tenon.io/api/projects/:projectID/urls/:id?key=:apiKey

Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://www.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

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

Sample Request

[
    {
        "url": "http://www.foo.com"
    },
    {
        "url": "http://www.bar.com"
    }
]
Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://www.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://www.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://www.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://www.tenon.io/api/projects/:projectID/urls/:id?key=:apiKey

Sample Response

{
    "status": 200,
    "message": "OK",
    "code": "success",
    "moreInfo": "https://www.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
Code Description
200 OK
  • 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 Request This code is returned whenever a required parameter is not set or is set but invalid
401 Unauthorized This code is returned whenever the API key supplied was invalid
402 Payment Required This 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 Out This 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
  • 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.