Skip to content
Get a free accessibility consultation

Understanding Tenon API Request Parameters

This document discusses all of the various request parameters available to Tenon API users. The number and kinds of request parameters we provide allows Tenon to work for you in a way that matches your specific goals and needs.

Required Parameters

There are only two required parameters: 'key' and either 'url' or 'src'.

key
The key parameter is the API key you received upon registering. The key is required for every API request you send. Missing or invalid keys will result in error response.
url or src

Either the url or src are required for testing. The URL must be a fully qualified URL that the API has access to. If any GET parameters are required in order to access the URL, you must supply them as part of the URL. If using src it must be a string of document source only (HTML, CSS, and JavaScript).

Supplying both url and src, beyond being plain silly, will result in only the URL being tested.

When supplying src, this can be anything ranging from the source of a complete document or only a fragment of a document (mark this case using the fragment parameter, described below). The src is preferable when testing something that is otherwise not available via URL.

Notes on testing Source

If using src, ensure that the path to all document assets is set to a fully qualified path, otherwise those assets (and their impact on the UI) will not be accurately tested. For instance, if you're testing a document fragment that consists of a JavaScript-driven widget, you'll need to also do one of the following:

  • include either the JavaScript and CSS source in the document itself,
  • include the fully qualified path of the relevant assets in the relevant <script> and <link> tags of the source string,
  • or, send over the rendered document source in its state after the JavaScript.

Remember: the important part of testing is to test that which will be experienced by the user which means, if testing document source, you should send over a "rendered" version of the source.

Note: If you plan to send over document source, you may want to explore utilizing a Grunt plugin like Grunt HTML Smoosher to help prepare the source.

Optional Parameters

All of the below parameters are optional for all users. Some of these parameters may not be available to you depending upon your plan. For specific details on what your plan allows, review your plan details.

Providing any value outside of the accepted list of values will result in failure.

certainty

Sometimes accessibility tools will return results that the tool isn't completely sure is a real issue. The certainty parameter allows you to filter out these "uncertain" results by choosing a minimum acceptable certainty score.

  • Valid values: must be one of '0','20','40','60','80','100'.
  • The default value is '0', meaning that the minimum certainty score for issues returned is '0'.

Note: You probably don't want to only choose '100' as this will, in practice, probably be too conservative. We try to create tests that return real results and so very low certainty scores should be few and far between. As a general guide, if integrating Tenon into an automated build or pre-commit hook, use 80 and above. For a QA scenario, choose the lowest value you can tolerate as an organization.

projectID

The projectID parameter is a string of text you can supply to identify the tested document as part of a specific project. All users get a "Default Project" when you sign up. You must go to your projects to retrieve the necessary projectID or to set up new projects.

  • Valid values: if supplied, this must match the projectID of an already-existing project in your account.

Note: it is your responsibility to ensure accuracy and validity of the supplied string. We will accept any (safe) arbitrary string for this parameter. If no value is supplied, the report will go into your default project.

docID

The docID parameter is a string of text used to identify the page being tested. This can be used by you to track the performance of a specific page. Although this can also be done via the URL, you can also use this when testing document source, for which there is no useful URL.

  • Valid values: If supplied, can be any arbitrary alphanumeric string between 16 and 255 characters in length. It must be an unbroken string (In other words it must not contain spaces). The only punctuation allowed is '-' and '_'.
  • If your request does not contain a docID, we will generate a GUID formatted string for the docID.
priority

Each Best Practice in the system has a number of factors that allow us to determine their relative priority. In your result set, each issue reported will be given a calculated priority score which you can then use to filter or order your results.

  • Valid values: must be one of '0','20','40','60','80','100'.
  • Default value will be '0'. As a consequence all issues, regardless of Priority, will be reported.

Note: in practice, it is unlikely that an issue returned will have 100% priority. Like certainty, you should supply the lowest priority you can, especially when first starting out. Setting this too high may result in no errors returned.

level

The level parameter indicates the "lowest" WCAG level to test against.

  • Valid values: must be one of 'A','AA','AAA'. Chosing "AA", for instance, will test both "AA" and "A" success criteria.
  • Default value is 'AAA', meaning that all tests for AAA, AA, and A will be run.

Note: Keep in mind that WCAG Level does not actually correlate to Priority when determining what to test for. For more information on our philosophy regarding prioritization, see blog post by Karl Groves: Understanding WCAG Level.

In practice, very few of the Level AAA Success Criteria are testable using automated means and therefore you'll see few tests against these anyway. Despite this, we recommend selecting "AAA" for the level parameter and being more stringent in your certainty setting, because it is likely that doing so will have a greater impact against False Positives than filtering by Level.

delay (formerly waitFor)

The delay parameter tells the API to wait a specified amount of time, in milliseconds, before beginning execution of tests. This is a very important parameter for web pages that get content from Ajax or 3rd party CDNs. If you have performance issues, you should strongly consider using it.

  • Value supplied muse be numeric string only.
  • Value should be supplied in milliseconds. In other words, '1000' is 1 second, '2000' is 2 seconds, etc.
  • Setting this value too high may result in a request timeout from the API.
store

The store parameter indicates whether or not Tenon should store your results. You can then come back later and view your results in our Web-based system.

  • Valid values: must be one of '0','1' representing 'false' and 'true'.
  • Default value is '0', meaning that we will not store the results.
  • If you set this to '1' you can later retrieve the stored results by using the URL pattern: https://tenon.io/history.php?responseID=[xxx] where the value for the 'responseID' parameter is the value returned in the response.

Note: The length of time we will store the results depends upon your plan.

fragment

The fragment parameter indicates whether or not you are testing only a portion of the page.

  • Valid values: must be one of '0','1' representing 'false' and 'true'.
  • Default value is '0', meaning that we will treat the page as though it is a complete page.
uaString

The uaString parameter allows you to supply any arbitrary string of text which will be sent as the User-Agent string when we request the URL you supply. This is particularly useful if your site does any user-agent sniffing.

  • Valid values: can be any arbitrary string up to 255 characters in length.

Note: it is your responsibility to ensure accuracy and validity of the supplied string. We will accept any (safe) arbitrary string for this parameter. If no value is supplied, Tenon identifies itself with a Google Chrome user-agent string.

viewPortHeight

The viewPortHeight parameter sets the height, in pixels, of the viewport for our headless browser.

  • Valid values: must be a string consisting only of numeric characters, no more than four characters in length. In other words, it can be any positive number between 0 and 9999.

Note: If this parameter it is not supplied at time of request it will be set to '768'. If you set one viewport parameter you must set both.

viewPortWidth

The viewPortWidth parameter sets the width, in pixels, of the viewport for our headless browser. This parameter is particularly useful when testing the accessibility of your responsive design.

  • Valid values: must be a string consisting only of numeric characters, no more than four characters in length. In other words, it can be any positive number between 0 and 9999.

Note: If this parameter it is not supplied at time of request it will be set to '1024'. If you set one viewport parameter you must set both.