API basics

This guide describes the official Dradis Pro API. If you have any problems or requests, please contact the support team.

Jump to: Current version | Schema | HTTP Verbs | Parameters | Authentication | Error codes | Endpoint cheatsheet

Current Version

By default, all requests receive the v1 version of the API. We encourage you to explicitly request this version via the Accept header.

Accept: application/vnd.dradisproapi; v=1

Schema

All API access is over HTTPS, and accessed through dradis-pro.dev/pro/api. All data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

  • HEAD: Can be issued against any resource to get just the HTTP header info.
  • GET: Used for retrieving resources.
  • POST: Used for creating resources
  • PUT: Used for updating resources with partial JSON data. A PUT request may accept one or more of the attributes to update the resource.
  • DELETE: Used for deleting resources.

Parameters

For POST, PATCH, PUT, and DELETE requests, parameters should be encoded as JSON with a Content-Type of application/json:

$ curl \
  -H 'Authorization: Token token="xMsNwttqN5bVNEYcrIF01s65"' \
  -H 'Content-type: application/json' \
  -d '{"client":{"name":"Test Client 4"}}' \
  https://dradis-pro.dev/pro/api/clients

Authentication

The API supports two different authentication modes: API token and HTTP Basic.

API token

Provide your token as part of the HTTP Authorization header:

Authorization: Token token="<API_token>"

Note that the header requires you to use double-quotes (").

For example:

$ curl \
  -H 'Authorization: Token token="xMsNwttqN5bVNEYcrIF01s65"' \
  https://dradis-pro.dev/pro/api/projects/1
Find your API token
  1. In the header, click the avatar icon in the top right corner and then select Profile from the dropdown that appears.
  2. Scroll down below Confirm password to find your API token:

Basic Authentication

Use the same credentials you log in with:

$ curl -u 'your@email.com' https://dradis-pro.dev/pro/api/projects/1
Enter host password for user 'your@email.com':

Error codes

These are the possible types of errors on API calls. The response will include a JSON object with the description and the proper HTTP status code:

HTTP Status Message Description
401 Authentication required No authentication credentials have been provided. Use one of the supported authentication methods (token or basic authentication).
403 Forbidden The authenticated user does not have access to this operation. Use a different user or ask the administrator to set the needed permissions for the current user.
404 Not found The resource couldn't be found.
415 JSON required Content-Type header needs to be set to 'application/json' for this request
422 Validation error Some fields have invalid values. Check the "errors" array in the response for further information.
500 Internal server error The application found an unexpected condition that prevented it from fulfilling the request.

Endpoints Cheatsheet

Check out the following pages for more details on each of the available endpoints:

Endpoint Description
Clients Retrieve details about the Clients on your instance.
Projects Retrieve content about all of the projects or work with a specific project.
Nodes Retrieve and work with the Nodes in a specific project.
Issues Retrieve and work with the Issues in a specific project.
Evidence Retrieve and work with the Evidence associated with specific Nodes in your project.
Notes Retrieve and work with the Notes associated with specific Nodes in your project.

Next help article: Clients endpoint →