API v2 Documentation

v: 4.11 · 4.10 · 4.9 · 4.8 · 4.7 · 4.6 · 4.5 · 4.4 · 4.3 · 4.2 · 4.1 · 4.0 · 3.8 · 3.7 · 3.6 · 3.5 · 3.4 · 3.3 · 3.2 · dev

NAV undefined

Introduction

Welcome to SD Elements API v2! Our API provides RESTful HTTP access to a large part of the functionality of SD Elements.

SD Elements's API documentation page was created with Slate

API Format

API results are currently returned in XML and JSON formats. It is advised to use the JSON format only. Specify the JSON format by including the HTTP header in all requests:

Content-type: application/json

Include Parameters

Some endpoints allow users to include extra fields in the response the API returns. This is used to add a specific field to an element, or collection of elements. For example, we may wish to receive a collection of projects that are within an application. Since projects are normally not a field of the applications resource, we can include projects in our request to see the projects as an additional field.

/?include={field_to_include}

Expand Parameters

Some endpoints allow users to expand a field that is already present in the response. For example, by default, an application element contains the id of the business unit to which it belongs. If we wish to retrieve more information about the business unit, we would expand the business unit field to get more information.

/?expand={field_to_expand}

It is possible to include and expand more than one field simultaneously.

/?include={field1},{field2}&expand={field3},{field4}

Pagination

Consume long responses by enabling pagination on an endpoint. Specify a page size in the URL:

/?page_size=10

This will limit the result set down to 10 (or fewer) elmenets. There will be a few additional values returned in addtion to the results list. next and previous are URLs you can request to get the next or previous result set. count is the total number of resources available.

Authentication

There are several ways to authenticate against SD Elements, which are outlined below.

Basic Authentication

GET /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"

To authenticate against SD Elements using basic authentication (username and password), you need to pass a Base64 encoding of your username:password as a header.

Session Authorization

GET /api/v2/users/ HTTP/1.1
Accept: application/json
Cookie: sessionid="YOUR SESSION ID"

To authenticate against SD Elements using session authentication, you need to pass in your session id as a cookie in the header.

Token Authentication

GET /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

To authenticate against SD Elements using tokens, you need to pass an API access token via an Authorization header.

A token can be generated as follows:

Help

If you have any questions/feedback regarding the SD Elements APIv2, please reach out to us. We're here to help. You can email SD Elements Support at support@sdelements.com.

Errors

The SD Elements API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid
401 Unauthorized -- Your API key is incorrect
403 Forbidden -- The resource requested is hidden for administrators only
404 Not Found -- The specified resource could not be found
405 Method Not Allowed -- You tried to access a resource with an invalid method
406 Not Acceptable -- You requested a format that isn't json
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Resources

The most common types of resources obtained from this API are Collections and Elements. A collection represents the set of all resources of a particular type (such as "projects" or "applications"). An element resource represents an individual member of a collection. Each element consists of a set of name/value pairs.

Activities

Get all activities

GET /api/v2/activities/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        id: 5,
        name: "CreatedGroupActivity",
        actor: 1,
        text: "Admin Testerton created group group A",
        date: "2016-05-06T14:53:28.557156Z",
        data: {
            target_group_desc: "group A",
            group: "G1",
            group_desc: "group A"
        },
        icon: "user",
        log_level: "success"
    },
    {
        "id": 3,
        "date": "2016-03-30T17:10:20.532634+00:00",
        "actor": 7,
        "name": "ModifiedBusinessUnitActivity",
        "text": "Admin Testerton modified business unit Example BU 500",
        "data": {
            "business_unit": 5,
            "business_unit_desc": "Example BU 500"
        },
        "icon": "edit",
        "log_level": ""
    },
    {
        "id": 2,
        "date": "2016-03-30T15:16:05.659610+00:00",
        "actor": 1,
        "name": "UserCreatedActivity",
        "text": "Admin Testerton created user Cindy Lu",
        "data": {"user": "U7}",
        "icon": "user",
        "log_level": ""

    },
    {
        "id": 1,
        "date": "2016-03-30T15:14:46.634929+00:00",
        "actor": 1,
        "name": "LoggedInActivity",
        "text": "Admin Testerton logged in",
        "data": {},
        "icon": "user"
        "log_level" : ""
    }]
}

This endpoint returns a list of Activities. Activities are events that have occurred in the application. We return when they occurred and some additional data about the event.

GET /api/v2/activities/

Note: this endpoint uses the term 'standard' to reference what we call 'library tasks' elsewhere in the API.

The application, business_unit, project, and standard fields have associated description fields, suffixed with '_desc'. These fields contain a description of the related item, and can be used to filter if the related item has been deleted.

Query Parameters

The following parameters may be used to filter the activity resources in the response.

Parameter Description
actor Returns a list of activities performed by the user with the id specified.
application Returns a list of activities that reference the application with the specified id.
application_desc Returns a list of activities that reference the application with the specified application name.
business_unit Returns a list of activities that reference the business unit with the specified id.
business_unit_desc Returns a list of activities that reference the business_unit with the specified business unit name.
date_to Returns all activities performed at or before the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime.
date_from Returns all activities performed at or after the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime.
id Returns the activities with the specified id.
name Returns a list of activities with the specified name.
project Returns a list of activities that reference the project with the specified id.
project_desc Returns a list of activities that reference the project with the specified project name.
user Returns a list of activities that reference the user with the specified user id (not to be confused with activities that are performed by this user). The id used here is a number, for example ?user=1.
standard Returns a list of activities that reference the standard with the specified id. The format of this parameter value is the standard id prefixed by a 'T' for builtin standards or 'CT' for custom standards.
standard_desc Returns a list of activities that reference the standard with the specified standard's full name, for example: "T21: Ensure confidential data is sent over an encrypted channel".

Get a Specific Activity

GET /api/v2/activities/2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
        "id": 2,
        "date": "2016-03-30T15:16:05.659610+00:00",
        "actor": 1,
        "name": "UserCreatedActivity",
        "text": "Admin Testerton created user Cindy Lu",
        "data": {"user": "U7"},
        "icon": "user",
        "log_level": ""

}

This endpoint retreives a specific Activity Resource as specified by the activity_id.

GET /api/v2/activities/{activity_id}/

URL Parameters

Parameter Description
activity_id The id of the Activity Resource to retrieve.

Analysis Notes

Get All Analysis Notes

GET /api/v2/projects/1936/tasks/1-T2/analysis-notes/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 875,
        "analysis_session": 334,
        "analysis_type": {
            "slug": "manual",
            "name": "Manual Verification"
        },
        "behaviour": "replace",
        "confidence": "high",
        "created": "2015-03-26T19:50:46.348000Z",
        "findings": {},
        "finding_ref": "my_ref",
        "status": "pass",
        "automatic": true,
        "updated": "2015-06-05T02:55:54.231254Z",
        "updater": {
            "id": 599,
            "email": "user@example.com",
            "first_name": "Bob",
            "last_name": "Smith"
        }
    }]
}

This endpoint returns a list of Analysis Note resources for a specific project task.

GET /api/v2/projects/{project_id}/tasks/{task_id}/analysis-notes/

Get a Specific Analysis Note

GET /api/v2/projects/1936/tasks/1-T2/analysis-notes/682/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 875,
    "analysis_session": 334,
    "analysis_type": {
        "slug": "manual",
        "name": "Manual Verification"
    },
    "behaviour": "replace",
    "confidence": "high",
    "created": "2015-03-26T19:50:46.348000Z",
    "findings": {},
    "finding_ref": "my_ref",
    "status": "pass",
    "automatic": true,
    "updated": "2015-06-05T02:55:54.231254Z",
    "updater": {
        "id": 599,
        "email": "user@example.com",
        "first_name": "Bob",
        "last_name": "Smith"
    }
}

This endpoint returns a specific Analysis Note resource.

GET /api/v2/projects/{project_id}/tasks/{task_id}/analysis-notes/{note_id}/

Create an Analysis Note

POST /api/v2/project/1/tasks/1-T12/analysis-notes/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "analysis_session": 334,
    "behaviour": "replace",
    "confidence": "high",
    "findings": {},
    "finding_ref": "my_ref",
    "status": "pass"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 875,
    "analysis_session": 334,
    "analysis_type": {
        "slug": "manual",
        "name": "Manual Verification"
    },
    "behaviour": "replace",
    "confidence": "high",
    "created": "2015-03-26T19:50:46.348000Z",
    "findings": {},
    "finding_ref": "my_ref",
    "status": "pass",
    "automatic": true,
    "updated": "2015-06-05T02:55:54.231254Z",
    "updater": {
        "id": 599,
        "email": "user@example.com",
        "first_name": "Bob",
        "last_name": "Smith"
    }
}

This endpoint creates a single Analysis Note resource.

POST /api/v2/projects/{project_id}/tasks/{task_id}/analysis-notes/

Fields Required Description
analysis_session No The ID of the related Analysis Session.
Not required if this is a manual verification.
behaviour Yes See Behaviour section below.
confidence Yes "high" or "low"
findings Yes JSON object/array representing analysis findings
finding_ref No
status Yes "pass", "partial", "fail", or "none"
task_status_mapping No See Task Status Mapping section below.
automatic No Whether the Task Note was posted by a tool. Default is false.

Behaviour

Value Description
combine Combine with all previous results
replace-scanner Overwrite previous results from this tool
replace Overwrite all previous result

Task Status Mapping

You can provide an object that maps Analysis Note statuses to Task Statuses.

SD Elements will then use this mapping object to automatically change the status of the associated task based on the status of the Analysis Note.

The object format is:

{ "<note_status>": "<task_status_slug>", ...etc... }

An example:

{ "pass": "DONE", "fail": "TODO" }

Analysis Sessions

Get All Analysis Sessions

GET /api/v2/projects/1/analysis-sessions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 682,
        "analysis_ref": "zero.webappsecurity.com",
        "analysis_type": "webinspect",
        "extra": {},
        "created": "2014-12-15T20:10:51.900775Z",
        "updated": "2014-12-15T20:10:51.900775Z",
        "updater": 1
    }]
}

This endpoint returns a list of Analysis Session resources.

GET /api/v2/projects/{project_id}/analysis-sessions/

Get a Specific Analysis Session

GET /api/v2/projects/1/analysis-sessions/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 682,
    "analysis_ref": "zero.webappsecurity.com",
    "analysis_type": "webinspect",
    "extra": {},
    "created": "2014-12-15T20:10:51.900775Z",
    "updated": "2014-12-15T20:10:51.900775Z",
    "updater": 1
}

This endpoint returns a specific Analysis Session resource.

GET /api/v2/projects/{project_id}/analysis-sessions/{analysis_session_id}/

Create an Analysis Session

POST /api/v2/projects/1/analysis-sessions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "analysis_ref": "zero.webappsecurity.com",
    "analysis_type": "webinspect"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1,
    "analysis_ref": "zero.webappsecurity.com",
    "analysis_type": "webinspect",
    "extra": {},
    "created": "2014-12-15T20:10:51.900775Z",
    "updated": "2014-12-15T20:10:51.900775Z",
    "updater": 1
}

This endpoint creates an Analysis Session resource.

POST /api/v2/projects/{project_id}/analysis-sessions/

Fields Required Description
analysis_ref Yes Arbitrary string used as a session identifier
analysis_type Yes Enum that identifies the type of analysis tool.
Can be one of the following:
  • appscan
  • appscan_enterprise
  • fortify
  • veracode
  • webinspect
  • whitehat
notes No An array of Analysis Note resources.
See Create an Analysis Note for what fields are supported/required.
The "task" attribute field is required, but "analysis_session" is not required.

Create an Analysis Session with embedded Notes

POST /api/v2/projects/1/analysis-sessions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "analysis_ref": "zero.webappsecurity.com",
    "analysis_type": "webinspect",
    "notes": [
      {
          "task": "1-T6",
          "behaviour": "replace",
          "confidence": "high",
          "findings": {},
          "finding_ref": "my_ref",
          "status": "pass"
      }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 682,
    "analysis_ref": "zero.webappsecurity.com",
    "analysis_type": "webinspect",
    "extra": {},
    "created": "2014-12-15T20:10:51.900775Z",
    "updated": "2014-12-15T20:10:51.900775Z",
    "updater": 1
}

API Tokens

Generate an API Token

POST /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "1234567890abcdefghijklmnopqrstuvwxyz",
    "connection_string": "1234567890abcdefghijklmnopqrstuvwxyz@example.com"
}

This endpoint returns a newly generated API Token. If the user already has a token, it will be regenerated.

Note: This endpoint only uses either basic or session authentication.

POST /api/v2/users/{user_id}/api-token/

URL Parameters

Parameter Description
user_id The ID of the User to retrieve

Regenerate an API Token

PUT /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "1234567890abcdefghijklmnopqrstuvwxyz",
    "connection_string": "1234567890abcdefghijklmnopqrstuvwxyz@example.com"
}

This endpoint revokes and then regenerates an API Token.

Note: This endpoint only uses either basic or session authentication.

PUT /api/v2/users/{user_id}/api-token/

URL Parameters

Parameter Description
user_id The ID of the User to retrieve

Get an API Token

GET /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "***********************************vwxyz",
    "connection_string": "***********************************vwxyz@example.com"
}

This endpoint retrieves the users API Token. For security reasons the token will be obfuscated. If you have lost your token you will have to regenerate it.

Note: This endpoint only uses either basic or session authentication.

GET /api/v2/users/{user_id}/api-token/

URL Parameters

Parameter Description
user_id The ID of the User to retrieve

Revoke an API Token

DELETE /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"
HTTP/1.1 204 NO CONTENT

This endpoint revokes the users current API Token. Only admin users can revoke API Tokens of other users.

Note: This endpoint only uses either basic or session authentication.

DELETE /api/v2/users/{user_id}/api-token/

URL Parameters

Parameter Description
user_id The ID of the User to retrieve

Applications

Get All Applications

GET /api/v2/applications/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "business_unit": 1,
        "name": "Application Test",
        "created": "2015-04-15T20:27:24.396442Z",
        "updated": "2015-04-15T20:27:24.389957Z",
        "priority": "0-none",
        "slug": "application-test"
    }]
}

This endpoint retrieves a list of Application resources.

GET /api/v2/applications/

Query Parameters

The following parameters may be used to filter the application resources in the response.

Parameter Description
business_unit Filter applications by Business Unit ID.
name Filter applications by name.
priority Filter applications by priority.
slug Filter applications by slug.
ordering Sort applications by the specified field. Prefix field name with minus to sort descending. Sortable fields: name.
search Filter applications by performing a textual search on name.

Expand Parameters

GET /api/v2/applications/?expand=business_unit HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 3,
        "business_unit": {
            "id": 1,
            "slug": "example-business-unit-1",
            "name": "example business unit 1"
        },
        "name": "Application Test",
        "created": "2015-04-15T20:27:24.396442Z",
        "updated": "2015-04-15T20:27:24.389957Z",
        "priority": "0-none",
        "slug": "application-test"
    }]
}

See the Expand Parameters section for more details.

Parameter Description
business_unit Expand the business unit field of the application

Include Parameters

GET /api/v2/applications/?include=projects HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 3,
        "business_unit": 1,
        "name": "Application Test",
        "created": "2015-04-15T20:27:24.396442Z",
        "updated": "2015-04-15T20:27:24.389957Z",
        "priority": "0-none",
        "slug": "application-test",
        "projects": [
            {
                "id": "1",
                "name": "Project 1",
                "slug": "project-1",
                "url": "http://example.com/bunits/test-bu/application-test/project-1/"
            },
            {
                "id": "2",
                "name": "Project 2",
                "slug": "project-2",
                "url": "http://example.com/bunits/test-bu/application-test/project-2/"
            }
        ]
    }]
}

See the Include Parameters section for more details.

Parameter Description
projects Includes a list of projects associated with an application

Get a Specific Application

GET /api/v2/applications/3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 3,
        "business_unit": 1,
        "name": "Application Test",
        "created": "2015-04-15T20:27:24.396442Z",
        "updated": "2015-04-15T20:27:24.389957Z",
        "priority": "0-none",
        "slug": "application-test"
    }]
}

This endpoint retrieves a specific Application resource, as specified by the id parameter.

GET /api/v2/applications/{application_id}/

URL Parameters

Parameter Description
application_id The id of the application to retrieve

All of the expand and include parameters for the 'Get all Applications' endpoint apply here as well.

Create a New Application

POST /api/v2/applications/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "business_unit": 1,
    "name":"API Test"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "results": [{
        "id": 3,
        "business_unit": 1,
        "name": "API Test",
        "created": "2015-04-15T20:27:24.396442Z",
        "updated": "2015-04-15T20:27:24.389957Z",
        "priority": "0-none",
        "slug": "api-test"
    }]
}
Fields Required Description
business_unit Yes The ID of the business unit the application belongs to
name Yes The name of the new application
priority No Specifies the priority of the application to be either '0-none', '1-high', '2-medium' or '3-low'

Update an Application

PUT /api/v2/applications/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "Edit Test",
    "business_unit": 2
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "business_unit": 2,
        "name": "Edit Test",
        "created": "2015-06-18T19:27:14.860536Z",
        "updated": "2015-06-18T21:00:03.827952Z",
        "priority": "0-none",
        "slug": "api-test"
    }]
}

Update a single application by specifying a new name and new business unit. The application to update is identified by the id.

PUT /api/v2/applications/{application_id}/

URL Parameters

Parameter Description
application_id The id of the application to edit must be submitted in the request

Payload

Fields Required Description
name No The name of the application can be changed to any other string
business_unit No This can be edited by setting the business unit id
priority No The three options are: '0-none', '1-high', '2-medium', '3-low'

Delete an Application

DELETE /api/v2/applications/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT

This endpoint deletes a single Application resource, as specified by the id parameter.

DELETE /applications/{application_id}/

URL Parameters

Parameter Description
application_id The id of the application to retrieve

Business Units

Get All Business Units

GET /api/v2/business-units/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": 1,
            "slug": "example-business-unit-1",
            "name": "example business unit 1",
            "created": "2015-09-30T18:28:37.214914Z",
            "updated": "2015-09-30T18:28:37.214959Z",
            "default_groups": [],
            "default_users": [],
            "users": [{
                "id": 682,
                "email": "frank@sdelements.com",
                "first_name": "Frank",
                "last_name": "Testerton",
                "is_active": true,
                "role": {
                    id: "UR1",
                    name: "User"
                }
            }],
            "groups": [{
                "id": "G64",
                "name": "Group Bar"
            }],
            "all_users": false
        },
        {
            "id": 2,
            "slug": "example-business-unit-2",
            "name": "example business unit 2",
            "created": "2015-09-30T19:30:25.254036Z",
            "updated": "2015-09-30T19:30:25.254072Z",
            "default_users": [],
            "default_groups": [],
            "users": [],
            "groups": [],
            "all_users": true,
            "persist_phases": false
        }
    ]
}

This endpoint retrieves a list of Business Unit resources, respecting the permissions of the user who has made the request.

GET /api/v2/business-units/

Query Parameters

The following parameters may be used to filter the business unit resources in the response.

Parameter Description
name Filter business units by name.
ordering Sort business units by the specified field. Prefix field name with minus to sort descending. Sortable fields: name.
search Filter applications by performing a textual search on name.

Get a Specific Business Unit

GET /api/v2/business-units/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "slug": "example-business-unit-1",
    "name": "example business unit 1",
    "created": "2015-09-30T18:28:37.214914Z",
    "updated": "2015-09-30T18:28:37.214959Z",
    "default_groups": [],
    "default_users": [],
    "users": [{
        "id": 682,
        "email": "frank@sdelements.com",
        "first_name": "Frank",
        "last_name": "Testerton",
        "is_active": true,
        "role": {
            id: "UR1",
            name: "User"
        }
    }],
    "groups": [{
        "id": "G64",
        "name": "Group Bar"
    }],
    "all_users": false,
    "persist_phases": false
}

This endpoint retrieves a specific Business Unit resource, as specified by the id parameter.

GET /api/v2/business-units/{business_unit_id}/

URL Parameters

Parameter Description
business_unit_id The id of the Business Unit to retrieve.

Create a New Business Unit

POST /api/v2/business-units/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "API Test",
    "users": [{"email": "test@example.com"}],
    "groups": [{"id": "G1"}],
    "default_users": [{"email": "test@example.com", "role": "PR4"}],
    "default_groups": [{"id": "G1", "role": "PR4"}],
    "all_users": false,
    "persist_phases": false
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 541,
    "slug": "api-test",
    "name": "API Test",
    "created": "2015-09-30T18:28:37.214914Z",
    "updated": "2015-09-30T18:28:37.214959Z",
    "users": [{
        "id": 1,
        "email": "test@example.com",
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true,
        "role": {
            id: "UR1",
            name: "User"
        }
    }],
    "groups": [{
        "id": "G1"
    }],
    "default_users": [{
        "email": "test@example.com",
        "role": "PR4",
        "id": 1,
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true
    }],
    "default_groups": [{
        "id": "G1",
        "role": "PR4"
    }],
    "all_users": false,
    "persist_phases": false
}
Fields Required Description
name Yes The name of the new business unit.
users No A list of dictionaries representing the users who are part of the business unit. Each dictionary has an email field.
groups No A list of dictionaries representing the groups which are part of the business unit. Each dictionary has an id field which is the group id.
default_users No A list of dictionaries representing the default user roles for the users in the business unit. Each dictionary has an email field and a role field where the role is the role id. The users specified here should be members of the business unit unless all_users is true.
default_groups No A list of dictionaries representing the default group roles for the users in the business unit. Each dictionary has an id field which is the group id and a role field where the role is the role id. The groups specified here should be members of the business unit unless all_users is true.
all_users No Whether the business unit includes all users. Trying to create a business unit with this field set to True and specific users/groups specified is an error. Default is false.
persist_phases No Set the persistence of TODO tasks that belong to active phases in a project within this business unit.

Update a Business Unit

PUT /api/v2/business-units/36/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "New BU Name"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 36,
    "slug": "api-test",
    "name": "New BU Name",
    "created": "2015-09-30T18:28:37.214914Z",
    "updated": "2015-09-30T18:28:37.214959Z",
    "users": [{
        "email": "test@example.com",
        "id": 1,
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true,
        "role": {
            id: "UR1",
            name: "User"
        }
    }],
    "groups": [{
        "id": "G1"
    }],
    "default_users": [{
        "email": "test@example.com",
        "role": "PR4",
        "id": 1,
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true
    }],
    "default_groups": [{
        "id": "G1",
        "role": "PR4"
    }],
    "all_users": false,
    "persist_phases": false
}

Update a single business unit by specifying the id. The fields users, groups, name, default_users, and default_groups can be updated.

PUT /api/v2/business-units/{business_unit_id}/

URL Parameters

Parameter Description
business_unit_id The id of the Business Unit to update.

Delete a Business Unit

DELETE /api/v2/business-units/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT

This endpoint deletes a single Business Unit resource, as specified by the id parameter.

DELETE /business-units/{business_unit_id}/

URL Parameters

Parameter Description
business_unit_id The id of the Business Unit to delete.

Connections

Get LDAP Connections for the current organization

GET /api/v2/connections/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "results": [{
        "id": 15,
        "alias": "LDAP",
        "system": "ldap",
        "frequency": "manually",
        "command": "sync_ldap",
        "params": {
            "ldap_filter": {
                "users": [
                    "user@example.org",
                    "user2@example.org"
                ],
                "groups": [
                    "LDAPGroup",
                    "LDAPGroup3"
                ]
            },
            "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
            "ldap_server": "ldapServer:12345",
            "deactivate_groupless_users": false,
            "deactivate_stale_users": false,
            "user_schema": {
                "first_name": "gn",
                "last_name": "sn",
                "email": "mail",
                "full_name": "cn"
            },
            "bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
            "bind_password": "qweASD123",
            "base_dn": "dc=example,dc=org",
            "group_mapping": {
                "ldap_group2": "G2",
                "ldap_group1": "G1"
            },
            "ldap_start_tls": false,
            "ldap_validate_cert": true
        },
        "inaccessible": true
    }]
}

Returns a list of all LDAP integration connections in the current organization.

Note, this is different from the LDAP connection configured for Single Sign-On.

GET /api/v2/connections/ldap/

Include Parameters

GET /api/v2/connections/ldap/?include=last_job HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 15,
        "alias": "LDAP",
        "system": "ldap",
        "frequency": "manually",
        "command": "sync_ldap",
        "params": {
            "ldap_filter": {
                "users": [
                    "user@example.org",
                    "user2@example.org"
                ],
                "groups": [
                    "LDAPGroup",
                    "LDAPGroup3"
                ]
            },
            "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
            "ldap_server": "ldapServer:12345",
            "deactivate_groupless_users": false,
            "deactivate_stale_users": false,
            "user_schema": {
                "first_name": "gn",
                "last_name": "sn",
                "email": "mail",
                "full_name": "cn"
            },
            "bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
            "bind_password": "qweASD123",
            "base_dn": "dc=example,dc=org",
            "group_mapping": {
                "ldap_group2": "G2",
                "ldap_group1": "G1"
            },
            "ldap_start_tls": false,
            "ldap_validate_cert": true
        },
        "inaccessible": true,
        "last_job": {
            "succeeded": false,
            "last_run": "2016-12-15T22:45:27.412Z",
            "result_message": "Error Message",
            "user": 1,
            "ready": true,
            "automatic": false,
            "id": 4
        }
    }]
}

See the Include Parameters section for more details.

Parameter Description
last_job Include the details of the last job executed for this connection.

Create an LDAP Connection

POST /api/v2/connections/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "alias": "LDAP",
    "params": {
        "ldap_server": "ldapServer:12345",
        "group_mapping": {
            "ldap_group1": "G1",
            "ldap_group2": "G2"
        },
        "ldap_filter": {
            "groups": ["LDAPGroup", "LDAPGroup3"],
            "users": ["user@example.org", "user2@example.org"]
        },
        "user_schema": {
            "first_name": "gn",
            "last_name": "sn",
            "full_name": "cn",
            "email": "mail"
        },
        "deactivate_groupless_users": false,
        "deactivate_stale_users": false,
        "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
        "bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
        "base_dn": "dc=example,dc=org",
        "bind_password": "pass",
        "ldap_start_tls": true
    }
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 15,
    "alias": "LDAP",
    "system": "ldap",
    "frequency": "manually",
    "command": "sync_ldap",
    "params": {
        "ldap_filter": {
            "users": [
                "user@example.org",
                "user2@example.org"
            ],
            "groups": [
                "LDAPGroup",
                "LDAPGroup3"
            ]
        },
        "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
        "ldap_server": "ldapServer:12345",
        "deactivate_groupless_users": false,
        "deactivate_stale_users": false,
        "user_schema": {
            "first_name": "gn",
            "last_name": "sn",
            "email": "mail",
            "full_name": "cn"
        },
        "bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
        "base_dn": "dc=example,dc=org",
        "group_mapping": {
            "ldap_group2": "G2",
            "ldap_group1": "G1"
        },
        "ldap_start_tls": true,
        "ldap_validate_cert": true
    },
    "inaccessible": false
}
Fields Required Description
alias Yes The name of the new connection.
frequency No The frequency in which this connection will sync. The available options are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually".
params Yes A dictionary containing connections options. Please refer to the table below
inaccessible No Is the connection inaccessible from the SDE server. Defaults to false.

Params fields

Fields Required Description
ldap_server Yes The address of the LDAP server.
ldap_start_tls No Determines whether or not to secure connection using TLS/SSL (defaults to True).
group_mapping Yes Object that maps LDAP group names to SDE group ids.
ldap_filter No Fine-grained control for users and groups during synchronization
ldap_validate_cert No Determines whether or not to validate the SSL certificate for the LDAP server (defaults to True).
user_schema No Define a custom user schema.
deactivate_groupless_users No Automatically deactivate SDE users that are not assigned to any groups (defaults to False).
deactivate_stale_users No Automatically deactivate SDE users not found in LDAP (defaults to False).
bind_dn Yes The bind dn
bind_password Yes The bind password
page_size No Number of users to return per page. (defaults to 1000)
group_member_query No Gives the users of the specified group
group_base_dn Yes Base DN of the LDAP groups to sync
base_dn No The base dn (will be computed from bind_dn if unspecified)

Delete an LDAP Connection

DELETE /api/v2/connections/ldap/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 204 NO Content

This endpoint deletes a single LDAP Connection resource, as specified by the id parameter.

DELETE /api/v2/connections/ldap/{connection_id}/

URL Parameters

Parameter Description
connection_id The id of the LDAP Connection to delete.

Update a specific LDAP Connection

PUT /api/v2/connections/ldap/31/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
  "alias": "Example Connection Updated Name",
  "frequency": "daily",
  "params": {
    "ldap_filter": {
      "users": [
        "user@example.org",
        "user2@example.org"
      ],
      "groups": [
        "LDAPGroup",
        "LDAPGroup3"
      ]
    },
    "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
    "ldap_server": "ldapServer:12345",
    "bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
    "user_schema": {
      "first_name": "gn",
      "last_name": "sn",
      "email": "mail",
      "full_name": "cn"
    },
    "deactivate_groupless_users": false,
    "deactivate_stale_users": false,
    "group_member_query": "(&(objectClass=user)(memberOf=%s))",
    "page_size": 1000,
    "bind_password": "pass",
    "base_dn": "dc=example,dc=org",
    "group_mapping": {
      "group": "G1"
    },
    "ldap_start_tls": true,
    "ldap_validate_cert": true
  }
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 31,
  "alias": "Example Connection Updated Name",
  "system": "LDAP",
  "frequency": "daily",
  "command": "sync_ldap",
  "params": {
    "ldap_filter": {
      "users": [
        "user@example.org",
        "user2@example.org"
      ],
      "groups": [
        "LDAPGroup",
        "LDAPGroup3"
      ]
    },
    "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
    "ldap_server": "ldapServer:12345",
    "bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
    "user_schema": {
      "first_name": "gn",
      "last_name": "sn",
      "email": "mail",
      "full_name": "cn"
    },
    "deactivate_groupless_users": false,
    "deactivate_stale_users": false,
    "group_member_query": "(&(objectClass=user)(memberOf=%s))",
    "page_size": 1000,
    "base_dn": "dc=example,dc=org",
    "group_mapping": {
      "group": "G1"
    },
    "ldap_start_tls": true,
    "ldap_validate_cert": true
  },
  "inaccessible": false
}

Update a specific LDAP Connection resource.

PUT /api/v2/connections/ldap/{connection_id}/

URL Parameters

Parameter Description
connection_id The ID of the LDAP Connection to update
Fields Required Description
alias Yes The name of the new connection.
frequency No The frequency in which this connection will sync. The available options are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually".
params Yes A dictionary containing connections options. Please refer to the table below
inaccessible No Is the connection inaccessible from the SDE server. Defaults to false.

Params fields

Fields Required Description
ldap_server Yes The address of the LDAP server.
ldap_start_tls No Determines whether or not to secure connection using TLS/SSL (defaults to True).
group_mapping Yes Object that maps LDAP group names to SDE group ids.
ldap_filter No Fine-grained control for users and groups during synchronization
ldap_validate_cert No Determines whether or not to validate the SSL certificate for the LDAP server (defaults to True).
user_schema No Define a custom user schema.
deactivate_groupless_users No Automatically deactivate SDE users that are not assigned to any groups (defaults to False).
deactivate_stale_users No Automatically deactivate SDE users not found in LDAP (defaults to False).
bind_dn Yes The bind dn
bind_password No The bind password
page_size No Number of users to return per page. (defaults to 1000)
group_member_query No Gives the users of the specified group
group_base_dn Yes Base DN of the LDAP groups to sync
base_dn No The base dn (will be computed from bind_dn if unspecified)

Get All ALM Connections of All Projects

GET /api/v2/connections/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "connector": 2,
        "project": 2,
        "system": "Rally",
        "alias": "Rally Integration",
        "frequency": "manually",
        "command": "sync_rally",
        "params": {
            "sde_project": "Demo Project",
            "alm_user": "rally_user",
            "sde_verification_filter": "none,partial,pass,fail",
            "rally_workspace": "Rally Workspace",
            "alm_method": "https",
            "alm_title_format": "$task_id $title",
            "alm_server": "rally1.rallydev.com",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "alm_project": "Rally Project",
            "alm_pass": "rally_password",
            "alm_phases": "requirements,architecture-design,development",
            "sde_statuses_in_scope": "TODO",
            "conflict_policy": "alm",
            "sde_min_priority": 7
        },
        "inaccessible": false,
    }]
}

Returns a list of all ALM connections associated with all projects. The params are only displayed if you have the 'Edit ALM connections' permission.

GET /api/v2/connections/alm/

Query Parameters

The following parameters may be used to filter the ALM connections resources in the response.

Parameter Description
alias Returns all ALM connections with the specified alias.
frequency Returns all ALM connections with the specified frequency of synchronization.
system Returns all ALM connections associated with a particular system.

Include Parameters

GET /api/v2/connections/alm/?include=last_job HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "connector": 2,
        "project": 2,
        "system": "Rally",
        "alias": "Rally Integration",
        "frequency": "manually",
        "command": "sync_rally",
        "params": {
            "sde_project": "Demo Project",
            "alm_user": "rally_user",
            "sde_verification_filter": "none,partial,pass,fail",
            "rally_workspace": "Rally Workspace",
            "alm_method": "https",
            "alm_title_format": "$task_id $title",
            "alm_server": "rally1.rallydev.com",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "alm_project": "Rally Project",
            "alm_pass": "rally_password",
            "alm_phases": "requirements,architecture-design,development",
            "sde_statuses_in_scope": "TODO",
            "conflict_policy": "alm",
            "sde_min_priority": 7
        },
        "inaccessible": false,
         "last_job": {
            "succeeded": false,
            "last_run": "2016-12-15T22:45:27.412Z",
            "result_message": "Error Message",
            "user": 1,
            "ready": true,
            "automatic": false,
            "id": 4
        }
    }]
}

See the Include Parameters section for more details.

Parameter Description
last_job Include the details of the last job executed for this connection.

Get a Specific ALM Connection

GET /api/v2/connections/alm/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "connector": 2,
    "project": 2,
    "system": "Rally",
    "alias": "Rally Integration",
    "frequency": "manually",
    "command": "sync_rally",
    "params": {
        "sde_project": "Demo Project",
        "alm_user": "rally_user",
        "sde_verification_filter": "none,partial,pass,fail",
        "rally_workspace": "Rally Workspace",
        "alm_method": "https",
        "alm_title_format": "$task_id $title",
        "alm_server": "rally1.rallydev.com",
        "sde_businessunit": "General",
        "sde_application": "Demo Application",
        "alm_project": "Rally Project",
        "alm_pass": "rally_password",
        "alm_phases": "requirements,architecture-design,development",
        "sde_statuses_in_scope": "TODO",
        "conflict_policy": "alm",
        "sde_min_priority": 7
    },
    "inaccessible": false,
}

Returns a specific ALM connection. The params are only displayed if you have the 'Edit ALM connections' permission.

GET /api/v2/connections/alm/{connection_id}/

Create an ALM Connection

POST /api/v2/connections/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "alias": "Example Connection",
    "connector": 1,
    "project": 1,
    "frequency": "hourly",
    "params":{
        "alm_project": "Example Project",
        "alm_parent_issue": "Parent"
    }
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 5,
    "connector": 1,
    "alias": "Example Connection",
    "system": "JIRA",
    "project": 1,
    "frequency": "hourly",
    "command": "sync_jira",
    "params":{
        "sde_project": "Proj 1",
        "alm_user": "Sindy",
        "sde_verification_filter": "none,partial,pass,fail",
        "jira_version": "5",
        "alm_method": "https",
        "alm_title_format": "$task_id $title",
        "alm_server": "bugs.server.co",
        "sde_businessunit": "BU",
        "sde_application": "Finance App",
        "alm_project": "Example Project",
        "alm_pass": "id",
        "alm_phases": "requirements,architecture-design,development",
        "sde_statuses_in_scope": "TODO",
        "conflict_policy": "alm",
        "sde_min_priority": 7,
        "alm_reference_context": 5
    },
    "inaccessible": false
}
Fields Required Description
alias Yes The name of the new connection.
connector Yes The id of the connector that this connection will use to connect with the ALM.
project Yes The id of the SD Elements project that this connection will connect with.
frequency No The frequency in which this connection will sync. The available options for organizations with the advanced ALM feature are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually". Organizations without the advanced ALM feature can only choose "manually".
params Yes A dictionary containing connections options. Please refer to product documentation for more details or reach out to support.

Update a specific ALM Connection

PUT /api/v2/connections/alm/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "alias": "Example Connection Updated Name",
    "connector": 1,
    "project": 1,
    "frequency": "manually",
    "params": {"alm_project": "Project Name"}
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 5,
    "connector": 1,
    "alias": "Example Connection Updated Name",
    "system": "JIRA",
    "project": 1,
    "frequency": "manually",
    "command": "sync_jira",
    "params":{
        "sde_project": "Proj 1",
        "alm_user": "Sindy",
        "sde_verification_filter": "none,partial,pass,fail",
        "jira_version": "5",
        "alm_method": "https",
        "alm_title_format": "$task_id $title",
        "alm_server": "bugs.server.co",
        "sde_businessunit": "BU",
        "sde_application": "Finance App",
        "alm_project": "Project Name",
        "alm_pass": "id",
        "alm_phases": "requirements,architecture-design,development",
        "sde_statuses_in_scope": "TODO",
        "conflict_policy": "alm",
        "sde_min_priority": 7,
        "alm_reference_context": 5
    },
    "inaccessible": false
}

Update a specific ALM Connection resource.

PUT /api/v2/connections/alm/{connection_id}/

URL Parameters

Parameter Description
connection_id The ID of the ALM Connection to update

Get All Analysis Connections of All Projects

GET /api/v2/connections/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "connector": 1,
        "project": 1,
        "system": "WhiteHat",
        "alias": "WhiteHat Integration",
        "frequency": "manually",
        "command": "sync_whitehat",
        "params": {
            "asset_name": "WebGoat Java",
            "sde_project": "WhiteHat",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "import_behaviour": "replace-scanner",
            "analysis_server": "server.whitehatsec.com",
            "task_status_mapping": "{}"
        },
        inaccessible": false
    }]
}

Returns a list of all analysis connections associated with all projects. The params are only displayed if you have the 'Edit security tool connections' permission.

GET /api/v2/connections/analysis/

Query Parameters

The following parameters may be used to filter the analysis connections resources in the response.

Parameter Description
alias Returns all analysis connections with the specified alias.
frequency Returns all analysis connections with the specified frequency of synchronization.
system Returns all analysis connections associated with a particular system.

Include Parameters

GET /api/v2/connections/analysis/?include=last_job HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "connector": 1,
        "project": 1,
        "system": "WhiteHat",
        "alias": "WhiteHat Integration",
        "frequency": "manually",
        "command": "sync_whitehat",
        "params": {
            "asset_name": "WebGoat Java",
            "sde_project": "WhiteHat",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "import_behaviour": "replace-scanner",
            "analysis_server": "server.whitehatsec.com",
            "task_status_mapping": "{}"
        },
        inaccessible": false
         "last_job": {
            "succeeded": false,
            "last_run": "2016-12-15T22:45:27.412Z",
            "result_message": "Error Message",
            "user": 1,
            "ready": true,
            "automatic": false,
            "id": 4
        }
    }]
}

See the Include Parameters section for more details.

Parameter Description
last_job Include the details of the last job executed for this connection.

Get a Specific Analysis Connection

GET /api/v2/connections/analysis/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "connector": 1,
    "project": 1,
    "system": "WhiteHat",
    "alias": "WhiteHat Integration",
    "frequency": "manually",
    "command": "sync_whitehat",
    "params": {
        "asset_name": "WebGoat Java",
        "sde_project": "WhiteHat",
        "sde_businessunit": "General",
        "sde_application": "Demo Application",
        "import_behaviour": "replace-scanner",
        "analysis_server": "server.whitehatsec.com",
        "task_status_mapping": "{}"
    },
    inaccessible": false
}

Returns a specific analysis connection. The params are only displayed if you have the 'Edit security tool connections' permission.

GET /api/v2/connections/analysis/{connection_id}/

Create an Analysis Connection

POST /api/v2/connections/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "alias": "Example Analysis Connection",
    "connector": 2,
    "project": 1,
    "frequency": "daily",
    "params": {
        "task_status_mapping": "{\"pass\": \"DONE\"}",
        "import_behaviour": "combine"
    }
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 9,
    "connector": 2,
    "alias": "Example Analysis Connection",
    "system": "Veracode",
    "project": 1,
    "frequency": "daily",
    "command": "import_veracode",
    "params":{
        "integration_mode": "api",
        "analysis_user": "Code",
        "analysis_pass": "Name",
        "sde_businessunit": "BU",
        "sde_application": "Financial App",
        "sde_project": "Example Project",
        "analysis_server": "vera",
        "task_status_mapping": "{\"pass\": \"DONE\"}",
        "import_behaviour": "combine",
        "analysis_method": "http"
        },
    "inaccessible": false
}

Only remote analysis connections can be created via the api.

Fields Required Description
alias No The name of the new connection. Will default to the name of the connector.
connector Yes The id of the connector that this connection will use to connect with the ALM.
project Yes The id of the SD Elements project that this connection will connect with.
frequency No The frequency in which this connection will sync. The available options for organizations with the advanced ALM feature are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually". Organizations without the advanced ALM feature can only choose "manually".
params Yes A dictionary containing connections options. Please refer to product documentation for more details or reach out to support.

Update a specific Analysis Connection

PUT /api/v2/connections/analysis/2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "alias": "Example Analysis Connection Updated Name",
    "connector": 2,
    "project": 1,
    "frequency": "hourly",
    "params": {}
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 9,
    "connector": 2,
    "alias": "Example Analysis Connection Updated Name",
    "system": "Veracode",
    "project": 1,
    "frequency": "hourly",
    "command": "import_veracode",
    "params":{
        "integration_mode": "api",
        "analysis_user": "Code",
        "analysis_pass": "Name",
        "sde_businessunit": "BU",
        "sde_application": "Financial App",
        "sde_project": "Example Project",
        "analysis_server": "vera",
        "task_status_mapping": "",
        "import_behaviour": "replace-scanner",
        "analysis_method": "http"
        },
    "inaccessible": false
}

Update a specific Analysis Connection resource.

PUT /api/v2/connections/analysis/{connection_id}/

URL Parameters

Parameter Description
connection_id The ID of the Analysis Connection to update

Connectors

Get All ALM Connectors

GET /api/v2/connectors/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "name": "Rally Connector",
        "system": "Rally",
        "inaccessible": false
    }]
}

Returns a list of all ALM connectors available.

GET /api/v2/connectors/alm/

Query Parameters

The following parameters may be used to filter the ALM connectors.

Parameter Description
system Returns all ALM connectors associated with a particular system.

Get a Specific ALM Connector

GET /api/v2/connectors/alm/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "Rally Connector",
    "system": "Rally",
    "inaccessible": false
}

Returns a specific ALM connector.

GET /api/v2/connectors/alm/{id}

Get All Analysis Connectors

GET /api/v2/connectors/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "name": "Fortify Connector",
        "system": "Fortify",
        "inaccessible": false
    }]
}

Returns a list of all analysis connectors available.

GET /api/v2/connectors/analysis/

Query Parameters

The following parameters may be used to filter the analysis connectors.

Parameter Description
system Returns all analysis connectors associated with a particular system.

Get a Specific Analysis Connector

GET /api/v2/connectors/analysis/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "Fortify Connector",
    "system": "Fortify",
    "inaccessible": false
}

Returns a specific analysis connector.

GET /api/v2/connectors/analysis/{id}

Global Roles

Get All Global Roles

GET /api/v2/global-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": "UR4",
            "name": "Administrator",
            "description": "An administrator can create new..."
        },
        {
            "id": "UR5",
            "name": "No Role",
            "description": "This role confers no permissions."
        },
        {
            "id": "UR2",
            "name": "Project Lead",
            "description": "A project lead has permission to..."
        },
        {
            "id": "UR1",
            "name": "User",
            "description": "A regular SD Elements user has..."
        }
    ]
}

This endpoint returns a list of Global Role resources.

Get a Specific Global Role

GET /api/v2/global-roles/UR4/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "UR4",
    "name": "Administrator",
    "description": "An administrator can create new..."
}

This endpoint returns a specific Global Role resource as specified by the id parameter.

GET /api/v2/global-roles/{global_role_id}/

URL Parameters

Parameter Description
global_role_id The id of the Global Role to retrieve

Create a New Global Role

POST /api/v2/global-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "Global Role",
    "description": "Can participate in projects.",
    "inherit_from": "UR1"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": "CUR1",
    "name": "Global Role",
    "description": "Can participate in projects.",
    "permissions": [
        "modify_self"
    ],
    "is_default": false
}
POST /api/v2/global-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "New Global Role",
    "description": "Can create new applications and projects.",
    "permissions": [
        "add_project",
        "add_application"
    ],
    "is_default": true
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": "CUR2",
    "name": "New Global Role",
    "description": "Can create new applications and projects.",
    "permissions": [
        "add_project",
        "add_application"
    ],
    "is_default": true
}
Fields Required Description
name Yes The name of the Global Role.
description Yes A description of the Global Role.
permissions No The permissions given to users who are assigned this Global Role.
inherit_from No If inherit_from field is passed, then the permissions field gets set with the permissions of the parent Global Role.
is_default No Passing is_default as True will set the newly created Global Role as default role for the current organization.

Update a Global Role

PATCH /api/v2/global-roles/CUR2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "permissions": [
        "archive_application",
        "add_project",
        "add_application"
    ],
    "is_default": true
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "CUR2",
    "name": "New Global Role",
    "description": "Can create new applications and projects.",
    "permissions": [
        "archive_application",
        "add_project",
        "add_application"
    ],
    "is_default": true
}

PATCH /api/v2/global-roles/{global_role_id}/

URL Parameters

Parameter Description
global_role_id The id of the Global Role to update

Payload

Fields Required Description
name No The name of the Global Role.
description No Global Role description.
permissions No The permissions given to users who are assigned this Global Role.
is_default No Passing is_default as True will set the Global Role as default role for the current organization.

Delete a Global Role

DELETE /api/v2/global-roles/CUR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "replacement": "UR1"
}
HTTP/1.1 204 NO CONTENT

DELETE /api/v2/global-roles/{global_role_id}/

URL Parameters

Parameter Description
global_role_id The id of the Global Role to delete

Payload

Fields Required Description
replacement Yes The id of the Global Role to replace the one to be deleted.

Glossary Terms

Get all Glossary Terms

GET /api/v2/glossary-terms/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": "G2",
            "title": "Use Notification",
            "text": "<p>This is a type of notification or message that basically describes...</p>",
            "summary": "<p>A message that notifies the users of their actions.</p>",
            "created": "2015-03-26T19:50:46.348000Z",
            "updated": "2015-03-26T19:50:46.348000Z"
        },
        {
            "id": "G3",
            "title": "Unauthenticated part of application",
            "text": "<p>An unauthenticated (or authentication-free) part of an application consists...</p>",
            "summary": "<p>An unauthenticated (or authentication-free) part of an application is a public portion of an application.</p>",
            "created": "2015-03-26T19:52:34.854000Z",
            "updated": "2015-03-26T19:52:34.853000Z"
        }
    ]
}

This endpoint returns a list of Glossary Term resources.

Get a Specific Glossary Term

GET /api/v2/glossary-terms/G2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "G2",
    "title": "Use Notification",
    "text": "<p>This is a type of notification or message that basically describes...</p>",
    "summary": "<p>A message that notifies the users of their actions.</p>",
    "created": "2015-03-26T19:50:46.348000Z",
    "updated": "2015-03-26T19:50:46.348000Z"
}

This endpoint returns a specific Glossary Term resource.

GET /api/v2/glossary-terms/{glossary_term_id}/

URL Parameters

Parameter Description
glossary_term_id The id of the Glossary Term to retrieve

Create a New Glossary Term

POST /api/v2/glossary-terms/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "title": "New Glossary Term",
    "text": "Full description of the term goes here.",
    "summary": "The summary of the glossary term goes here."
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": "CG13",
    "title": "New Glossary Term",
    "text": "<p>This is the new glossary term for our API documentation example<p>",
    "summary": "<p>Example POST glossary Term<p>",
    "created": "2015-06-23T19:05:46.175048Z",
    "updated": "2015-06-23T19:05:46.107520Z"
}

This endpoint creates a new Glossary Term resource.

Fields Required Description
text Yes
title Yes
summary Yes

Groups

Get All Groups

GET /api/v2/groups/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "G64",
        "name": "Group 64",
        "updated": "2016-07-29T21:02:33.764620Z",
        "description": "Group description",
        "role": "UR4"
    }]
}

This endpoint returns a list of Group resources.

GET /api/v2/groups/

Expand Parameters

GET /api/v2/groups/?expand=role
Accept: application/json
Authorization: Token: "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "G64",
        "name": "Group 64",
        "updated": "2016-07-29T21:02:19.780768Z",
        "description": "Group description",
        "role": {
            "id": "UR1",
            "name": "User"
        }
    }]
}

See the Expand Parameters section for more details.

Parameter Description
role Role field is expanded to include to id and name fields.

Include Parameters

GET /api/v2/groups/?include=groups,users,all_users,total_user_count
Accept: application/json
Authorization: Token: "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "G64",
        "name": "Group 64",
        "updated": "2016-07-29T21:02:19.780768Z",
        "description": "Group description",
        "role": "UR4"
        "users": [{
            "first_name": "Frank",
            "last_name": "Testerton",
            "is_active": true,
            "id": 2,
            "email": "frank@example.com",
            "role": {
                    "id": "UR1",
                    "name": "User"
            }
        }],
        "groups": [{
            role: "User",
            id: "G1",
            name: "Example Group"
        }],
        "total_user_count": 2,
        "all_users": "users": [
            {
                "first_name": "Frank",
                "last_name": "Testerton",
                "is_active": true,
                "id": 2,
                "email": "frank@example.com",
                "role": {
                    "id": "UR1",
                    "name": "User"
                }
            },
            {
                "first_name": "Linda",
                "last_name": "Graham",
                "is_active": false,
                "id": 3,
                "email": "linda@example.com",
                "role": {
                    "id": "UR1",
                    "name": "User"
                }
            },

        ]
        "sync_connections": ["LDAP Connection"]
    }]
}

See the Include Parameters section for more details.

Parameter Description
groups Includes a list of nested groups that are directly a member of the parent group
users Includes a list of direct users a part of the group.
all_users Include a list of direct and indirect users of the group.
total_user_count Includes the total number of users (direct and indirect) in the group.
sync_connections Includes a list of Sync Connections that include the group in their mappings

Get a Specific Group

GET /api/v2/groups/G64/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "G64",
    "name": "Group 64",
    "updated": "2016-07-29T21:02:19.780768Z",
    "description": "Group description",
    "role": "UR4",
}

This endpoint retreives a specific Group Resource as specified by the group_id.

GET /api/v2/groups/{group_id}/

URL Parameters

Parameter Description
group_id The id of the Group to retrieve

Create a Group

POST /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "Group 2",
    "role": "UR5",
    "users": [{"email": "frank@example.com"}],
    "groups": ["G1"]
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": "G2",
    "name": "Group 2",
    "updated": "2016-07-29T21:02:19.780768Z",
    "description": "",
    "role": "UR5",
    "users": [{
        "first_name": "Frank",
        "last_name": "Testerton",
        "is_active": true,
        "id": 2,
        "email": "frank@example.com",
        "role": {
            "id": "UR1",
            "name": "User"
        }
    }],
    "groups": [{
        "role": "User",
        "id": "G1",
        "name": "Example Group"
    }]
}

Create a Group resource.

POST /api/v2/groups/

Fields Required Description
name Yes The name of the group resource
description No The description of the group
role Yes The role of the group
users No A list of dictionaries representing the users who are part of the business unit. Each dictionary has an email field.
groups No A list of group ids representing the nested groups who are part of the parent group.

Update a specific Group

PUT /api/v2/groups/G2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "User Experience Group",
    "description": "Deals with designing user experiences"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "G2",
    "name": "User Experience Group",
    "updated": "2016-07-29T21:02:19.780768Z",
    "description": "Deals with designing user experiences",
    "role": "UR1"
    "users": [{
        "first_name": "Frank",
        "last_name": "Testerton",
        "is_active": true
        "id": 2,
        "email": "frank@example.com",
        "role": {
            "id": "UR1",
            "name": "User"
        }
    }],
    "groups": [{
        "role": "User"
        "id": "G1",
        "name": "Example Group"
    }]
}

Update a specific Group resource.

PUT /api/v2/users/{group_id}/

URL Parameters

Parameter Description
group_id The ID of the Group to update

Delete a Group

DELETE api/v2/groups/G1/
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT

This endpoint deletes a single Group resource, as specified by the id parameter.

DELETE /groups/{group_id}/

Parameter Description
group_id The id of the group to delete

Jobs

Get All ALM Jobs of All Projects

GET /api/v2/jobs/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 12,
        "user": "admin@example.com",
        "succeeded": true,
        "automatic": true,
        "ready": true,
        "result_message": "",
        "last_run": "2015-04-15T20:27:24.396442Z",
        "connection": {
            "alias": "My Connection",
            "command": "run_my_connection",
            "frequency": "daily",
            "id": 23,
            "params": {
                "sde_project": "Demo Project",
                "alm_user": "rally_user",
                "sde_verification_filter": "none,partial,pass,fail",
                "rally_workspace": "Rally Workspace",
                "alm_method": "https",
                "alm_title_format": "$task_id $title",
                "alm_server": "rally1.rallydev.com",
                "sde_businessunit": "General",
                "sde_application": "Demo Application",
                "alm_project": "Rally Project",
                "alm_pass": "rally_password",
                "alm_phases": "requirements,architecture-design,development",
                "sde_statuses_in_scope": "TODO",
                "conflict_policy": "alm",
                "sde_min_priority": 7
            },
            "project": 7,
            "system": "Rally"
        }
    }]
}

Returns a list of all alm jobs associated with all projects. Note that the params are only shown if you have 'Edit ALM connections' permission.

GET /api/v2/jobs/alm/

Query Parameters

The following parameters may be used to filter the ALM connections resources in the response.

Parameter Description
automatic Returns all ALM jobs that were created automatically.
connection Returns all ALM jobs that correspond to a specific connection.
ready Returns all ALM jobs that have finished running, successfully or otherwise.
succeeded Returns all ALM jobs that completed successfully.
user Returns all ALM jobs created by the specified user.

Get a Specific ALM Job

GET /api/v2/jobs/alm/{job_id} HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 12,
    "user": "admin@example.com",
    "succeeded": true,
    "automatic": true,
    "ready": true,
    "result_message": "",
    "last_run": "2015-04-15T20:27:24.396442Z",
    "connection": {
        "alias": "My Connection",
        "command": "run_my_connection",
        "frequency": "daily",
        "id": 23,
        "params": {
            "sde_project": "Demo Project",
            "alm_user": "rally_user",
            "sde_verification_filter": "none,partial,pass,fail",
            "rally_workspace": "Rally Workspace",
            "alm_method": "https",
            "alm_title_format": "$task_id $title",
            "alm_server": "rally1.rallydev.com",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "alm_project": "Rally Project",
            "alm_pass": "rally_password",
            "alm_phases": "requirements,architecture-design,development",
            "sde_statuses_in_scope": "TODO",
            "conflict_policy": "alm",
            "sde_min_priority": 7
        },
        "project": 7,
        "system": "Rally"
    }
}

Returns a specific alm job. Note that the params are only shown if you have 'Edit ALM connections' permission.

GET /api/v2/jobs/alm/{job_id}

Post Results of an ALM Job of a Project

POST /api/v2/projects/1/jobs/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "connection": 12,
    "result_message": "My Message",
    "succeeded": true,
    "automatic": true
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 12,
    "user": "admin@example.com",
    "succeeded": true,
    "automatic": true,
    "ready": true,
    "result_message": "My Message",
    "last_run": "2015-04-15T20:27:24.396442Z",
    "connection": {
        "alias": "My Connection",
        "command": "run_my_connection",
        "frequency": "daily",
        "id": 12,
        "params": {
            "sde_project": "Demo Project",
            "alm_user": "rally_user",
            "sde_verification_filter": "none,partial,pass,fail",
            "rally_workspace": "Rally Workspace",
            "alm_method": "https",
            "alm_title_format": "$task_id $title",
            "alm_server": "rally1.rallydev.com",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "alm_project": "Rally Project",
            "alm_pass": "rally_password",
            "alm_phases": "requirements,architecture-design,development",
            "sde_statuses_in_scope": "TODO",
            "conflict_policy": "alm",
            "sde_min_priority": 7
        },
        "project": 7,
        "system": "Rally"
    }
}

Will submit the results of an ALM job.

POST /api/v2/jobs/alm/

Fields Required Description
automatic Yes Whether the job was run automatically.
connection Yes The connection id associated with the job.
result_message Yes The result message of the job.
succeeded Yes Whether the job was run successfully.

Initiate an ALM Connection Sync Job

POST /api/v2/projects/1/jobs/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "connection": 12,
    "automatic": false,
    "ready": false
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{

    "id": 12,
    "user": "admin@example.com",
    "succeeded": false,
    "automatic": false,
    "ready": false,
    "result_message": "",
    "last_run": "2015-04-15T20:27:24.396442Z",
    "connection": {
        "alias": "My Connection",
        "command": "run_my_connection",
        "frequency": "daily",
        "id": 12,
        "params": {
            "sde_project": "Demo Project",
            "alm_user": "rally_user",
            "sde_verification_filter": "none,partial,pass,fail",
            "rally_workspace": "Rally Workspace",
            "alm_method": "https",
            "alm_title_format": "$task_id $title",
            "alm_server": "rally1.rallydev.com",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "alm_project": "Rally Project",
            "alm_pass": "rally_password",
            "alm_phases": "requirements,architecture-design,development",
            "sde_statuses_in_scope": "TODO",
            "conflict_policy": "alm",
            "sde_min_priority": 7
        },
        "project": 7,
        "system": "Rally"
    }
}

Will add a sync job to the queue to be run.

POST /api/v2/jobs/alm/

Fields Required Description
automatic Yes Whether the job was run automatically.
connection Yes The connection id associated with the job.
ready Yes Whether the job is ready to post its result or not. This field must be set to "false" in order for the import to commence.
succeeded No Boolean Field. Use this along with the 'ready: true' to record when a job was successful/unsuccessful.

Get All Analysis Jobs for All Projects

GET /api/v2/jobs/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 12,
        "user": "admin@example.com",
        "succeeded": true,
        "automatic": true,
        "ready": true,
        "result_message": "",
        "last_run": "2015-04-15T20:27:24.396442Z",
        "connection": {
            "alias": "My Connection",
            "command": "run_my_connection",
            "frequency": "daily",
            "id": 23,
            "params": {
                "asset_name": "WebGoat Java",
                "sde_project": "WhiteHat",
                "sde_businessunit": "General",
                "sde_application": "Demo Application",
                "import_behaviour": "replace-scanner",
                "analysis_server": "server.whitehatsec.com",
                "task_status_mapping": "{}"
            },
            "project": 7,
            "system": "Whitehat"
        }
    }]
}

Returns a list of all analysis jobs associated with all projects. Note that the params are only shown if you have 'Edit security tool connections' permission.

GET /api/v2/jobs/analysis/

Query Parameters

The following parameters may be used to filter the analysis connections resources in the response.

Parameter Description
automatic Returns all Analysis jobs that were created automatically.
connection Returns all Analysis jobs that correspond to a specific connection.
ready Returns all Analysis jobs that have finished running, successfully or otherwise.
succeeded Returns all Analysis jobs that completed successfully.
user Returns all Analysis jobs created by the specified user.

Get a Specific Analysis Job

GET /api/v2/jobs/analysis/{job_id} HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 12,
    "user": "admin@example.com",
    "succeeded": true,
    "automatic": true,
    "ready": true,
    "result_message": "",
    "last_run": "2015-04-15T20:27:24.396442Z",
    "connection": {
        "alias": "My Connection",
        "command": "run_my_connection",
        "frequency": "daily",
        "id": 23,
        "params": {
            "asset_name": "WebGoat Java",
            "sde_project": "WhiteHat",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "import_behaviour": "replace-scanner",
            "analysis_server": "server.whitehatsec.com",
            "task_status_mapping": "{}"
        },
        "project": 7,
        "system": "Whitehat"
    }
}

Returns a specific analysis job. Note that the params are only shown if you have 'Edit security tool connections' permission.

GET /api/v2/jobs/analysis/{job_id}

Post Results of an Analysis Job of a Project

POST /api/v2/projects/1/jobs/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "connection": 12,
    "result_message": "My Message",
    "succeeded": true,
    "automatic": true
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 12,
    "user": "admin@example.com",
    "succeeded": true,
    "automatic": true,
    "ready": true,
    "result_message": "My Message",
    "last_run": "2015-04-15T20:27:24.396442Z",
    "connection": {
        "alias": "My Connection",
        "command": "run_my_connection",
        "frequency": "daily",
        "id": 23,
        "params": {
            "asset_name": "WebGoat Java",
            "sde_project": "WhiteHat",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "import_behaviour": "replace-scanner",
            "analysis_server": "server.whitehatsec.com",
            "task_status_mapping": "{}"
        },
        "project": 7,
        "system": "Whitehat"
    }
}

Will submit the results of an analysis job.

POST /api/v2/jobs/analysis/

Fields Required Description
automatic Yes Whether the job was run automatically.
connection Yes The connection id associated with the job.
result_message Yes The result message of the job.
succeeded Yes Whether the job was run successfully.
ready No Whether the job is ready to post the result or not. Defaults to True.

Initiate an Analysis Connection Import Job

POST /api/v2/projects/1/jobs/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "connection": 12,
    "automatic": false,
    "ready": false
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 12,
    "user": "admin@example.com",
    "succeeded": false,
    "automatic": false,
    "ready": false,
    "result_message": "",
    "last_run": "2015-04-15T20:27:24.396442Z",
    "connection": {
        "alias": "My Connection",
        "command": "run_my_connection",
        "frequency": "daily",
        "id": 23,
        "params": {
            "asset_name": "WebGoat Java",
            "sde_project": "WhiteHat",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "import_behaviour": "replace-scanner",
            "analysis_server": "server.whitehatsec.com",
            "task_status_mapping": "{}"
        },
        "project": 7,
        "system": "Whitehat"
    }
}

Will put the import job on the queue to be run.

POST /api/v2/jobs/analysis/

Fields Required Description
automatic Yes Whether the job was run automatically.
connection Yes The connection id associated with the job.
ready Yes Whether the job is ready to post its result or not. This field must be set to "false" in order for the import to commence.
succeeded No Boolean Field. Use this along with the 'ready: true' to record when a job was successful/unsuccessful.

Get All LDAP Jobs

GET /api/v2/jobs/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "automatic": false,
        "connection": {
            "id": 29,
            "alias": "gg'",
            "system": "LDAP",
            "frequency": "manually",
            "command": "sync_ldap",
            "params": {
                "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
                "ldap_server": "geneva.labs.sdelements.com:389",
                "bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
                "user_schema": {
                    "first_name": "gn",
                    "last_name": "sn",
                    "email": "mail",
                    "full_name": "cn"
                },
                "deactivation": false,
                "group_member_query": "(&(objectClass=user)(memberOf=%s))",
                "page_size": 666,
                "base_dn": "DC=labs,DC=sdelements,DC=com",
                "group_mapping": {
                    "mathematicians": "group2",
                    "analyst": "group3",
                    "scientists": "group1"
                },
                "ldap_method": "LDAP",
                "ldap_validate_cert": true
            },
            "inaccessible": false
        },
        "id": 57,
        "last_run": "2017-01-05T18:38:42.604983Z",
        "ready": true,
        "result_message": "",
        "succeeded": true,
        "user": "admin@example.com" 
    }]
}

Returns a list of all LDAP jobs. Note that the params are only shown if you have 'Edit security tool connections' permission.

GET /api/v2/jobs/ldap/

Query Parameters

The following parameters may be used to filter the analysis connections resources in the response.

Parameter Type Description
automatic Boolean Returns all LDAP jobs that were created automatically.
connection Integer Returns all LDAP jobs that correspond to a specific connection.
ready Boolean Returns all LDAP jobs that have finished running, successfully or otherwise.
succeeded Boolean Returns all LDAP jobs that completed successfully.
user E-mail Returns all LDAP jobs created by the specified user.

Get a Specific LDAP Job

GET /api/v2/jobs/ldap/{job_id} HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "automatic": false,
    "connection": {
        "id": 29,
        "alias": "gg'",
        "system": "LDAP",
        "frequency": "manually",
        "command": "sync_ldap",
        "params": {
            "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
            "ldap_server": "geneva.labs.sdelements.com:389",
            "bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
            "user_schema": {
                "first_name": "gn",
                "last_name": "sn",
                "email": "mail",
                "full_name": "cn"
            },
            "deactivation": false,
            "group_member_query": "(&(objectClass=user)(memberOf=%s))",
            "page_size": 666,
            "base_dn": "DC=labs,DC=sdelements,DC=com",
            "group_mapping": {
                "mathematicians": "group2",
                "analyst": "group3",
                "scientists": "group1"
            },
            "ldap_method": "LDAP",
            "ldap_validate_cert": true
        },
        "inaccessible": false
    },
    "id": 57,
    "last_run": "2017-01-05T18:38:42.604983Z",
    "ready": true,
    "result_message": "",
    "succeeded": true,
    "user": 1
}

Returns a specific LDAP job. Note that the params are only shown if you have 'Edit security tool connections' permission.

GET /api/v2/jobs/ldap/{job_id}

Post Results of an LDAP Job

POST /api/v2/jobs/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "connection": 29,
    "result_message": "My Message",
    "succeeded": true,
    "automatic": true
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "automatic": false,
    "connection": {
        "id": 29,
        "alias": "gg'",
        "system": "LDAP",
        "frequency": "manually",
        "command": "sync_ldap",
        "params": {
            "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
            "ldap_server": "geneva.labs.sdelements.com:389",
            "bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
            "user_schema": {
                "first_name": "gn",
                "last_name": "sn",
                "email": "mail",
                "full_name": "cn"
            },
            "deactivation": false,
            "group_member_query": "(&(objectClass=user)(memberOf=%s))",
            "page_size": 666,
            "base_dn": "DC=labs,DC=sdelements,DC=com",
            "group_mapping": {
                "mathematicians": "group2",
                "analyst": "group3",
                "scientists": "group1"
            },
            "ldap_method": "LDAP",
            "ldap_validate_cert": true
        },
        "inaccessible": false
    },
    "id": 57,
    "last_run": "2017-01-05T18:38:42.604983Z",
    "ready": true,
    "result_message": "My Message",
    "succeeded": true,
    "user": 1
}

Will submit the results of an LDAP job.

POST /api/v2/jobs/LDAP/

Fields Required Type Description
automatic Yes Boolean Whether the job was run automatically.
connection Yes Integer The connection id associated with the job.
result_message Yes String The result message of the job.
succeeded Yes Boolean Whether the job was run successfully.
ready No Boolean Whether the job is ready to post the result or not. Defaults to True.

Initiate an LDAP Connection Import Job

POST /api/v2/jobs/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "connection": 29,
    "automatic": false,
    "ready": false
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "automatic": false,
    "connection": {
        "id": 29,
        "alias": "gg'",
        "system": "LDAP",
        "frequency": "manually",
        "command": "sync_ldap",
        "params": {
            "group_base_dn": "OU=SyncGroups,DC=example,DC=com",
            "ldap_server": "geneva.labs.sdelements.com:389",
            "bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
            "user_schema": {
                "first_name": "gn",
                "last_name": "sn",
                "email": "mail",
                "full_name": "cn"
            },
            "deactivation": false,
            "group_member_query": "(&(objectClass=user)(memberOf=%s))",
            "page_size": 666,
            "base_dn": "DC=labs,DC=sdelements,DC=com",
            "group_mapping": {
                "mathematicians": "group2",
                "analyst": "group3",
                "scientists": "group1"
            },
            "ldap_method": "LDAP",
            "ldap_validate_cert": true
        },
        "inaccessible": false
    },
    "id": 57,
    "last_run": "2017-01-05T18:38:42.604983Z",
    "ready": true,
    "result_message": "",
    "succeeded": true,
    "user": "admin@example.com" 
}

Will put the import job on the queue to be run.

POST /api/v2/jobs/ldap/

Fields Required Type Description
automatic Yes Boolean Whether the job was run automatically.
connection Yes Integer The connection id associated with the job.
ready Yes Boolean Whether the job is ready to post its result or not. This field must be set to "false" in order for the import to commence.
succeeded No Boolean Use this along with the 'ready: true' to record when a job was successful/unsuccessful.

Library Tasks

Get All Library Tasks

GET /api/v2/library/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "priority": 8,
        "url": "http://example.com/library/tasks/T179/",
        "problem": "P1",
        "title": "Allow access for users to remove their data from the system",
        "text": "Some example description",
        "phase": "X1",
        "id": "T179"
    }]
}

This endpoint retrieves a list of Library Task resources.

GET /api/v2/library/tasks/

Query Parameters

The following parameters may be used to filter the library task resources in the response.

Parameter Description
priority Given a priority 0-10, returns all tasks with specified priority

Expand Parameters

GET /api/v2/library/tasks/?expand=problem HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "priority": 8,
        "tags": [],
        "url": "http://example.com/library/tasks/T179/",
        "problem": {
            "text": "This is some example content.",
            "cwe": [{
                "url": "http://cwe.mitre.org/data/definitions/359",
                "title": "Exposure of Private Information ('Privacy Violation')",
                "cwe_id": 359
            }],
            "id": "P257",
            "title": "P257: Privacy Violation"
        },
        "title": "Allow access for users to remove their data from the system",
        "text": "Some example description",
        "phase": "X1",
        "id": "T179"
    }]
}

See the Expand Parameters section for more details.

Parameter Description
problem Expands the problem fields in the task response object

Include Parameters

GET /api/v2/library/tasks/?include=verification_coverage,categories,tags,how_tos,amendments HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "priority": 8,
        "tags": [1, 2, 3],
        "url": "http://example.com/library/tasks/T179/",
        "problem": "P1",
        "title": "Allow access for users to remove their data from the system",
        "text": "Some example description",
        "phase": "X1",
        "id": "T179",
        "categories": [
            "Authorization"
        ],
        "amendments": [{
            "id": "TA123",
            "title": "TA123",
            "text": "Some additional information about this task..."
        }],
        "verification_coverage": [
            "No Automated Static Analysis Coverage"
        ],
        "how_tos": [{
            "id": "I131",
            "title": "I131: Manually with browser",
            "slug": "test-account-lockout-manually-browser",
            "url": "http://a7069ccda519b00c4/....",
            "text": "1. Open your web browser ..."
        }]
    }]
}

See the Include Parameters section for more details.

Parameter Description
amendments Includes a list of amendments on each task
categories Includes a list of categories that apply to each task
how_tos Includes a list of How-Tos for each task. These are language specific examples of how to implement the task
tags Includes a list of tags attached to each task
verification_coverage Includes a list of verification coverages of each task

Get a Specific Library Task

GET /api/v2/library/tasks/T3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "priority": 8,
        "tags": [],
        "url": "http://example.com/library/tasks/T3/",
        "problem": "P1",
        "title": "Example Library Task",
        "text": "Some example description",
        "phase": "X1",
        "id": "T3"
    }]
}

This endpoint retrieves a single library task resource, as specified by the id parameter.

GET /api/v2/library/task/{task_id}/

URL Parameters

Parameter Description
task_id The id of the task to retrieve

All of the expand and include parameters for the 'Get All Library Tasks' endpoint apply here as well.

Library Problems

Get All Library Problems

GET /api/v2/library/problems/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "text": "This is some example description.", 
        "cwes": [359],
        "id": "P257", 
        "title": "Privacy Violation",
        "risk_rating": 5
    }]
}

This endpoint retrieves a list of Library Problem resources.

GET /api/v2/library/problems/

Query Parameters

The following parameters may be used to filter the library problem resources in the response.

Parameter Description
risk_rating Given a risk rating 0-10, returns all problems with specified rating

Include Parameters

GET /api/v2/library/problems/?include=related_tasks,category,cwe HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "P257",
        "title": "Privacy Violation",
        "text": "This is some example description.", 
        "risk_rating": 5,
        "category": "XML and Web Services",
        "cwe": [{
            "url": "http://cwe.mitre.org/data/definitions/359", 
            "title": "Exposure of Private Information ('Privacy Violation')", 
            "id": 359
        }], 
        "related_tasks": [{
                "id": "CT1",
                "title": "Example Task 1",
                "priority": 10,
                "text": "Example task solution",
                "phase": "X1"
        }]
    }]
}

See the Include Parameters section for more details.

Parameter Description
category Includes the category that applies to each problem
cwe Includes the list of CWEs that apply to each problem
related_tasks Includes a list of tasks that relate to each problem

Get a Specific Library Problem

GET /api/v2/library/problems/P3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "text": "This is some example description.", 
        "id": "P3", 
        "title": "Example Library Problem",
        "risk_rating": 5
    }]
}

This endpoint retrieves a single library problem resource, as specified by the id parameter.

GET /api/v2/library/problems/{problem_id}/

URL Parameters

Parameter Description
problem_id The id of the problem to retrieve

All of the expand and include parameters for the 'Get All Library Problems' endpoint apply here as well.

Phases

Get All Phases

GET /api/v2/phases/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": "X1",
            "description": "Application security requirements, generally used to assist requirements analysts.",
            "name": "Requirements",
            "slug": "requirements",
            "tip": "One-time tasks that you can verify. Similar to traditional functional requirements or user stories.",
            "ordinal": 1,
            "active": "true",
            "is_custom": "true",
            "retain": "true"
        }
    ]
}

This endpoint retrieves a list of Phase resources, which describe phases of a software development process.

GET /api/v2/phases/

Query Parameters

The following parameters may be used to filter the phases resources in the response.

Parameter Description
name Returns the phase resource with specified name
slug Returns the phase resource with the specified slug

Get a Specific Phase

GET /api/v2/phases/X1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "X1",
    "description": "Application security requirements, generally used to assist requirements analysts.",
    "name": "Requirements",
    "slug": "requirements",
    "tip": "One-time tasks that you can verify. Similar to traditional functional requirements or user stories.",
    "ordinal": 1,
    "active": "true",
    "is_custom": "true",
    "retain": "true"
}

This endpoint retrieves a specific Phase resource, as specified by the id parameter.

GET /api/v2/phases/{phase_id}/

URL Parameters

Parameter Description
phase_id The id of the phase to retrieve

Create a Phase

POST /api/v2/phases/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "New Phase",
    "description": "description",
    "tip": "tip",
    "ordinal": 1,
    "retain": "true"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "CX1",
    "name": "New Phase",
    "slug": "new_phase",
    "description": "description",
    "tip": "tip",
    "ordinal": 1,
    "active": "true",
    "is_custom": "true",
    "retain": "true"
}

This endpoint creates a new Phase resource.

POST /api/v2/phases/{phase_id}/

Fields Required Description
name Yes The name of the phase.
description Yes The description of the phase.
tip Yes The tooltip for the phase.
ordinal Yes The order of the phase.
retain No Determines whether this phase carries over statuses and notes by default.

Update a Phase

PUT /api/v2/phases/CX1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "Updated Requirements",
    "description": "Updated Application security requirements",
    "tip": "updated tip",
    "ordinal": 1,
    "retain": "true",
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "CX1",
    "name": "Updated Requirements",
    "slug": "updated_requirements",
    "description": "Updated Application security requirements",
    "tip": "updated tip",
    "ordinal": 1,
    "active": "true",
    "is_custom": "true",
    "retain": "true"
}

This endpoint updates a specific Phase resource, as specified by the id parameter.

PUT /api/v2/phases/{phase_id}/

Fields Required Description
name Yes The name of the phase.
description Yes The description of the phase.
tip Yes The tooltip for the phase.
ordinal Yes The order of the phase.
retain No Determines whether this phase carries over statuses and notes by default.

PATCH /api/v2/phases/{phase_id}/

Fields Required Description
name No The name of the phase.
description No The description of the phase.
tip No The tooltip for the phase.
ordinal No The order of the phase.
retain No Determines whether this phase carries over statuses and notes by default.

URL Parameters

Parameter Description
phase_id The id of the phase to update

Delete a Phase

DELETE /api/v2/phases/CX1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "replacement": "CX2"
}
HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

This endpoint deletes a specific Phase resource, as specified by the id parameter.

DELETE /api/v2/phases/{phase_id}/

Fields Required Description
replacement Yes The phase to move the tasks of the current phase to.

URL Parameters

Parameter Description
phase_id The id of the phase to delete

Profiles

Get All Profiles

GET /api/v2/profiles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": "P1",
            "name": "No Profile",
            "description": "An empty Profile",
            "answers": ["A740"],
            "logo_url": "/static/images/logo-other.png"
        },
        {
            "id": "P3",
            "name": ".NET Web App",
            "description": "Microsoft .NET Web Application",
            "answers":["A1061", "A740", "A48", "A4", "A2"],
            "logo_url": "/static/images/logo-net.png"
        }
    ]
}

This endpoint retrieves a list of Profiles resources.

Query Parameters

Parameter Description
ordering Returns a list of profile resources ordered by the specified field. This endpoint supports ordering by id, name and description.

Project Roles

Get All Project Roles

GET /api/v2/project-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": "PR4",
            "name": "Manage Project",
            "description": "Can change project survey, ...",
            "permissions": [
                "edit_project_membership",
                "archive_project",
                "lock_project_survey",
                "write_task_note",
                "verify_task",
                "sync_with_alm",
                "edit_project_survey",
                "edit_project_details",
                "assign_task",
                "mark_task",
                "view_project",
                "create_project_specific_task"
            ]
        },
        {
            "id": "PR5",
            "name": "Normal",
            "description": "Can view project and update task statuses",
            "permissions": [
                "verify_task",
                "mark_task",
                "view_project",
                "write_task_note"
            ]
        },
        {
            "id": "PR6",
            "name": "Read Only",
            "description": "Can view project, but not modify it",
            "permissions": [
                "view_project"
            ]
        }
    ]
}

This endpoint returns a list of Project Role resources.

URL Parameters

Parameter Description
ordering Sort project roles by the specified field. Prefix field name with minus to sort descending. Sortable fields: name.
search Filter project roles by performing a textual search on name.

Get a Specific Project Role

GET /api/v2/project-roles/CPR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "CPR1",
    "name": "Custom Role",
    "description": "Can view project.",
    "permissions": [
        "view_project"
    ]
}

This endpoint returns a specific Project Role resource, specified by its id.

GET /api/v2/project-roles/{project_role_id}/

URL Parameters

Parameter Description
project_role_id The id of the Project Role to retrieve.

Create a New Project Role

POST /api/v2/project-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "New Project Role",
    "description": "Can view project!",
    "inherit_from": "PR6"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{ 
    "id": "CPR3",
    "name": "New Project Role",
    "description": "Can view project!",
    "permissions": [
        "view_project"
    ]
}
POST /api/v2/project-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "New Project Role",
    "description": "Can view project!",
    "permissions": [
        "view_project"
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{ 
    "id": "CPR3",
    "name": "New Project Role",
    "description": "Can view project!",
    "permissions": [
        "view_project"
    ]
}
Fields Required Description
name Yes The name of the Project Role.
description Yes A description of the Project Role.
permissions No The permissions given to users who are assigned this Project Role.
inherit_from No If inherit_from field is passed, then the permissions field gets set with the permissions of the parent Project Role.

Update a Project Role

PATCH /api/v2/project-roles/CPR3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "permissions": ["view_project", "archive_project"]
}
HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "id": "CPR3",
    "name": "New Project Role",
    "description": "Can view project!",
    "permissions": [
        "view_project",
        "archive_project"
    ]

}

PATCH /api/v2/project-roles/{project_role_id}/

URL Parameters

Parameter Description
project_role_id The id of the Project Role to update

Payload

Fields Required Description
name No The name of the Project Role.
description No Project Role description.
permissions No The permissions given to users who are assigned this Project Role.

Delete a Project Role

DELETE /api/v2/project-roles/CPR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "replacement": "PR1"
}
HTTP/1.1 204 NO CONTENT

DELETE /api/v2/project-roles/{project_role_id}/

URL Parameters

Parameter Description
project_role_id The id of the Project Role to delete

Payload

Fields Required Description
replacement Yes The id of the Project Role to replace the one to be deleted.

Project Survey

Get the project survey of a project

GET /api/v2/projects/1/survey/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [
        "A21",
        "A493"
    ],
    "survey_complete": true
}

This endpoint returns data relevant to the profile for the current project

GET /api/v2/projects/{project_id}/survey/

Expand Filters

GET /api/v2/projects/1/survey/?expand=answers HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [
        {
            "id": "A21",
            "cpe": "cpe:/question/answer",
            "text": "",
            "selected_by": [],
            "question": "Q100"
        }
    ],
    "survey_complete": true
}

See the Expand Parameters section for more details.

Parameter Description
answers answers in answers field are expanded to include id, cpe, text, selected_by

Project Survey Draft

Get the current state of the project survey draft

GET /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [{
            "id": "A21",
            "selected": false,
            "valid": true
    }, ...],
    "survey_complete": true,
    "dirty": false
}

Returns the current state of the survey draft. All non-hidden answers are returned along with whether they are selected and whether they are valid for the current survey state. Dirty is a boolean representing whether the current draft state is different from the last saved survey.

GET /api/v2/projects/{project_id}/survey/draft/

Include Filters

GET /api/v2/projects/1/survey/draft/?include=survey HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [{
            "id": "A21",
            "selected": false,
            "valid": true
    }, ...],
    "survey_complete": true,
    "dirty": false,
    "survey": {
        "sections": [{
            "id": "S1",
            "title": "Application Survey",
            "slug": "application-survey",
            "subsections": [{
                "id": "Q1",
                "title": "Programming Language",
                "questions": [{
                    "id": "Q21",
                    "text": "Is this a question?",
                    "description": "Help text",
                    "format": "MC", // SC for single choice, else MC
                    "mandatory": false,
                    "satisfied": true,
                    "subquestions": [{
                        "mandatory": false,
                        "description: "",
                        "format: "MC",
                        "text: "Sub Question?",
                        "satisfied": true,
                        "answers": [{
                            "description": "Description 1",
                            "text": "Answer 1",
                            "selected": false,
                            "selected_by": [ ],
                            "valid": true,
                            "id": "A11"
                        }, {
                            "description": "Description 2",
                            "text": "Answer 2",
                            "selected": false,
                            "selected_by": [ ],
                            "valid": true,
                            "id": "A12"
                        }],
                        id: "Q216"
                    }],
                    "answers": [{
                        "id": "A21",
                        "text": "Yes",
                        "description": "Help text",
                        "selected": false,
                        "valid": true,
                        "selected_by": []
                    }, ...]
                }, ...]
            }, ...]
        }, ...]
    }
}

See the Include Parameters section for more details.

Parameter Description
survey Includes a full representation of the survey structure with metadata

Reset the draft

DELETE /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [{
            "id": "A21",
            "selected": false,
            "valid": true
    }, ...],
    "survey_complete": true,
    "dirty": false,
}

Reverts changes to the draft to the last saved state.

DELETE /api/v2/projects/{project_id}/survey/draft/

Save the draft

POST /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [{
            "id": "A21",
            "selected": false,
            "valid": true
    }, ...],
    "survey_complete": true,
    "dirty": false,
}

This saves the current changes to the draft to the project. This may cause changes in the applicable tasks & other content for the project as well as accepting any other unaccepted changes to the tasks.

POST /api/v2/projects/{project_id}/survey/draft/

Modify an answer in the draft

PUT /api/v2/projects/1/survey/draft/A21/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{"selected": true}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [{
            "id": "A21",
            "selected": true,
            "valid": true
    }, ...],
    "survey_complete": true,
    "dirty": true
}

Modifies the specified answer in the draft and returns the full draft state. This may affect other answer's selected and valid values.

PUT /api/v2/projects/{project_id}/survey/draft/{answer_id}/

Field Required Description
selected Yes Selects or unselects the specified answer

Clone a profile to the draft

PUT /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{"profile": "P21"}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "answers": [{
            "id": "A21",
            "selected": true,
            "valid": true
    }, ...],
    "survey_complete": true,
    "dirty": true
}

Clears the current draft and uses the answers set on the specified profile for the draft instead. Any unsaved changes will be lost.

PUT /api/v2/projects/{project_id}/survey/draft/

Field Required Description
profile Yes Profile id of profile to clone from

Project Activities

Get Activities associated with a Project

This endpoint returns a list of Activities associated with a Project. Activities are events that have occurred in the application. The date the event occurred and some additional data is returned.

GET /api/v2/projects/{project_id}/activities/

URL Parameters

Parameter Description
project_id The id of the Project to retrieve the activities of. 
GET /api/v2/projects/{project_id}/activities/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    count: 3,
    next: null,
    previous: null,
    results: [
        {
            id: 4278,
            name: "ModifiedProjectActivity",
            actor: 1,
            text: "Admin Testerton modified project 123444321443 in application Flipism",
            date: "2016-10-31T19:43:23.648726Z",
            data: {
                project_desc: "123444321443",
                application_desc: "Flipism",
                project: 11,
                application: 5,
                business_unit: 1,
                business_unit_desc: "Test BU"
            },
            icon: "modify",
            log_level: "modify"
        },
        {
            id: 4271,
            name: "CreatedProjectActivity",
            actor: 1,
            text: "Admin Testerton created project 123444321 in application Flipism",
            date: "2016-10-31T19:20:13.887289Z",
            data: {
                project_desc: "123444321",
                application_desc: "Flipism",
                project: 11,
                application: 5,
                business_unit: 1,
                business_unit_desc: "Test BU"
            },
            icon: "createProject",
            log_level: "create"
        },
        {
            id: 4270,
            name: "AddedUserToProjectActivity",
            actor: 1,
            text: "Admin Testerton added Admin Testerton to project 123444321 in application Flipism",
            date: "2016-10-31T19:20:12.570855Z",
            data: {
                project_desc: "123444321",
                application_desc: "Flipism",
                project: 11,
                application: 5,
                business_unit: 1,
                user: "U1",
                user_desc: "Admin Testerton",
                business_unit_desc: "Test BU"
            },
            icon: "personAdd",
            log_level: "user"
        }
    ]
}

Projects

Get All Projects

GET /api/v2/projects/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1936,
        "slug": "project-test",
        "url": "http://example.com/bunits/bu-test/app-test/project-test",
        "application": 1280,
        "profile" : {
            "id": "P9",
            "name": "Android App",
            "logo_url": "/static/images/android.png"
        },
        "archived": false,
        "name": "Project Test",
        "creator": 1,
        "description": "API Project",
        "tags": ["foo", "bar"],
        "created": "2015-04-15T19:30:04.132712Z",
        "updated": "2015-04-15T19:57:15.042353Z",
        "parent": {
            "id": 8,
            "slug": "parent-984-gamma",
            "name": "Parent 9.8.4 Gamma",
            "url": "http://example.com/bunits/bu-test/app-test/parent-984-gamma/"
        },
        "base": {
            "id": 10,
            "name": "base 9.8.4 Gamma",
            "slug": "base-984-gamma",
            "url": "http://example.com/bunits/bu-test/app-test/base-984-gamma/"
        },
        "users": [{
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true
        }],
        "groups": [{
            "id": "G1",
            "name": "Devs",
            "role": "PR4"
        }],
        "custom_attributes": {
          "slug": "value"
        },
        "locked_on": null,
        "locked_by": null,
        "locked": false
    }]
}

This endpoint retrieves a list of Project resources.

GET /api/v2/projects/

Query Parameters

The following parameters may be used to filter the project resources in the response.

Parameter Description
application Filter projects by Application ID.
name Filter projects by name.
slug Filter projects by slug.
ordering Sort projects by the specified field. Prefix field name with minus to sort descending. Sortable fields: name, created, updated.
search Filter projects by performing a textual search on name and profile name.

Include Parameters

GET /api/v2/projects/1/?include=permissions,task_counts HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1936,
        "slug": "project-test",
        "url": "http://example.com/bunits/bu-test/app-test/project-test",
        "application": 1280,
        "profile" : {
            "id": "P9",
            "name": "Android App",
            "logo_url": "/static/images/android.png"
        },
        "archived": false,
        "name": "Project Test",
        "creator": 1,
        "description": "API Project",
        "tags": ["foo", "bar"],
        "created": "2015-04-15T19:30:04.132712Z",
        "updated": "2015-04-15T19:57:15.042353Z",
        "parent": null,
        "base": null,
        "users": [{
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true
        }],
        "groups": [{
            "id": "G1",
            "name": "Devs",
            "role": "PR4"
        }],
        "custom_attributes": {
          "slug": "value"
        },
        "permissions": [
            "edit_project_details",
            "assign_task",
            "mark_task",
            "create_project_specific_task",
            "archive_project",
            "verify_task",
            "edit_project_membership",
            "view_project",
            "write_task_note",
            "sync_with_alm",
            "edit_project_survey"
        ],
        "task_counts": {
            "development": {
                "high": {
                    "na": 0,
                    "total": 16,
                    "complete": 2,
                    "incomplete": 14
                },
                "medium": {
                    "na": 0,
                    "total": 15,
                    "complete": 1,
                    "incomplete": 14
                },
                "low": {
                    "na": 0,
                    "total": 3,
                    "complete": 1,
                    "incomplete": 2
                }
            },
            "testing": {
                "high": {
                    "na": 0,
                    "total": 25,
                    "complete": 2,
                    "incomplete": 23
                },
                "medium": {
                    "na": 0,
                    "total": 33,
                    "complete": 1,
                    "incomplete": 32
                },
                "low": {
                    "na": 0,
                    "total": 14,
                    "complete": 2,
                    "incomplete": 12
                }
            },
            "requirements": {
                "high": {
                    "na": 0,
                    "total": 12,
                    "complete": 4,
                    "incomplete": 8
                },
                "medium": {
                    "na": 0,
                    "total": 26,
                    "complete": 0,
                    "incomplete": 26
                },
                "low": {
                    "na": 0,
                    "total": 10,
                    "complete": 2,
                    "incomplete": 8
                }
            },
            "architecture-design": {
                "high": {
                    "na": 0,
                    "total": 4,
                    "complete": 1,
                    "incomplete": 3
                },
                "medium": {
                    "na": 0,
                    "total": 3,
                    "complete": 1,
                    "incomplete": 2
                },
                "low": {
                    "na": 0,
                    "total": 1,
                    "complete": 1,
                    "incomplete": 0
                }
            }
        },
        "locked_on": null,
        "locked_by": null,
        "locked": false
    }]
}

See the Include Parameters section for more details.

Parameter Description
permissions Includes a list of permissions the requesting user has for the project
task_counts Includes counts of tasks broken down by phase, priority and completeness for the project.
Priorities are: high (7-10), medium (4-6), low (1-3).

Expand Parameters

GET /api/v2/projects/?expand=creator HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1936,
        "slug": "project-test",
        "url": "http://example.com/bunits/bu-test/app-test/project-test",
        "application": 1280,
        "profile" : {
            "id": "P9",
            "name": "Android App",
            "logo_url": "/static/images/android.png"
        },
        "archived": false,
        "name": "Project Test",
        "creator": {
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true
        },
        "description": "API Project",
        "tags": ["foo", "bar"],
        "created": "2015-04-15T19:30:04.132712Z",
        "updated": "2015-04-15T19:57:15.042353Z",
        "parent": null,
        "base": null,
        "users": [{
            "id": "1",
            "email": "test@example.com",
            "role": "PR4",
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true
        }],
        "groups": [{
            "id": "G1",
            "name": "Devs",
            "role": "PR4"
        }],
        "custom_attributes": {
          "slug": "value"
        },
        "locked_on": null,
        "locked_by": null,
        "locked": false
    }]
}

See the Expand Parameters section for more details.

Parameter Description
creator Creator field is expanded to display information on the project creator

Get a Specific Project

GET /api/v2/projects/1936/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1936,
    "slug": "project-test",
    "url": "http://example.com/bunits/bu-test/app-test/project-test",
    "application": 1280,
    "profile" : {
        "id": "P9",
        "name": "Android App",
        "logo_url": "/static/images/android.png"
    },
    "archived": false,
    "name": "Project Test",
    "creator": 1,
    "description": "API Project",
    "tags": ["foo", "bar"],
    "created": "2015-04-15T19:30:04.132712Z",
    "updated": "2015-04-15T19:57:15.042353Z",
    "parent": null,
    "base": null,
    "users": [{
        "id": "1",
        "email": "test@example.com",
        "role": "PR4",
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true
    }],
    "groups": [{
        "id": "G1",
        "name": "Devs",
        "role": "PR4"
    }],
    "custom_attributes": {
      "slug": "value"
    },
    "locked_on": null,
    "locked_by": null,
    "locked": false
}

This endpoint retrieves a specific Project resource, as specified by the id parameter.

GET /api/v2/projects/{project_id}/

URL Parameters

Parameter Description
project_id The id of the Project to retrieve

Create a New Project

POST /api/v2/projects/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "application": 1280,
    "name": "API Test",
    "profile": "P9",
    "users": [{"email": "test@example.com", "role": "PR4"}],
    "groups": [{"id": "G1", "role": "PR4"}]
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1936,
    "slug": "project-test",
    "url": "http://example.com/bunits/bu-test/app-test/project-test",
    "application": 1280,
    "profile" : {
        "id": "P9",
        "name": "Android App",
        "logo_url": "/static/images/android.png"
    },
    "archived": false,
    "name": "Project Test",
    "creator": 1,
    "description": "API Project",
    "tags": ["foo", "bar"],
    "created": "2015-04-15T19:30:04.132712Z",
    "updated": "2015-04-15T19:57:15.042353Z",
    "parent": null,
    "base": null,
    "users": [{
        "id": "1",
        "email": "test@example.com",
        "role": "PR4",
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true
    }],
    "groups": [{
        "id": "G1",
        "name": "Devs",
        "role": "PR4"
    }],
    "custom_attributes": {
    },
    "locked_on": null,
    "locked_by": null,
    "locked": false
}
Fields Required Description
application Yes The ID of the application the project should be created under.
groups No A list of dictionaries per group that are to be assigned to the project. Each dictionary should contain the group's id and the desired role.
name Yes The name of the new project.
profile No The ID of the desired profile for the project.
users No A list of dictionaries per user that are to be assigned to the project. Each dictionary should contain the user's email and the desired role.
locked No A boolean field to lock or unlock the project. It can only be used by users that have lock_project_survey permission

Update a Project

PATCH /api/v2/projects/1936/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "application": 1,
    "name": "This is the project's new name!"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1936,
    "slug": "project-test",
    "url": "http://example.com/bunits/bu-test/app-test/project-test",
    "application": 1,
    "profile" : {
        "id": "P9",
        "name": "Android App",
        "logo_url": "/static/images/android.png"
    },
    "archived": false,
    "name": "This is the project's new name!",
    "creator": 1,
    "description": "API Project",
    "tags": ["foo", "bar"],
    "created": "2015-04-15T19:30:04.132712Z",
    "updated": "2015-07-23T15:52:14.482992Z",
    "parent": null,
    "base": null,
    "users": [{
        "id": "1",
        "email": "test@example.com",
        "role": "PR4",
        "first_name": "Admin",
        "last_name": "Testerton",
        "is_active": true
    }],
    "groups": [{
        "id": "G1",
        "name": "Devs",
        "role": "PR4"
    }],
    "custom_attributes": {
      "slug": "value"
    },
    "locked_on": "2016-06-01T14:39:45.083334Z",
    "locked_by": 1,
    "locked": true
}

Update a single project by specifying a new name and a new application. The project to update is identified by the id.

PATCH /api/v2/projects/{project_id}/

URL Parameters

Parameter Description
project_id The id of the Project to update

Payload

Fields Required Description
locked No A boolean field to lock or unlock the project. It can only be used by users that have lock_project_survey permission
application No The ID of the application the project should be created under.
profile No The ID of the desired profile for the project.
archived No A boolean to archive and unarchive a project.
name No The name of the project.
description No Project description.
tags No List of project tags.
parent No ID, name, slug, and URL of the parent project.
base No ID, name, slug, and URL of the original project.
users No A list of dictionaries per user that are to be assigned to the project. Each dictionary should contain the user's email and the desired role.
groups No A list of dictionaries per group that are to be assigned to the project. Each dictionary should contain the group's id and the desired role.

Delete a Project

DELETE /api/v2/projects/10/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT

This endpoint deletes a specific project, specified by the project id.

DELETE /api/v2/projects/{project_id}/

URL Parameters

Parameter Description
project_id The id of the Project to delete

Report Settings

Get All Report Settings

GET /api/v2/report-settings/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "CR1",
        "title": "Example Report",
        "filters": {
            "completion":   {
                "max": 100,
                "min": 0,
                "floor": 0,
                "ceil": 100
            },
            "project":[],
            "projectTags":[],
            "priority":["high", "medium", "low"],
            "application":[],
            "state": false,
            "phase":["requirements", "architecture-design", "development", "testing"],
            "taskTags":[]
        },
        "filter_query": {
            "project":  {
                "$and":[{
                    "archived": {
                        "$exact": false
                    }
                }]
            },
            "task": {
                "$and": [{
                    "priority_label":   {
                        "$in":["high", "medium"]
                    }
                }]
            }
        },
        "template": "project"
}

This endpoint retrieves a list of Report Settings resources.

GET /api/v2/report-settings/

Query Parameters

The following parameters may be used to filter the report setting resources resources in the response.

Parameter Description
template Returns a list of report settings with the specified template

Get a Specific Report Setting

GET /api/v2/report-settings/CR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "CR1",
        "title": "Example Report",
        "filters": {
            "completion":   {
                "max": 100,
                "min": 0,
                "floor": 0,
                "ceil": 100
            },
            "project":[],
            "projectTags":[],
            "priority":["high", "medium", "low"],
            "application":[],
            "state": false,
            "phase":["requirements", "architecture-design", "development", "testing"],
            "taskTags":[]
        },
        "filter_query": {
            "project":  {
                "$and":[{
                    "archived": {
                        "$exact": false
                    }
                }]
            },
            "task": {
                "$and": [{
                    "priority_label":   {
                        "$in":["high", "medium"]
                    }
                }]
            }
        },
        "template": "project"
}

This endpoint retrieves a specific Report Setting resource, as specified by the id parameter.

GET /api/v2/applications/{report-settings_id}/

URL Parameters

Parameter Description
report-settings_id The id of the report setting to retrieve

Create A New Report Setting

POST /api/v2/report-settings/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "template": "project",
    "title": "API Test Report Settings"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": "CR3",
    "title": "API Test Report Settings",
    "filters": null,
    "filter_query":{
        "project":{},
        "task":{}
    },
    "template": "project"
}
Fields Required Description
filters No A json object containing any filters on the project survey.
filter_query No A json object containing the query to be run against the project resource.
template Yes The type of report that the settings apply to. Usually set to "project".
title Yes A string representing a unique title of the report settings.

Delete a Report Setting

DELETE /api/v2/report-settings/CR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

This endpoint deletes a specific Report Setting as identified by the id.

DELETE /api/v2/report-settings/{report-settings_id}/

Parameter Description
report-settings_id The id of the report setting to delete

Server Information

Get Server Information

GET /api/v2/server-info/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "domain":"localhost.com",
    "jobs_queue_length":0,
    "sso_settings":null,
    "platform":{
        "python":{
            "implementation":"CPython",
            "version":"2.7.10",
            "pip_packages":[
                {
                    "version":"1.0",
                    "package":"some-package"
                },
                {
                    "version":"1.0",
                    "package":"other-package"
                }
            ]
        },
        "system":"Darwin-15.2.0-x86_64-i386-64bit"
    },
    "plugins":{
        "project_reports":[
            {
                "name":"ProjectStatusReport",
                "title":"Completion Status Report"
            },
            {
                "name":"ComplianceReport",
                "title":"Compliance Report"
            },
            {
                "name":"ProblemSummaryReport",
                "title":"Problem Summary Report"
            },
            {
                "name":"AllTasksReport",
                "title":"All Tasks Report"
            }
        ],
        "bu_reports":[

        ],
        "project_connections":[

        ]
    },
    "release":{
        "date":"2015-12-04",
        "name":"3.4"
    }
}

This endpoint provides information on SDE release version, domain name, server platform, python version and implementation, pip modules and their versions, SSO details if applicable, ALM job queue length, and installed SDE plugins. Available only for SDE super-users.

GET /api/v2/server-info/

Service Status

Get Service Statuses

GET /api/v2/service-statuses/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "name": "keyczar",
        "available": true,
        "message": "OK"
    }, {
        "name": "celery",
        "available": true,
        "message": "OK"
    }, {
        "name": "rabbitmq",
        "available": true,
        "message": "OK"
    }]
}

This endpoint returns the status of all services used by SDElements. Available only for SDE super-users.

GET /api/v2/service-statuses/

Single Sign On

Test LDAP Connection Bind

POST /api/v2/sso/ldap/connection-test/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "server_uri": "ldaps://ldap.server.com:777",
    "bind_dn": "CN=Bind User,CN=Users,DC=server,DC=com",
    "bind_password": "Password1",
    "start_tls": false
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "details": ""
}

Performs a simple connection bind and query test against the LDAP server.

POST /api/v2/sso/ldap/connection-test/

Fields Required Description
server_uri Yes The URI of the LDAP server.
bind_dn No The distinguished name to use when binding to the LDAP server. Leave blank for anonymous bind.
bind_password No The password used with the bind DN. Leave blank for anonymous bind.
start_tls No If checked, each connection to the LDAP server will enable TLS encryption over the standard LDAP port.

Test LDAP User Authentication

POST /api/v2/sso/ldap/authentication-test/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "server_uri": "ldaps://ldap.server.com:777",
    "bind_dn": "CN=Bind User,CN=Users,DC=server,DC=com",
    "bind_password": "Password1",
    "start_tls": true,
    "username": "john@server.com",
    "password": "password",
    "base_dn": "DC=server,DC=com",
    "scope": 2,
    "search_filter": "(mail=%(user)s)"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "details": ""
}

Tests user authentication against an LDAP server from the SDE instance.

POST /api/v2/sso/ldap/authentication-test/

Fields Required Description
server_uri Yes The URI of the LDAP server.
bind_dn No The distinguished name to use when binding to the LDAP server. Leave blank for anonymous bind.
bind_password No The password used with the bind DN. Leave blank for anonymous bind.
start_tls No If checked, each connection to the LDAP server will enable TLS encryption over the standard LDAP port.
username Yes The username/email of the authenticating user.
password Yes The password of the authenticating user.
base_dn Yes The DN within which to search for the user.
scope No The scope of the search. A numerical value from 0 to 2 where 0 = base, 1 = one-level and 2 = subtree.
search_filter Yes Used by SD Elements to look-up users on the LDAP server. Should almost always be '(mail=%(user)s)'.

Tags

Get all tags

GET /api/v2/tags/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "name": "important"
    },
    {
        "name": "deployment"
    },
    {
        "name": "my_tag"
    }]
}

This endpoint returns a list of Tag resources.

GET /api/v2/tags/

Tasks

Get all tasks of a project

GET /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": "Insecure forgotten password and password reset...",
        "priority": 8,
        "phase": "Requirements",
        "ad_hoc": false,
        "relevant": true,
        "accepted": true,
        "assigned_to": [],
        "updated": "2015-06-16T19:37:44.710100Z",
        "updater": 7,
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": null,
        "status": "TS2",
        "note_count": 0,
        "artifact_proxy": null
    }]
}

This endpoint returns a list of Task resources associated with the project having id "project_id".

GET /api/v2/projects/{project_id}/tasks/

Expand Parameters

GET /api/v2/projects/1/tasks/?expand=description,status,text,updater HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": {
            "description": "Insecure forgotten password and password reset...",
            "amendments": []
        },
        "priority": 8,
        "phase": "Requirements",
        "ad_hoc": false,
        "relevant": true,
        "accepted": true,
        "assigned_to": [],
        "updated": "2015-06-16T19:37:44.710100Z",
        "updater": {
            "first_name": "Hamish",
            "last_name": "Stout",
            "is_active": true,
            "email": "hamish.stout@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 7
        },
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": null,
        "status": {
            "id": "TS2",
            "meaning": "TODO",
            "icon": "clock-o",
            "name": "Incomplete",
            "slug": "TODO"
        },
        "note_count": 0,
        "artifact_proxy": null

    }]
}

See the Expand Parameters section for more details.

Parameter Description
description Description field is expanded into content and amendments sub-fields.
status Status field is expanded into id, meaning, icon, name and slug sub-fields.
phase Phase field is expanded into id, name, slug, description and tip sub-fields.
updater Updater field is expanded into id, first name, last name, email, role, and active status sub-fields.

Include Parameters

GET /api/v2/projects/1/tasks/?include=tags,related,problem,how_tos,references,training HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": "Insecure forgotten password and password reset...",
        "priority": 8,
        "phase": "Requirements",
        "ad_hoc": false,
        "relevant": true,
        "accepted": true,
        "assigned_to": [],
        "updated": "2015-06-16T19:37:44.710100Z",
        "updater": 7,
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": null,
        "status": "TS2",
        "note_count": 0,
        "artifact_proxy": null,
        "tags": ["tag1", "tag2"],
        "related": ["1-T31", "1-T32", "1-T34", "1-T98"],
        "problem": {
            "id": "P526",
            "title": "P526: Weak Password Recovery Mechanism...",
            "text": "It is common for an application...",
            "cwe": [
                {
                    "url": "http://example.com/640",
                    "id": 640,
                    "title": "Weak Password Recovery..."
                }
            ]
        },
        "how_tos": [
            {
                "id": "I131",
                "title": "Manually with browser",
                "slug": "test-account-lockout-manually-browser",
                "url": "http://a7069ccda519b00c4/....",
                "text": "1. Open your web browser ..."
            }
        ],
        "regulation_sections": [
            {
                "id": "RS1026",
                "name": "CR2.7 (L3 and higher)",
                "regulation": "CR45"
            },
            {
                "id": "RS642",
                "name": "SR2.7 (L3 and higher)",
                "regulation": "CR39"
            }
        ],
        "references": [
            {
              "id": 10,
              "alm_connection": 1,
              "reference": "47300",
              "name": "US451",
              "link": "https://sdetest.atlassian.net/rest/api/2/issue/47300"
            }
        ],
        "training": [
            {
              "title": "OWASP Top 10 2013",
              "id": "TR1",
              "modules": [
                  {
                     "title": "Cross-site request forgery (CSRF)",
                     "id": "M5",
                     "link": "/static/05_CSRF/story_html5.html?tincan=true&endpoint=%2Ftincan%2F&enrollment_id=1",
                     "completed": false
                  },
                  {
                     "title": "Broken authentication and session management",
                     "id: "M7",
                     "link": "/static/07_Broken_Auth/story_html5.html?tincan=true&endpoint=%2Ftincan%2F&enrollment_id=1",
                     "completed": true
                  }
            },
            {
              "title": "Development",
              "id": "TR6",
              "modules": [
                  {
                     "title": "Software Development, Operation, Maintenance & Disposal",
                     "id: "M8",
                     "link": "/static/08_Software_dev/story_html5.html?tincan=true&endpoint=%2Ftincan%2F&enrollment_id=1",
                     "completed": true
                  }
              ]
            }
        ]
    }]
}

See the Include Parameters section for more details.

Parameter Description
how_tos Includes a list of applicable how-tos
problem Includes the problem that the task is related to
related Includes a list of related tasks
tags Includes a list of tags associated to the task
regulation_sections Includes a list of regulation sections to which this task belongs
references Includes a list of task references linked to this task
training Includes a list of training courses/modules linked to this task

Filter Parameters

GET /api/v2/projects/1/tasks/?accepted=true&relevant=false HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": "Insecure forgotten password and password reset...",
        "priority": 8,
        "phase": "Requirements",
        "ad_hoc": false,
        "relevant": false,
        "accepted": true,
        "assigned_to": [],
        "updated": "2015-06-16T19:37:44.710100Z",
        "updater": 7,
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z",
        "verification_status": null,
        "status": "TS2",
        "note_count": 0,
        "artifact_proxy": null,
    }]
}

Tasks can be filtered by their relevance and whether or not they have been accepted into a project by a project lead. If no filters are passed, we default to returning accepted tasks to match with the list shown in the web application.

Parameter Expected values Description
accepted true | false Return the accepted/unaccepted tasks
relevant true | false Return the relevant/irrelevant tasks

Get a Specific Task

GET /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "accepted": true,
    "ad_hoc": false,
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": [
        {
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "email": "admin@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 1
        }
    ],
    "text": "Insecure forgotten password.",
    "id": "1-T2",
    "library_task_created": "2010-10-20T17:46:50Z",
    "library_task_updated": "2015-05-07T18:58:26.732000Z",
    "note_count": 0,
    "phase": "Requirements",
    "priority": "8",
    "relevant": true,
    "status": "TS2",
    "task_id": "T2",
    "title": "Secure forgotten password",
    "updated": "2015-07-08T02:16:33.923315Z",
    "updater": 7,
    "url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
    "verification_status": null
}

This endpoint retrieves a single Task resource, as specified by the id parameter.

GET /api/v2/projects/{project_id}/tasks/{task_id}/

Create a New Project Specific Task

POST /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": ['admin@example.com'],
    "phase": "X1",
    "priority": 9,
    "status": "TS1",
    "text": "Task Description",
    "title": "Project Specific Task"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "accepted": true,
    "ad_hoc": true,
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": [
        {
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "email": "admin@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 1
        }
    ],
    "text": "Task Description",
    "id": "1-PT1",
    "library_task_created": "2015-05-07T18:58:26.732000Z",
    "library_task_updated": "2015-05-07T18:58:26.732000Z",
    "note_count": 0,
    "phase": "X1",
    "priority": "9",
    "relevant": true,
    "status": "TS1",
    "task_id": "PT1",
    "title": "Project Specific Task",
    "updater": 7,
    "updated": "2015-05-07T18:58:26.732000Z",
    "url": "http://example.com/.../1-PT1",
    "verification_status": null
}

Creates a new Task resource that is project-specific.

POST /api/v2/projects/{project_id}/tasks/

URL Parameters

Parameter Description
project_id The id of the project the new task belongs to

Payload

Fields Required Description
artifact_proxy No Arbitrary string which identifies a synchronized ALM issue
assigned_to No A list of emails for users that belong to the project
phase Yes The id of a phase
priority Yes The priority value from 0-10
status No The id of a status
text Yes The description of the new task
title Yes The title of the new task

Update a Specific Task

PATCH /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": ['user1@example.com', 'user2@example.com'],
    "status": "TS1"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "accepted": true,
    "ad_hoc": false,
    "artifact_proxy": "ABC-XYZ",
    "assigned_to": [
        {
            "first_name": "Admin",
            "last_name": "Testerton",
            "is_active": true,
            "email": "admin@example.com",
            "role": {
                "id": "UR1",
                "name": "User"
            },
            "id": 1
        }
    ],
    "text": "Insecure forgotten password.",
    "id": "1-T2",
    "library_task_created": "2010-10-20T17:46:50Z",
    "library_task_updated": "2015-05-07T18:58:26.732000Z",
    "note_count": 0,
    "phase": "X1",
    "priority": "8",
    "relevant": true,
    "status": "TS1",
    "task_id": "T2",
    "title": "Secure forgotten password",
    "updated": "2015-07-08T02:16:33.923315Z",
    "updater": 7,
    "url": "http://example.com/.../1-T2",
    "verification_status": null
}

Updates a single Task resource, as specified by the project and task id parameters.

PATCH /api/v2/projects/{project_id}/tasks/{id}/

URL Parameters

Parameter Description
project_id The id of the project this task belongs to
id The id of the task to modify

Payload

Fields Required Description
artifact_proxy No Arbitrary string which identifies a synchronized ALM issue
assigned_to No A list of emails for users that belong to the project
phase No The id of a phase. Available only if the updated task is a project specific task.
priority No The priority value from 0-10. Available only if the updated task is a project specific task.
status No The id of a status
text No The description of the task. Available only if the updated task is a project specific task.
title No The title of the task. Available only if the updated task is a project specific task.

Task Notes

Get All Task Notes

GET /api/v2/projects/1/tasks/1-T2/notes/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 682,
        "task": "1-T2",
        "text": "This task is on-hold until we...",
        "automatic": true,
        "updater": 1,
        "created": "2015-03-26T19:50:46.348000Z",
        "updated": "2015-03-26T19:50:46.348000Z"
    }]
}

This endpoint returns a list of Task Note resources.

GET /api/v2/projects/{project_id}/tasks/{task_id}/notes/

URL Parameters

Parameter Description
project_id The id of the Project
task_id The id of the Task

Get a Specific Task Note

GET /api/v2/projects/1/tasks/1-T2/notes/682/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 682,
    "task": "1-T2",
    "text": "This task is on-hold until we...",
    "automatic": true,
    "updater": 1,
    "created": "2015-03-26T19:50:46.348000Z",
    "updated": "2015-03-26T19:50:46.348000Z"
}

This endpoint returns a specific Task Note resource.

GET /api/v2/projects/{project_id}/tasks/{task_id}/notes/{note_id}/

URL Parameters

Parameter Description
project_id The id of the Project
task_id The id of the Task
note_id The id of the Task Note to retrieve

Create a Task Note

POST /api/v2/projects/1/tasks/1-T2/notes/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "text": "This task is on-hold until we..."
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 682,
    "task": "1-T2",
    "text": "This task is on-hold until we...",
    "automatic": true,
    "updater": 1,
    "created": "2015-03-26T19:50:46.348000Z",
    "updated": "2015-03-26T19:50:46.348000Z"
}

This endpoint creates a Task Note resource with the specified content.

POST /api/v2/projects/{project_id}/tasks/{task_id}/notes/

URL Parameters

Parameter Description
project_id The id of the Project
task_id The id of the Task

Fields

Field Required Description
text Yes The note text
automatic No Whether the Task Note was posted by a tool. Default is false.

Update a Task Note

PUT /api/v2/projects/1/tasks/1-T2/notes/682/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "text": "This task is on-hold until we..."
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 682,
    "task": "1-T2",
    "text": "This task is on-hold until we...",
    "automatic": true,
    "updater": 1,
    "created": "2015-03-26T19:50:46.348000Z",
    "updated": "2015-03-26T19:50:46.348000Z"
}

This endpoint updates a Task Note resource.

PUT /api/v2/projects/{project_id}/tasks/{task_id}/notes/{note_id}/

URL Parameters

Parameter Description
project_id The id of the Project
task_id The id of the Task
note_id The id of the Task Note to update

Fields

Field Required Description
text Yes The note text
automatic No Whether the Task Note was posted by a tool. Default is false.

Delete a Specific Task Note

DELETE /api/v2/projects/1/tasks/1-T2/notes/682/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT

This endpoint deletes a specific Task Note resource.

DELETE /api/v2/projects/{project_id}/tasks/{task_id}/notes/{note_id}/

URL Parameters

Parameter Description
project_id The id of the Project
task_id The id of the Task
note_id The id of the Task Note to retrieve

Task Statuses

Get all Task Statuses

GET /api/v2/task-statuses/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": "TS3",
            "meaning": "NA",
            "icon": "minus-circle",
            "name": "Not Applicable",
            "slug": "NA"
        },
        {
            "id": "TS2",
            "meaning": "TODO",
            "icon": "clock-o",
            "name": "Incomplete",
            "slug": "TODO"
        },
        {
            "id": "TS1",
            "meaning": "DONE",
            "icon": "check",
            "name": "Complete",
            "slug": "DONE"
        }
    ]
}

This endpoint returns a list of Task Status resources.

GET /api/v2/task-statuses/

Query Parameters

The following parameters may be used to filter the task status resources in the response.

Parameter Description
meaning Returns a list of the task statuses with the specified meaning field.

Task References

Get all references of a task

GET /api/v2/projects/1/tasks/1-T21/references/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "id": 1,
      "alm_connection": 2,
      "reference": "47300",
      "name": "PROJ-450",
      "link": "https://atlassian.net/browse/PROJ-450"
    },
    {
      "id": 2,
      "alm_connection": 3,
      "reference": "47301",
      "name": "PROJ-451",
      "link": "https://atlassian.net/browse/PROJ-451"
    }
  ]
}

This endpoint returns a list of Task Reference resources.

GET /api/v2/projects/{project_id}/tasks/{task_id}/references/

Get a Specific Reference

GET /api/v2/projects/1/tasks/1-T21/references/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "alm_connection": 2,
  "reference": "47300",
  "name": "PROJ-450",
  "link": "https://atlassian.net/browse/PROJ-450"
}

This endpoint retrieves a single Task Reference resource, as specified by the id parameter.

GET /api/v2/projects/{project_id}/tasks/{task_id}/references/{reference_id}/

Create a New Task Reference

POST /api/v2/projects/1/tasks/1-T21/references/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
  "alm_connection": 2,
  "reference": "47300",
  "name": "PROJ-450",
  "link": "https://atlassian.net/browse/PROJ-450"
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "id": 1,
  "alm_connection": 2,
  "reference": "47300",
  "name": "PROJ-450",
  "link": "https://atlassian.net/browse/PROJ-450"
}
Fields Required Description
alm_connection Yes The ID of the ALM connection the task is linked to
reference Yes Internal reference to a linked artifact
name No User-friendly identifier for the artifact
link No User-facing reference, like a hyperlink used in a web app

Update a Task Reference

PATCH /api/v2/projects/1/tasks/1-T21/references/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
  "reference": "47300",
  "name": "PROJ-450",
  "link": "https://atlassian.net/browse/PROJ-450"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "alm_connection": 2,
  "reference": "47300",
  "name": "PROJ-450",
  "link": "https://atlassian.net/browse/PROJ-450"
}

Update a single Task Reference

PATCH /api/v2/projects/{project_id}/tasks/{task_id}/references/{reference_id}/

URL Parameters

Parameter Description
project_id The id of the Project containing the Task
task_id The id of the Task the reference links to
reference_id The id of the Reference to update

Payload

Fields Required Description
reference No Internal reference to a linked artifact
name No User-friendly identifier for the artifact
link No User-facing reference, like a hyperlink used in a web app

Delete a Task Reference

DELETE /api/v2/projects/1/tasks/1-T21/references/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT

This endpoint deletes a specific task reference, specified by the reference id.

DELETE /api/v2/projects/{project_id}/tasks/{task_id}/references/{reference_id}/

URL Parameters

Parameter Description
project_id The id of the Project containing the Task
task_id The id of the Task the reference links to
reference_id The id of the Reference to delete

Task Updates

Retrieve the list of tasks whose inclusion state does not match its relevance

GET /api/v2/projects/1/task-updates/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": "1-T2",
        "task_id": "T2",
        "url": "http://example.com/bunits/new-business-unit/...",
        "title": "Secure forgotten password",
        "text": "Insecure forgotten password and password reset...",
        "priority": 8,
        "phase": "X1",
        "relevant": true,
        "accepted": false,
        "updated": "2015-06-16T19:37:44.710100Z",
        "library_task_created": "2015-06-16T19:36:57.863684Z",
        "library_task_updated": "2015-06-16T19:36:57.836874Z"
    }]
}

Will return a list of tasks whose accepted state is out of date with the project having id "project_id". This list includes tasks which are relevant to a project but have not had their inclusion accepted by a user and tasks which are no longer relevant to a project whose removal has yet to be accepted.

GET /api/v2/projects/{project_id}/task-updates/

URL Parameters

Parameter Description
project_id The ID of the project for the tasks

Accept task changes for a project

POST /api/v2/projects/1/task-updates/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK

Will accept all changes to the project tasks. This will add all relevant tasks to the project, and it will remove all no longer relevant tasks from the project.

POST /api/v2/projects/{project_id}/task-updates/

URL Parameters

Parameter Description
project_id The ID of the project for the tasks

Get specific updated task

GET /api/v2/projects/1/task-updates/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "1-T2",
    "task_id": "T2",
    "url": "http://example.com/bunits/new-business-unit/...",
    "title": "Secure forgotten password",
    "text": "Insecure forgotten password and password reset...",
    "priority": 8,
    "phase": "X1",
    "relevant": true,
    "accepted": false,
    "updated": "2015-06-16T19:37:44.710100Z",
    "library_task_created": "2015-06-16T19:36:57.863684Z",
    "library_task_updated": "2015-06-16T19:36:57.836874Z"
}

Return task data for a specific task whose relevance is out of line with its acceptance status

GET /api/v2/projects/{project_id}/task-updates/{task_id}/

URL Parameters

Parameter Description
project_id The ID of the project for the tasks
task_id The ID of the specific task

Users

Get All Users

GET /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 682,
        "email": "frank@sdelements.com",
        "first_name": "Frank",
        "last_name": "Developer",
        "role": "Project Lead",
        "last_login": "2014-12-15T20:10:51.900775Z",
        "date_joined": "2014-04-16T19:43:47.883319Z",
        "is_active": true,
        "is_superuser": false,
        "role": "UR5",
        "groups": [
            {
                "id": "G1",
                "name": "Group1",
                "role": "Project Lead"
            }
        ],
        "password_reset_in_progress": false
    }]
}

This endpoint returns a list of User resources.

GET /api/v2/users/

Get a Specific User

GET /api/v2/users/599/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 599,
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "last_login": "2015-06-05T02:55:54.231254Z",
    "date_joined": "2015-06-05T02:55:54.231254Z",
    "is_active": true,
    "is_superuser": false,
    "role": "No Role",
    "groups": [],
    "password_reset_in_progress": false
}

This endpoint returns a specific User resource.

GET /api/v2/users/{user_id}/

URL Parameters

Parameter Description
user_id The ID of the User to retrieve

Get the Current User

GET /api/v2/users/me/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
}

This endpoint returns the current User resource.

Update the Current User

PUT /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
}

Update the current User resource. Note: only users with "Manage users & groups" can change email addresses.

PUT /api/v2/users/me/

Fields Required Description
email No User's email
first_name No First name of the user
last_name No Last name of the user

Create a User

POST /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "role": "UR5",
    "groups": ["G1", "G2"]
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 599,
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "last_login": "2015-09-29T18:52:41.247207Z",
    "date_joined": "2015-09-29T18:52:41.247207Z",
    "is_active": true,
    "is_superuser": false,
    "role": "UR5",
    "groups": [
        {
            "id": "G1",
            "name": "Group1",
            "role": "Project Lead"
        },
        {
            "id": "G2",
            "name": "Group2",
            "role": "No Role"
        }
    ],
    "password_reset_in_progress": true
}

Create a User resource.

POST /api/v2/users/

Fields Required Description
email Yes User's email
first_name Yes First name of the user
last_name Yes Last name of the user
role No Id of the role to add user to
groups No Ids of the groups to add user to

Update a specific User

PUT /api/v2/users/599/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "groups": ["G2"],
    "role": "UR2"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 599,
    "email": "user@example.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "last_login": "2015-06-05T02:55:54.231254Z",
    "date_joined": "2015-06-05T02:55:54.231254Z",
    "is_active": true,
    "is_superuser": false,
    "role": "UR2",
    "groups": [
        {
            "id": "G2",
            "name": "Group2",
            "role": "No Role"
        }
    ],
    "password_reset_in_progress": true
}

Update a specific User resource.

PUT /api/v2/users/{user_id}/

URL Parameters

Parameter Description
user_id The ID of the User to update

Get Password Reset Info

GET /api/v2/users/1/reset-password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "expiry_date": "2016-09-30T14:51:55.889Z",
    "reset_url": "http://example.com/accounts/new-password/12e33fbfc0f5774"
}

This endpoint returns the password reset information for a specific user. This endpoint only uses either basic or session authentication.

Note: If the returned fields are null, then there is no password reset in progress.

GET /api/v2/users/{user_id}/reset-password/

Reset Password

POST /api/v2/users/1/reset-password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK

Request a password reset for a specific user.

POST /api/v2/users/{user_id}/reset-password/

Change Password

POST /api/v2/users/me/password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "current_password": "hunter2",
    "new_password": "superstrongpassword123"
}
HTTP/1.1 200 OK

{"last_password_change":"2016-12-14T18:47:04.544Z"}

Changes the password for the current user.

This endpoint only uses either basic or session authentication.

POST /api/v2/users/me/password/

Get Password Metadata

GET /api/v2/users/me/password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK

{"last_password_change":"2016-12-14T18:47:04.544Z"}

Gets metadata regarding the password for the current user.

This endpoint only uses either basic or session authentication.

GET /api/v2/users/me/password/

Get Password Reset Questions

GET /api/v2/users/me/password-reset-questions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "last_modified": "2017-01-24T22:23:23.448047Z",
    "questions": [
        {
          "id": 1,
          "question": "What was your childhood nickname?"
        },
        {
          "id": 2,
          "question": "What is the street name of the house you grew up in?"
        },
        {
          "id": 3,
          "question": "What is your mothers middle name?"
        }
    ]
}

Get the password reset questions for the current user. Note: answers will not be returned.

GET /api/v2/users/me/password-reset-questions/

Change Password Reset Questions

PATCH /api/v2/users/me/password-reset-questions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "current_password": "superstrongpassword123",
    "questions": [
        {
            "question": "What was your childhood nickname?",
            "answer": "Hunter2"
        },
        {
            "question": "What is the street name of the house you grew up in?",
            "answer": "Younge"
        },
        {
            "question": "What is your mothers middle name?",
            "answer": "Jane"
        }
    ]
}
HTTP/1.1 200 OK

{
    "last_modified": "2017-01-24T22:23:23.448047Z",
    "questions": [
        {
          "id": 1,
          "question": "What was your childhood nickname?"
        },
        {
          "id": 2,
          "question": "What is the street name of the house you grew up in?"
        },
        {
          "id": 3,
          "question": "What is your mothers middle name?"
        }
    ]
}

Changes the password reset questions for the current user.

Note: Any existing question not included will be overwritten. To exclude a question from being overwritten/deleted, include it without a new answer.

PATCH /api/v2/users/me/password-reset-questions/

User Profile

Get User Profile

GET /api/v2/users/me/profile/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
  "plaintext_emails_only": false,
  "notify_on_task_status_changed": true,
  "notify_on_task_note_added": true,
  "notify_on_job_failed": true,
  "notify_on_new_relevant_tasks_in_project": true,
  "notify_on_task_assigned": true,
  "notify_on_task_added_to_project": true,
  "notify_on_task_team_changed": true,
  "notify_tasks": ["T1", "T2"]
}

This endpoint returns the profile data of the current user.

GET /api/v2/users/me/profile/

Update User Profile

PATCH /api/v2/users/me/profile/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
Content-Type: application/json

{
  "plaintext_emails_only": false,
  "notify_on_task_status_changed": false,
  "notify_on_task_note_added": false,
  "notify_on_job_failed": true,
  "notify_on_new_relevant_tasks_in_project": true,
  "notify_on_task_assigned": true,
  "notify_on_task_added_to_project": true,
  "notify_on_task_team_changed": true,
  "notify_tasks": ["T1", "T2", "T3"]
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "plaintext_emails_only": false,
  "notify_on_task_status_changed": true,
  "notify_on_task_note_added": true,
  "notify_on_job_failed": true,
  "notify_on_new_relevant_tasks_in_project": true,
  "notify_on_task_assigned": true,
  "notify_on_task_added_to_project": true,
  "notify_on_task_team_changed": true,
  "notify_tasks": ["T1", "T2", "T3"]
}

Update the current user's profile.

PATCH /api/v2/users/me/profile/

User Activities

Get all activities

GET /api/v2/users/me/activities/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 23,
        "actor": 7,
        "name": "MarkedTaskActivity",
        "text": "Cindy Lu marked T21: Ensure confidential data is sent over an encrypted channel as Complete in project proj1 of application app1",
        "date": "2016-05-11T18:53:02.216545Z",
        "data":{
            "status": "TS1",
            "project_desc": "proj1",
            "application_desc": "app1",
            "status_desc": "Complete",
            "standard": "T21",
            "standard_desc": "T21: Ensure confidential data is sent over an encrypted channel",
            "task_desc": "T21: Ensure confidential data is sent over an encrypted channel",
            "business_unit_desc": "Example BU"
        },
        "icon" : "check",
        "log_level": ""
    },
    {
        "id": 20,
        "name": "AddedUserToProjectActivity",
        "actor": 1,
        "text": "Admin Testerton added Cindy Luto project proj1 in application app1",
        "date": "2016-05-11T18:52:34.548759Z",
        "data": {
            "project_desc": "proj1",
            "application_desc": "app1",
            "user": "U7",
            "user_desc": "Cindy Lu",
            "business_unit_desc": "Example BU"
        },
        "icon": "users",
        "log_level": ""
    },
    {
        "id": 4,
        "name": "UserCreatedActivity",
        "actor": 1,
        "text": "Admin Testerton created user Cindy Lu",
        "date": "2016-05-06T14:53:10.961953Z",
        "data": {
            "user": "U2",
            "user_desc": "Cindy Lu"
        },
        "icon": "user",
        "log_level": ""
    }]
}

This endpoint returns a list of Activities that impact the current user. This includes activities performed by the current user, activites that affect the current user directly, and activities about projects the current user is a part of. Login/logout activities are not included in this list.

Activities are events that have occurred in the application. We return when they occurred and some additional data about the event.

GET /api/v2/users/me/activities/

Note: this endpoint uses the term 'standard' to reference what we call 'library tasks' elsewhere in the API.

The application, business_unit, project, and standard fields have associated description fields, suffixed with '_desc'. These fields contain a description of the related item, and can be used to filter if the related item has been deleted.

Query Parameters

The following parameters may be used to filter the activity resources in the response.

Parameter Description
actor Returns a list of activities performed by the user with the id specified.
application Returns a list of activities that reference the application with the specified id.
application_desc Returns a list of activities that reference the application with the specified application name.
business_unit Returns a list of activities that reference the business unit with the specified id.
business_unit_desc Returns a list of activities that reference the business_unit with the specified business unit name.
date_to Returns all activities performed at or before the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime.
date_from Returns all activities performed at or after the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime.
id Returns the activities with the specified id.
name Returns a list of activities with the specified name.
project Returns a list of activities that reference the project with the specified id.
project_desc Returns a list of activities that reference the project with the specified project name.
user Returns a list of activities that reference the user with the specified user id (not to be confused with activities that are performed by this user). The id used here is a number, for example ?user=1.
standard Returns a list of activities that reference the standard with the specified id. The format of this parameter value is the standard id prefixed by a 'T' for builtin standards or 'CT' for custom standards.
standard_desc Returns a list of activities that reference the standard with the specified standard's full name, for example: "T21: Ensure confidential data is sent over an encrypted channel".

Get a Specific Activity

GET /api/v2/users/me/activities/2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
        "id": 4,
        "date": "2016-03-30T15:16:05.659610+00:00",
        "actor": 1,
        "name": "UserCreatedActivity",
        "text": "Admin Testerton created user Cindy Lu",
        "data": {"user": "U7"},
        "icon": "user",
        "log_level": ""
}

This endpoint retreives a specific Activity Resource as specified by the activity_id.

GET /api/v2/users/me/activities/{activity_id}/

URL Parameters

Parameter Description
activity_id The id of the Activity Resource to retrieve.

User Assigned Tasks

Get all assigned tasks

GET /api/v2/users/me/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "accepted": true,
        "ad_hoc": false,
        "artifact_proxy": "ABC-XYZ",
        "assigned_to": [
            {
                "email": "admin@example.com",
                "id": 3
            }
        ],
        "text": "Insecure forgotten password.",
        "id": "1-T2",
        "library_task_created": "2010-10-20T17:46:50Z",
        "library_task_updated": "2015-05-07T18:58:26.732000Z",
        "note_count": 0,
        "phase": "Requirements",
        "priority": "8",
        "relevant": true,
        "status": "TS2",
        "task_id": "T2",
        "title": "Secure forgotten password",
        "updated": "2015-07-08T02:16:33.923315Z",
        "url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
        "verification_status": null,
        "project": 1,
        "application": 1
    }]
}

This endpoint returns a list of Tasks assigned to the current user.

GET /api/v2/users/me/tasks/

Query Parameters

The following parameters may be used to filter the activity resources in the response.

Parameter Description
application Returns a list of tasks within the specified application.

Expand Parameters

GET /api/v2/users/me/tasks/?expand=project HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "accepted": true,
        "ad_hoc": false,
        "artifact_proxy": "ABC-XYZ",
        "assigned_to": [
            {
                "email": "admin@example.com",
                "id": 3
            }
        ],
        "text": "Insecure forgotten password.",
        "id": "1-T2",
        "library_task_created": "2010-10-20T17:46:50Z",
        "library_task_updated": "2015-05-07T18:58:26.732000Z",
        "note_count": 0,
        "phase": "Requirements",
        "priority": "8",
        "relevant": true,
        "status": "TS2",
        "task_id": "T2",
        "title": "Secure forgotten password",
        "updated": "2015-07-08T02:16:33.923315Z",
        "url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
        "verification_status": null,
        "project": {
            "id": 1936,
            "slug": "proj1",
            "url": "http://example.com/bunits/bu1/app1/project1",
            "application": 1,
            "profile" : {
                "id": "P9",
                "name": "Android App",
                "logo_url": "/static/images/android.png"
            },
            "archived": false,
            "name": "Proj1",
            "creator": 1,
            "description": "API Project",
            "tags": ["foo", "bar"],
            "created": "2015-04-15T19:30:04.132712Z",
            "updated": "2015-04-15T19:57:15.042353Z",
            "parent": null,
            "users": [{
                "id": "1",
                "email": "test@example.com",
                "role": "PR4",
                "first_name": "Admin",
                "last_name": "Testerton"
            }],
            "groups": [{
                "id": "G1",
                "name": "Devs",
                "role": "PR4"
            }],
            "custom_attributes": {
              "slug": "value"
            },
            "locked_on": null,
            "locked_by": null,
            "locked": false
        },
        "application": 1
    }]
}

See the Expand Parameters section for more details.

Parameter Description
project Project field is expanded to display project information.

Get a Specific Assigned Task

GET /api/v2/users/me/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
        "accepted": true,
        "ad_hoc": false,
        "artifact_proxy": "ABC-XYZ",
        "assigned_to": [
            {
                "email": "admin@example.com",
                "id": 3
            }
        ],
        "text": "Insecure forgotten password.",
        "id": "1-T2",
        "library_task_created": "2010-10-20T17:46:50Z",
        "library_task_updated": "2015-05-07T18:58:26.732000Z",
        "note_count": 0,
        "phase": "Requirements",
        "priority": "8",
        "relevant": true,
        "status": "TS2",
        "task_id": "T2",
        "title": "Secure forgotten password",
        "updated": "2015-07-08T02:16:33.923315Z",
        "url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
        "verification_status": null,
        "project": 1,
        "application": 1
}

This endpoint retreives a specific assigned task as specified by the Task id.

GET /api/v2/users/me/tasks/{task_id}/

URL Parameters

Parameter Description
task_id The id of the Task to be retrieved.

Changelog

v4.7

v4.6

v4.5

v4.4

v4.3

v4.2

v4.1, v4.0, v3.9, etc.