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=100
and use the next and previous values to move through the complete response.
Authentication
GET /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"To authenticate against SD Elements, you need to pass an API access token via an Authorization header.
A token can be generated as follows:
- Go to the menu option in the top right of SD Elements:
/API Settings - Select the APIv2 tab and click on the Generate Token Button.
- The token will be displayed only once. If you forget your token you will need to regenerate a new one.
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
}]
}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
}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
}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:
|
| 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
}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"
},
{
"id": "2",
"name": "Project 2",
"slug": "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 CONTENTThis 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
}],
"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
}
]
}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
}],
"groups": [{
"id": "G64",
"name": "Group Bar"
}],
"all_users": 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,
}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
}],
"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
}| 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. |
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
}],
"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
}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 CONTENTThis 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 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,
"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
}
}]
}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. |
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,
"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
}
}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}/
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,
"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": "{}"
}
}]
}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. |
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,
"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": "{}"
}
}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}/
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"
}]
}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"
}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"
}]
}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"
}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 |
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"
}],
"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"
},
{
"first_name": "Linda",
"last_name": "Graham",
"is_active": false,
"id": 3,
"email": "linda@example.com"
},
]
}]
}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. |
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"
}],
"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"
}],
"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 CONTENTThis 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": 1,
"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": 1,
"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": 1,
"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. |
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": 1,
"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": 1,
"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": 1,
"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. |
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."
}
]
}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."
}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 |
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.
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. |
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 |
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": 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 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/tasks/?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,
"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": {
"high": {
"incomplete": 19,
"complete": 2,
"na": 0
},
"medium": {
"incomplete": 4,
"complete": 3,
"na": 1
},
"low": {
"incomplete": 2,
"complete": 1,
"na": 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 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,
"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": 1935,
"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,
"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,
"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 of the parent 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 CONTENTThis 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/jsonThis 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/
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",
"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=status,text 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",
"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. |
Include Parameters
GET /api/v2/projects/1/tasks/?include=tags,related,problem,how_tos,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-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",
"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"
},
]
}]
}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 |
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",
"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": [
{
"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
}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": ['user1@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": [
{
"email": "user1@example.com",
"id": 3
}
],
"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",
"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": [
{
"email": "user1@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": "X1",
"priority": "8",
"relevant": true,
"status": "TS1",
"task_id": "T2",
"title": "Secure forgotten password",
"updated": "2015-07-08T02:16:33.923315Z",
"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 CONTENTThis 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 CONTENTThis 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 OKWill 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"
}
]
}]
}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": []
}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 |
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"
}
]
}Create a User resource.
POST /api/v2/users/
| Fields | Required | Description |
|---|---|---|
| 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"
}
]
}Update a specific User resource.
PUT /api/v2/users/{user_id}/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to update |
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. |