Skip to content

Projects API & Spider

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.

This request type gets all projects you have access to.

Sample Response

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

Sample Response

POST

This request type creates a new project.

Allowed Parameters

type (required)

Type: 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)

Type: String

The name parameter allows you to define a human-readable name for the project.

description (optional)

Type: 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)

Type: 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)

Type: 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)

Type: 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)

Type: 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)

Type: 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)

Type: 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)

Type: 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)

Type: 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)

Type: Number

The default delay 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.

Sample Request body (API project type)
Sample Response (api type project)
Spider parameters

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

url (required)

Type: String

The URL at which the Spider will begin crawling. For example http://www.example.com.

domain (required)

Type: 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)

Type: 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)

Type: 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)
Sample Response

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:

Sample Request body (API project type)

Sample Response

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.

Sample Response

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

Sample Response

Get a single URL by ID

Sample Reponse

POST

Sample Request

Sample Response

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.

Sample Request
Sample Response

DELETE

Sample Response

Response Status Codes and Messages

Status Codes

200 OK

This 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 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<./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.