Introduction
Welcome to SD Elements API v2! Our API provides RESTful HTTP access to a large part of the functionality of SD Elements.
SD Elements's API documentation page was created with Slate
API Format
API results are currently returned in XML and JSON formats. It is advised to use the JSON format only. Specify the JSON format by including the HTTP header in all requests:
Content-type: application/json
Include Parameters
Some endpoints allow users to include extra fields in the response the API returns. This is used to add a specific field to an element, or collection of elements. For example, we may wish to receive a collection of projects that are within an application. Since projects are normally not a field of the applications resource, we can include projects in our request to see the projects as an additional field.
/?include={field_to_include}
Expand Parameters
Some endpoints allow users to expand a field that is already present in the response. For example, by default, an application element contains the id of the business unit to which it belongs. If we wish to retrieve more information about the business unit, we would expand the business unit field to get more information.
/?expand={field_to_expand}
It is possible to include and expand more than one field simultaneously.
/?include={field1},{field2}&expand={field3},{field4}
Pagination
Consume long responses by enabling pagination on an endpoint. Specify a page size in the URL:
/?page_size=10
This will limit the result set down to 10 (or fewer) elmenets. There will be a few additional values returned in addtion to the results list. next and previous are URLs you can request to get the next or previous result
set. count is the total number of resources available.
Authentication
There are several ways to authenticate against SD Elements, which are outlined below.
Basic Authentication
GET /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"To authenticate against SD Elements using basic authentication (username and password), you need to pass a Base64 encoding of your username:password as a header.
Session Authorization
GET /api/v2/users/ HTTP/1.1
Accept: application/json
Cookie: sessionid="YOUR SESSION ID"To authenticate against SD Elements using session authentication, you need to pass in your session id as a cookie in the header.
Token Authentication
GET /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"To authenticate against SD Elements using tokens, you need to pass an API access token via an Authorization header.
A token can be generated as follows:
- 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. |
ALM Connections
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": "GitHub Example Connector",
"system": {
"id": "github",
"short_name": "GitHub",
"name": "GitHub"
},
"inaccessible": false,
"params": {
"github_repo_owner": "repo owner",
"sde_verification_filter": "none,partial,pass,fail",
"alm_api_token": "token",
"title_format": "$task_id $title",
"alm_method": "https",
"alm_server": "api.github.com",
"github_duplicate_label": "duplicate",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": "7"
}
},
{
"id": 2,
"name": "JIRA Example Connector",
"system": {
"id": "jira",
"short_name": "JIRA",
"name": "JIRA"
},
"inaccessible": false,
"params": {
"sde_verification_filter": "none,partial,pass,fail",
"jira_version": "5",
"title_format": "$task_id $title",
"alm_method": "https",
"alm_server": "my-company.atlassian.net",
"alm_user": "user",
"alm_pass": "pass",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": "7"
}
},
]
}Returns a list of all ALM connectors available.
GET /api/v2/connectors/alm/
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": "GitHub Example Connector",
"system": {
"id": "github",
"short_name": "GitHub",
"name": "GitHub"
},
"inaccessible": false,
"params": {
"github_repo_owner": "repo owner",
"sde_verification_filter": "none,partial,pass,fail",
"alm_api_token": "token",
"title_format": "$task_id $title",
"alm_method": "https",
"alm_server": "api.github.com",
"github_duplicate_label": "duplicate",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": "7"
}
},Returns a specific ALM connector.
GET /api/v2/connectors/alm/{id}/
Create an ALM Connector
POST /api/v2/connectors/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "GitHub Example Connector",
"system": {
"id": "github"
},
"inaccessible": false,
"params": {
"github_repo_owner": "repo owner",
"sde_verification_filter": "none,partial,pass,fail",
"alm_api_token": "token",
"title_format": "$task_id $title",
"alm_method": "https",
"alm_server": "api.github.com",
"github_duplicate_label": "duplicate",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": "7"
}
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 1,
"name": "GitHub Example Connector",
"system": {
"id": "github",
"short_name": "GitHub",
"name": "GitHub"
},
"inaccessible": false,
"params": {
"github_repo_owner": "repo owner",
"sde_verification_filter": "none,partial,pass,fail",
"alm_api_token": "token",
"title_format": "$task_id $title",
"alm_method": "https",
"alm_server": "api.github.com",
"github_duplicate_label": "duplicate",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": "7"
}
}| Fields | Required | Description |
|---|---|---|
| name | Yes | The name of the new connector. |
| system | Yes | A dictionary containing the id, name and short name of the system. |
| inaccessible | No | Specifies whether the alm server specific is accessible from the SDE server. Defaults to false. |
| params | Yes | A dictionary containing connections options. Please refer to product documentation for more details or reach out to support. Required params will return appropriate errors when unspecified. |
Update an ALM Connector
PUT /api/v2/connectors/alm/3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "GitHub Connector PUT Example",
"system": {
"id": "github"
},
"inaccessible": false,
"params": {
"github_repo_owner": "new repo owner",
"sde_verification_filter": "none,partial,pass,fail",
"alm_api_token": "new token",
"title_format": "$task_id $title",
"alm_method": "https",
"alm_server": "api.github.com",
"github_duplicate_label": "duplicate",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": "5"
}
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 12,
"name": "GitHub Connector PUT Example",
"system": {
"id": "github",
"short_name": "GitHub",
"name": "GitHub"
},
"inaccessible": false,
"params": {
"github_repo_owner": "new repo owner",
"sde_verification_filter": "none,partial,pass,fail",
"alm_api_token": "new token",
"title_format": "$task_id $title",
"alm_method": "https",
"alm_server": "api.github.com",
"github_duplicate_label": "duplicate",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": "5"
}
}Updates a specific ALM connector resource as specified by the connector id.
PUT /api/v2/connectors/alm/{id}
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,
"alias": "Rally Integration",
"system":{
"id":"rally",
"short_name":"CA Agile Central",
"name":"CA Agile Central (formerly Rally)"
},
"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_validate_cert": true,
"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,
"alm_reference_context": 14
},
"inaccessible": false,
"in_progress": false,
"connector": 2,
"project": 1,
}]
}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 |
|---|---|
| project | Returns all analysis connections for the project with the specific id. |
Include Parameters
GET /api/v2/connections/alm/?include=last_job HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"alias": "Rally Integration",
"system":{
"id":"rally",
"short_name":"CA Agile Central",
"name":"CA Agile Central (formerly Rally)"
},
"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_validate_cert": true,
"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,
"alm_reference_context": 14
},
"inaccessible": false,
"last_job": {
"succeeded": false,
"last_run": "2016-12-15T22:45:27.412Z",
"result_message": "Error Message",
"user": 1,
"ready": true,
"automatic": false,
"id": 4
},
"in_progress": false,
"connector": 2,
"project": 2
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| last_job | Include the details of the last job executed for this connection. |
Get a Specific ALM Connection
GET /api/v2/connections/alm/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"alias": "Rally Integration",
"system": {
"id": "rally",
"name": "Rally"
},
"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_validate_cert": true,
"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,
"alm_reference_context": 14
},
"inaccessible": false,
"connector": 2,
"project": 2
}Returns a specific ALM connection. The params are only displayed if you have the 'Edit ALM connections' permission.
GET /api/v2/connections/alm/{connection_id}/
Create an ALM Connection
POST /api/v2/connections/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"alias": "Example Connection",
"connector": 1,
"project": 1,
"frequency": "hourly",
"params":{
"alm_project": "Example Project",
"alm_parent_issue": "Parent"
}
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 5,
"alias": "Example Connection",
"system": {
"id": "jira":,
"name": "JIRA",
"short_name": "JIRA"
},
"frequency": "hourly",
"command": "sync_jira",
"params":{
"sde_project": "Project 1",
"alm_user": "Sindy",
"sde_verification_filter": "none,partial,pass,fail",
"jira_version": "5",
"alm_method": "https",
"alm_validate_cert": true,
"alm_title_format": "$task_id $title",
"alm_server": "bugs.server.co",
"sde_businessunit": "BU",
"sde_application": "Finance App",
"alm_project": "Example Project",
"alm_pass": "id",
"alm_parent_issue": "Parent",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7,
"alm_reference_context": 5
},
"inaccessible": false,
"connector": 1,
"project": 1
}| Fields | Required | Description |
|---|---|---|
| alias | Yes | The name of the new connection. |
| connector | Yes | The id of the connector that this connection will use to connect with the ALM. |
| project | Yes | The id of the SD Elements project that this connection will connect with. |
| frequency | No | The frequency in which this connection will sync. The available options for organizations with the advanced ALM feature are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually". Organizations without the advanced ALM feature can only choose "manually". |
| params | Yes | A dictionary containing connections options. Please refer to product documentation for more details or reach out to support. |
Update a specific ALM Connection
PUT /api/v2/connections/alm/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"alias": "Example Connection Updated Name",
"connector": 1,
"project": 1,
"frequency": "manually",
"params": {"alm_project": "Project Name"}
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 5,
"alias": "Example Connection Updated Name",
"system": {
"id": "jira",
"name": "JIRA"
},
"frequency": "manually",
"command": "sync_jira",
"params":{
"sde_project": "Project 1",
"alm_user": "Sindy",
"sde_verification_filter": "none,partial,pass,fail",
"jira_version": "5",
"alm_method": "https",
"alm_validate_cert": true,
"alm_title_format": "$task_id $title",
"alm_server": "bugs.server.co",
"sde_businessunit": "BU",
"sde_application": "Finance App",
"alm_project": "Project Name",
"alm_pass": "id",
"alm_parent_issue": "Parent",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7,
"alm_reference_context": 5
},
"inaccessible": false,
"connector": 1,
"project": 1
}Update a specific ALM Connection resource.
PUT /api/v2/connections/alm/{connection_id}/
URL Parameters
| Parameter | Description |
|---|---|
| connection_id | The ID of the ALM Connection to update |
ALM Plugins
Get all ALM Plugins
GET /api/v2/plugins/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id":"trac",
"name":"Trac",
"short_name":"Trac",
"command":"sync_trac",
"sections":[
{
"label":null,
"optional":false,
"fields":[
{
"name":"alm_project",
"label":"Trac Milestone",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":255,
"required":true,
"deprecated":false,
"placeholder":null,
"scope":[
"project"
],
"help_text":"",
"options":[
]
}
]
},
{
"label":"Connection Details",
"optional":false,
"fields":[
{
"name":"alm_method",
"label":"Protocol",
"description":"",
"field_type":"radio",
"default":"https",
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":"https",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"https",
"value":"https",
"disabled":false
},
{
"label":"http",
"value":"http",
"disabled":false
}
]
},
{
"name":"alm_server",
"label":"Server",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":"bugs.server.com",
"scope":[
"system"
],
"help_text":"",
"options":[
]
},
{
"name":"alm_context_root",
"label":"Context Root",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"/",
"scope":[
"system"
],
"help_text":"Normally left empty unless the service is installed at a non-standard location",
"options":[
]
}
]
},
{
"label":"Credentials",
"optional":false,
"fields":[
{
"name":"alm_user",
"label":"Trac Username",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":null,
"scope":[
"system"
],
"help_text":"",
"options":[
]
},
{
"name":"alm_pass",
"label":"Trac Password",
"description":"",
"field_type":"masked_string",
"default":null,
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":null,
"scope":[
"system"
],
"help_text":"",
"options":[
]
}
]
},
{
"label":"Synchronization",
"optional":true,
"fields":[
{
"name":"conflict_policy",
"label":"Choose Authoritative Source",
"description":"",
"field_type":"radio",
"default":"alm",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"alm",
"scope":[
"system"
],
"help_text":"The de facto source for the status of an SD Elements task",
"options":[
{
"label":"Trac",
"value":"alm",
"disabled":false
},
{
"label":"SD Elements",
"value":"sde",
"disabled":false
},
{
"label":"Last Status Change",
"value":"timestamp",
"disabled":true
}
]
},
{
"name":"how_tos_in_scope",
"label":"Include code sample How-To's in task descriptions",
"description":"",
"field_type":"boolean",
"default":false,
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"False",
"scope":[
"system"
],
"help_text":"",
"options":[
]
}
]
},
{
"label":"Tasks to Synchronize",
"optional":true,
"fields":[
{
"name":"sde_min_priority",
"label":"Tasks having a minimum priority",
"description":"",
"field_type":"select",
"default":"7",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"7",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"10 - High Minimum Priority to Import",
"value":"10",
"disabled":false
},
{
"label":"9",
"value":"9",
"disabled":false
},
{
"label":"8",
"value":"8",
"disabled":false
},
{
"label":"7",
"value":"7",
"disabled":false
},
{
"label":"6",
"value":"6",
"disabled":false
},
{
"label":"5 - Medium Minimum Priority to Import",
"value":"5",
"disabled":false
},
{
"label":"4",
"value":"4",
"disabled":false
},
{
"label":"3",
"value":"3",
"disabled":false
},
{
"label":"2",
"value":"2",
"disabled":false
},
{
"label":"1 - Low Minimum Priority to Import",
"value":"1",
"disabled":false
}
]
},
{
"name":"sde_statuses_in_scope",
"label":"Tasks with status",
"description":"",
"field_type":"checkbox",
"default":"TODO",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"TODO",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"Done",
"value":"DONE",
"disabled":false
},
{
"label":"Todo",
"value":"TODO",
"disabled":false
},
{
"label":"N/A",
"value":"NA",
"disabled":false
}
]
},
{
"name":"alm_phases",
"label":"Tasks having phase",
"description":"",
"field_type":"checkbox",
"default":"requirements,architecture-design,development",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"requirements,architecture-design,development",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"Requirements",
"value":"requirements",
"disabled":false
},
{
"label":"Architecture & Design",
"value":"architecture-design",
"disabled":false
},
{
"label":"Development",
"value":"development",
"disabled":false
},
{
"label":"Testing",
"value":"testing",
"disabled":false
}
]
},
{
"name":"sde_tags_filter",
"label":"Tasks having all of the following tags",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"tag1,tag2",
"scope":[
"system"
],
"help_text":"",
"options":[
]
},
{
"name":"sde_verification_filter",
"label":"Tasks with verification status",
"description":"",
"field_type":"checkbox",
"default":"none,partial,pass,fail",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"none,partial,pass,fail",
"scope":[
"system"
],
"help_text":"Filter tasks based on their verification status",
"options":[
{
"label":"No Status",
"value":"none",
"disabled":false
},
{
"label":"Partial Pass",
"value":"partial",
"disabled":false
},
{
"label":"Pass",
"value":"pass",
"disabled":false
},
{
"label":"Fail",
"value":"fail",
"disabled":false
}
]
}
]
}
]
}
]
}This endpoint retrieves a list of ALM Integration Plugin resources.
Get a Specific ALM Plugin
GET /api/v2/plugins/alm/trac/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id":"trac",
"name":"Trac",
"short_name":"Trac",
"command":"sync_trac",
"sections":[
{
"label":null,
"optional":false,
"fields":[
{
"name":"alm_project",
"label":"Trac Milestone",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":255,
"required":true,
"deprecated":false,
"placeholder":null,
"scope":[
"project"
],
"help_text":"",
"options":[
]
}
]
},
{
"label":"Connection Details",
"optional":false,
"fields":[
{
"name":"alm_method",
"label":"Protocol",
"description":"",
"field_type":"radio",
"default":"https",
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":"https",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"https",
"value":"https",
"disabled":false
},
{
"label":"http",
"value":"http",
"disabled":false
}
]
},
{
"name":"alm_server",
"label":"Server",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":"bugs.server.com",
"scope":[
"system"
],
"help_text":"",
"options":[
]
},
{
"name":"alm_context_root",
"label":"Context Root",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"/",
"scope":[
"system"
],
"help_text":"Normally left empty unless the service is installed at a non-standard location",
"options":[
]
}
]
},
{
"label":"Credentials",
"optional":false,
"fields":[
{
"name":"alm_user",
"label":"Trac Username",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":null,
"scope":[
"system"
],
"help_text":"",
"options":[
]
},
{
"name":"alm_pass",
"label":"Trac Password",
"description":"",
"field_type":"masked_string",
"default":null,
"readonly":false,
"max_length":null,
"required":true,
"deprecated":false,
"placeholder":null,
"scope":[
"system"
],
"help_text":"",
"options":[
]
}
]
},
{
"label":"Synchronization",
"optional":true,
"fields":[
{
"name":"conflict_policy",
"label":"Choose Authoritative Source",
"description":"",
"field_type":"radio",
"default":"alm",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"alm",
"scope":[
"system"
],
"help_text":"The de facto source for the status of an SD Elements task",
"options":[
{
"label":"Trac",
"value":"alm",
"disabled":false
},
{
"label":"SD Elements",
"value":"sde",
"disabled":false
},
{
"label":"Last Status Change",
"value":"timestamp",
"disabled":true
}
]
},
{
"name":"how_tos_in_scope",
"label":"Include code sample How-To's in task descriptions",
"description":"",
"field_type":"boolean",
"default":false,
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"False",
"scope":[
"system"
],
"help_text":"",
"options":[
]
}
]
},
{
"label":"Tasks to Synchronize",
"optional":true,
"fields":[
{
"name":"sde_min_priority",
"label":"Tasks having a minimum priority",
"description":"",
"field_type":"select",
"default":"7",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"7",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"10 - High Minimum Priority to Import",
"value":"10",
"disabled":false
},
{
"label":"9",
"value":"9",
"disabled":false
},
{
"label":"8",
"value":"8",
"disabled":false
},
{
"label":"7",
"value":"7",
"disabled":false
},
{
"label":"6",
"value":"6",
"disabled":false
},
{
"label":"5 - Medium Minimum Priority to Import",
"value":"5",
"disabled":false
},
{
"label":"4",
"value":"4",
"disabled":false
},
{
"label":"3",
"value":"3",
"disabled":false
},
{
"label":"2",
"value":"2",
"disabled":false
},
{
"label":"1 - Low Minimum Priority to Import",
"value":"1",
"disabled":false
}
]
},
{
"name":"sde_statuses_in_scope",
"label":"Tasks with status",
"description":"",
"field_type":"checkbox",
"default":"TODO",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"TODO",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"Done",
"value":"DONE",
"disabled":false
},
{
"label":"Todo",
"value":"TODO",
"disabled":false
},
{
"label":"N/A",
"value":"NA",
"disabled":false
}
]
},
{
"name":"alm_phases",
"label":"Tasks having phase",
"description":"",
"field_type":"checkbox",
"default":"requirements,architecture-design,development",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"requirements,architecture-design,development",
"scope":[
"system"
],
"help_text":"",
"options":[
{
"label":"Requirements",
"value":"requirements",
"disabled":false
},
{
"label":"Architecture & Design",
"value":"architecture-design",
"disabled":false
},
{
"label":"Development",
"value":"development",
"disabled":false
},
{
"label":"Testing",
"value":"testing",
"disabled":false
}
]
},
{
"name":"sde_tags_filter",
"label":"Tasks having all of the following tags",
"description":"",
"field_type":"string",
"default":null,
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"tag1,tag2",
"scope":[
"system"
],
"help_text":"",
"options":[
]
},
{
"name":"sde_verification_filter",
"label":"Tasks with verification status",
"description":"",
"field_type":"checkbox",
"default":"none,partial,pass,fail",
"readonly":false,
"max_length":null,
"required":false,
"deprecated":false,
"placeholder":"none,partial,pass,fail",
"scope":[
"system"
],
"help_text":"Filter tasks based on their verification status",
"options":[
{
"label":"No Status",
"value":"none",
"disabled":false
},
{
"label":"Partial Pass",
"value":"partial",
"disabled":false
},
{
"label":"Pass",
"value":"pass",
"disabled":false
},
{
"label":"Fail",
"value":"fail",
"disabled":false
}
]
}
]
}
]
}This endpoint retrieves a specific ALM Integration Plugin resource, as specified by the id parameter.
GET /api/v2/phases/{alm_id}/
URL Parameters
| Parameter | Description |
|---|---|
| alm_id | The id of the alm plugin to retrieve |
Analysis Connections
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": {
"id": "fortify",
"name": "Fortify"
},
"inaccessible": false
}]
}Returns a list of all analysis connectors available.
GET /api/v2/connectors/analysis/
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": {
"id": "fortify",
"name": "Fortify"
},
"inaccessible": false
}Returns a specific analysis connector.
GET /api/v2/connectors/analysis/{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,
"connector": 1,
"project": 1,
"system": {
"id": "whitehat",
"name": "WhiteHat"
},
"alias": "WhiteHat Integration",
"frequency": "manually",
"command": "sync_whitehat",
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
},
"inaccessible": false
}]
}Returns a list of all analysis connections associated with all projects. The params are only displayed if you have the 'Edit security tool connections' permission.
GET /api/v2/connections/analysis/
Include Parameters
GET /api/v2/connections/analysis/?include=last_job HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"connector": 1,
"project": 1,
"system": "WhiteHat",
"alias": "WhiteHat Integration",
"frequency": "manually",
"command": "sync_whitehat",
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
},
inaccessible": false
"last_job": {
"id": 4,
"last_run": "2016-12-15T22:45:27.412Z",
"automatic": false,
"ready": true,
"result_message": "Error Message",
"succeeded": false,
"user": 1
}
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| last_job | Include the details of the last job executed for this connection. |
Get a Specific Analysis Connection
GET /api/v2/connections/analysis/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"connector": 1,
"project": 1,
"system": {
"id": "whitehat",
"name": "WhiteHat"
},
"alias": "WhiteHat Integration",
"frequency": "manually",
"command": "sync_whitehat",
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
},
"inaccessible": false
}Returns a specific analysis connection. The params are only displayed if you have the 'Edit security tool connections' permission.
GET /api/v2/connections/analysis/{connection_id}/
Create an Analysis Connection
POST /api/v2/connections/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"alias": "Example Analysis Connection",
"connector": 2,
"project": 1,
"frequency": "daily",
"params": {
"task_status_mapping": "{\"pass\": \"DONE\"}",
"import_behaviour": "combine"
}
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 9,
"connector": 2,
"alias": "Example Analysis Connection",
"system": {
"id": "veracode",
"name": "Veracode"
},
"project": 1,
"frequency": "daily",
"command": "import_veracode",
"params":{
"integration_mode": "api",
"analysis_user": "Code",
"analysis_pass": "Name",
"sde_businessunit": "BU",
"sde_application": "Financial App",
"sde_project": "Example Project",
"analysis_server": "vera",
"task_status_mapping": "{\"pass\": \"DONE\"}",
"import_behaviour": "combine",
"analysis_method": "http"
},
"inaccessible": false
}Only remote analysis connections can be created via the api.
| Fields | Required | Description |
|---|---|---|
| alias | No | The name of the new connection. Will default to the name of the connector. |
| connector | Yes | The id of the connector that this connection will use to connect with the ALM. |
| project | Yes | The id of the SD Elements project that this connection will connect with. |
| frequency | No | The frequency in which this connection will sync. The available options for organizations with the advanced ALM feature are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually". Organizations without the advanced ALM feature can only choose "manually". |
| params | Yes | A dictionary containing connections options. Please refer to product documentation for more details or reach out to support. |
Update a specific Analysis Connection
PUT /api/v2/connections/analysis/2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"alias": "Example Analysis Connection Updated Name",
"connector": 2,
"project": 1,
"frequency": "hourly",
"params": {}
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 9,
"connector": 2,
"alias": "Example Analysis Connection Updated Name",
"system": {
"id": "veracode",
"name": "Veracode"
},
"project": 1,
"frequency": "hourly",
"command": "import_veracode",
"params":{
"integration_mode": "api",
"analysis_user": "Code",
"analysis_pass": "Name",
"sde_businessunit": "BU",
"sde_application": "Financial App",
"sde_project": "Example Project",
"analysis_server": "vera",
"task_status_mapping": "",
"import_behaviour": "replace-scanner",
"analysis_method": "http"
},
"inaccessible": false
}Update a specific Analysis Connection resource.
PUT /api/v2/connections/analysis/{connection_id}/
URL Parameters
| Parameter | Description |
|---|---|
| connection_id | The ID of the Analysis Connection to update |
Analysis Notes
Get All Analysis Notes
GET /api/v2/projects/1936/tasks/1-T2/analysis-notes/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 875,
"analysis_session": 334,
"analysis_type": {
"slug": "manual",
"name": "Manual Verification"
},
"behaviour": "replace",
"confidence": "high",
"created": "2015-03-26T19:50:46.348000Z",
"findings": {},
"finding_ref": "my_ref",
"status": "pass",
"automatic": true,
"updated": "2015-06-05T02:55:54.231254Z",
"updater": {
"id": 599,
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith"
}
}]
}This endpoint returns a list of Analysis Note resources for a specific project task.
GET /api/v2/projects/{project_id}/tasks/{task_id}/analysis-notes/
Get a Specific Analysis Note
GET /api/v2/projects/1936/tasks/1-T2/analysis-notes/682/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 875,
"analysis_session": 334,
"analysis_type": {
"slug": "manual",
"name": "Manual Verification"
},
"behaviour": "replace",
"confidence": "high",
"created": "2015-03-26T19:50:46.348000Z",
"findings": {},
"finding_ref": "my_ref",
"status": "pass",
"automatic": true,
"updated": "2015-06-05T02:55:54.231254Z",
"updater": {
"id": 599,
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith"
}
}This endpoint returns a specific Analysis Note resource.
GET /api/v2/projects/{project_id}/tasks/{task_id}/analysis-notes/{note_id}/
Create an Analysis Note
POST /api/v2/project/1/tasks/1-T12/analysis-notes/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"analysis_session": 334,
"behaviour": "replace",
"confidence": "high",
"findings": {},
"finding_ref": "my_ref",
"status": "pass"
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 875,
"analysis_session": 334,
"analysis_type": {
"slug": "manual",
"name": "Manual Verification"
},
"behaviour": "replace",
"confidence": "high",
"created": "2015-03-26T19:50:46.348000Z",
"findings": {},
"finding_ref": "my_ref",
"status": "pass",
"automatic": true,
"updated": "2015-06-05T02:55:54.231254Z",
"updater": {
"id": 599,
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith"
}
}This endpoint creates a single Analysis Note resource.
POST /api/v2/projects/{project_id}/tasks/{task_id}/analysis-notes/
| Fields | Required | Description |
|---|---|---|
| analysis_session | No | The ID of the related Analysis Session. Not required if this is a manual verification. |
| behaviour | Yes | See Behaviour section below. |
| confidence | Yes | "high" or "low" |
| findings | Yes | JSON object/array representing analysis findings |
| finding_ref | No | |
| status | Yes | "pass", "partial", "fail", or "none" |
| task_status_mapping | No | See Task Status Mapping section below. |
| automatic | No | Whether the Task Note was posted by a tool. Default is false. |
Behaviour
| Value | Description |
|---|---|
| combine | Combine with all previous results |
| replace-scanner | Overwrite previous results from this tool |
| replace | Overwrite all previous result |
Task Status Mapping
You can provide an object that maps Analysis Note statuses to Task Statuses.
SD Elements will then use this mapping object to automatically change the status of the associated task based on the status of the Analysis Note.
The object format is:
{ "<note_status>": "<task_status_slug>", ...etc... }
An example:
{ "pass": "DONE", "fail": "TODO" }
Analysis Sessions
Get All Analysis Sessions
GET /api/v2/projects/1/analysis-sessions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 682,
"analysis_ref": "zero.webappsecurity.com",
"analysis_type": "webinspect",
"extra": {},
"created": "2014-12-15T20:10:51.900775Z",
"updated": "2014-12-15T20:10:51.900775Z",
"updater": 1
}]
}This endpoint returns a list of Analysis Session resources.
GET /api/v2/projects/{project_id}/analysis-sessions/
Get a Specific Analysis Session
GET /api/v2/projects/1/analysis-sessions/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 682,
"analysis_ref": "zero.webappsecurity.com",
"analysis_type": "webinspect",
"extra": {},
"created": "2014-12-15T20:10:51.900775Z",
"updated": "2014-12-15T20:10:51.900775Z",
"updater": 1
}This endpoint returns a specific Analysis Session resource.
GET /api/v2/projects/{project_id}/analysis-sessions/{analysis_session_id}/
Create an Analysis Session
POST /api/v2/projects/1/analysis-sessions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"analysis_ref": "zero.webappsecurity.com",
"analysis_type": "webinspect"
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 1,
"analysis_ref": "zero.webappsecurity.com",
"analysis_type": "webinspect",
"extra": {},
"created": "2014-12-15T20:10:51.900775Z",
"updated": "2014-12-15T20:10:51.900775Z",
"updater": 1
}This endpoint creates an Analysis Session resource.
POST /api/v2/projects/{project_id}/analysis-sessions/
| Fields | Required | Description |
|---|---|---|
| analysis_ref | Yes | Arbitrary string used as a session identifier |
| analysis_type | Yes | Enum that identifies the type of analysis tool. Can be one of the following:
|
| notes | No | An array of Analysis Note resources. See Create an Analysis Note for what fields are supported/required. The "task" attribute field is required, but "analysis_session" is not required. |
Create an Analysis Session with embedded Notes
POST /api/v2/projects/1/analysis-sessions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"analysis_ref": "zero.webappsecurity.com",
"analysis_type": "webinspect",
"notes": [
{
"task": "1-T6",
"behaviour": "replace",
"confidence": "high",
"findings": {},
"finding_ref": "my_ref",
"status": "pass"
}
]
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 682,
"analysis_ref": "zero.webappsecurity.com",
"analysis_type": "webinspect",
"extra": {},
"created": "2014-12-15T20:10:51.900775Z",
"updated": "2014-12-15T20:10:51.900775Z",
"updater": 1
}API Tokens
Generate an API Token
POST /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "1234567890abcdefghijklmnopqrstuvwxyz",
"connection_string": "1234567890abcdefghijklmnopqrstuvwxyz@example.com"
}This endpoint returns a newly generated API Token. If the user already has a token, it will be regenerated.
Note: This endpoint only uses either basic or session authentication.
POST /api/v2/users/{user_id}/api-token/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to retrieve |
Regenerate an API Token
PUT /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "1234567890abcdefghijklmnopqrstuvwxyz",
"connection_string": "1234567890abcdefghijklmnopqrstuvwxyz@example.com"
}This endpoint revokes and then regenerates an API Token.
Note: This endpoint only uses either basic or session authentication.
PUT /api/v2/users/{user_id}/api-token/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to retrieve |
Get an API Token
GET /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "***********************************vwxyz",
"connection_string": "***********************************vwxyz@example.com"
}This endpoint retrieves the users API Token. For security reasons the token will be obfuscated. If you have lost your token you will have to regenerate it.
Note: This endpoint only uses either basic or session authentication.
GET /api/v2/users/{user_id}/api-token/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to retrieve |
Revoke an API Token
DELETE /api/v2/users/{user_id}/api-token/ HTTP/1.1
Accept: application/json
Authorization: Basic "YOUR BASE64 ENCODING OF USERNAME:PASSWORD"
Cookie: sessionid="YOUR SESSION ID"HTTP/1.1 204 NO CONTENTThis endpoint revokes the users current API Token. Only admin users can revoke API Tokens of other users.
Note: This endpoint only uses either basic or session authentication.
DELETE /api/v2/users/{user_id}/api-token/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to retrieve |
Applications
Get All Applications
GET /api/v2/applications/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"business_unit": {
"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",
"tags": ["foo", "bar"]
}]
}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. |
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": {
"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",
"tags": ["foo", "bar"]
}]
}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",
"tags": ["foo", "bar"],
"projects": [
{
"id": "1",
"name": "Project 1",
"slug": "project-1",
"url": "http://example.com/bunits/test-bu/application-test/project-1/"
},
{
"id": "2",
"name": "Project 2",
"slug": "project-2",
"url": "http://example.com/bunits/test-bu/application-test/project-2/"
}
]
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| projects | Includes a list of projects associated with an application |
Get a Specific Application
GET /api/v2/applications/3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"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",
"tags": ["foo", "bar"]
}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
{
"id": 3,
"business_unit": {
"id": 1,
"slug": "example-business-unit-1",
"name": "example 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",
"tags": []
}| 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' |
| tags | No | List of application tags. |
Update an Application
PATCH /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
{
"id": 1,
"business_unit": {
"id": 2,
"slug": "example-business-unit-2",
"name": "example 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",
"tags": ["foo", "bar"]
}Update a single application by specifying a new name and new business unit. The application to update is identified by the id.
PATCH /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' |
| tags | No | List of application tags. |
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,
"role": {
id: "UR1",
name: "User"
}
}],
"groups": [{
"id": "G64",
"name": "Group Bar"
}],
"all_users": false
},
{
"id": 2,
"slug": "example-business-unit-2",
"name": "example business unit 2",
"created": "2015-09-30T19:30:25.254036Z",
"updated": "2015-09-30T19:30:25.254072Z",
"default_users": [],
"default_groups": [],
"users": [],
"groups": [],
"all_users": true,
"persist_phases": false
}
]
}This endpoint retrieves a list of Business Unit resources, respecting the permissions of the user who has made the request.
GET /api/v2/business-units/
Query Parameters
The following parameters may be used to filter the business unit resources in the response.
| Parameter | Description |
|---|---|
| name | Filter business units by name. |
| ordering | Sort business units by the specified field. Prefix field name with minus to sort descending. Sortable fields: name. |
| search | Filter applications by performing a textual search on name. |
Get a Specific Business Unit
GET /api/v2/business-units/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"slug": "example-business-unit-1",
"name": "example business unit 1",
"created": "2015-09-30T18:28:37.214914Z",
"updated": "2015-09-30T18:28:37.214959Z",
"default_groups": [],
"default_users": [],
"users": [{
"id": 682,
"email": "frank@sdelements.com",
"first_name": "Frank",
"last_name": "Testerton",
"is_active": true,
"role": {
id: "UR1",
name: "User"
}
}],
"groups": [{
"id": "G64",
"name": "Group Bar"
}],
"all_users": false,
"persist_phases": false
}This endpoint retrieves a specific Business Unit resource, as specified by the id parameter.
GET /api/v2/business-units/{business_unit_id}/
URL Parameters
| Parameter | Description |
|---|---|
| business_unit_id | The id of the Business Unit to retrieve. |
Create a New Business Unit
POST /api/v2/business-units/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "API Test",
"users": [{"email": "test@example.com"}],
"groups": [{"id": "G1"}],
"default_users": [{"email": "test@example.com", "role": "PR4"}],
"default_groups": [{"id": "G1", "role": "PR4"}],
"all_users": false,
"persist_phases": false
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 541,
"slug": "api-test",
"name": "API Test",
"created": "2015-09-30T18:28:37.214914Z",
"updated": "2015-09-30T18:28:37.214959Z",
"users": [{
"id": 1,
"email": "test@example.com",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"role": {
id: "UR1",
name: "User"
}
}],
"groups": [{
"id": "G1"
}],
"default_users": [{
"email": "test@example.com",
"role": "PR4",
"id": 1,
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true
}],
"default_groups": [{
"id": "G1",
"role": "PR4"
}],
"all_users": false,
"persist_phases": false
}| Fields | Required | Description |
|---|---|---|
| name | Yes | The name of the new business unit. |
| users | No | A list of dictionaries representing the users who are part of the business unit. Each dictionary has an email field. |
| groups | No | A list of dictionaries representing the groups which are part of the business unit. Each dictionary has an id field which is the group id. |
| default_users | No | A list of dictionaries representing the default user roles for the users in the business unit. Each dictionary has an email field and a role field where the role is the role id. The users specified here should be members of the business unit unless all_users is true. |
| default_groups | No | A list of dictionaries representing the default group roles for the users in the business unit. Each dictionary has an id field which is the group id and a role field where the role is the role id. The groups specified here should be members of the business unit unless all_users is true. |
| all_users | No | Whether the business unit includes all users. Trying to create a business unit with this field set to True and specific users/groups specified is an error. Default is false. |
| persist_phases | No | Set the persistence of TODO tasks that belong to active phases in a project within this business unit. |
Update a Business Unit
PUT /api/v2/business-units/36/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "New BU Name"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 36,
"slug": "api-test",
"name": "New BU Name",
"created": "2015-09-30T18:28:37.214914Z",
"updated": "2015-09-30T18:28:37.214959Z",
"users": [{
"email": "test@example.com",
"id": 1,
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"role": {
id: "UR1",
name: "User"
}
}],
"groups": [{
"id": "G1"
}],
"default_users": [{
"email": "test@example.com",
"role": "PR4",
"id": 1,
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true
}],
"default_groups": [{
"id": "G1",
"role": "PR4"
}],
"all_users": false,
"persist_phases": false
}Update a single business unit by specifying the id. The fields users, groups, name, default_users, and default_groups can be updated.
PUT /api/v2/business-units/{business_unit_id}/
URL Parameters
| Parameter | Description |
|---|---|
| business_unit_id | The id of the Business Unit to update. |
Delete a Business Unit
DELETE /api/v2/business-units/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 204 NO 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. |
Global Roles
Get All Global Roles
GET /api/v2/global-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "UR4",
"name": "Administrator",
"description": "An administrator can create new..."
},
{
"id": "UR5",
"name": "No Role",
"description": "This role confers no permissions."
},
{
"id": "UR2",
"name": "Project Lead",
"description": "A project lead has permission to..."
},
{
"id": "UR1",
"name": "User",
"description": "A regular SD Elements user has..."
}
]
}This endpoint returns a list of Global Role resources.
Get a Specific Global Role
GET /api/v2/global-roles/UR4/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "UR4",
"name": "Administrator",
"description": "An administrator can create new..."
}This endpoint returns a specific Global Role resource as specified by the id parameter.
GET /api/v2/global-roles/{global_role_id}/
URL Parameters
| Parameter | Description |
|---|---|
| global_role_id | The id of the Global Role to retrieve |
Create a New Global Role
POST /api/v2/global-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "Global Role",
"description": "Can participate in projects.",
"inherit_from": "UR1"
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "CUR1",
"name": "Global Role",
"description": "Can participate in projects.",
"permissions": [
"modify_self"
],
"is_default": false
}POST /api/v2/global-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "New Global Role",
"description": "Can create new applications and projects.",
"permissions": [
"add_project",
"add_application"
],
"is_default": true
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "CUR2",
"name": "New Global Role",
"description": "Can create new applications and projects.",
"permissions": [
"add_project",
"add_application"
],
"is_default": true
}| Fields | Required | Description |
|---|---|---|
| name | Yes | The name of the Global Role. |
| description | Yes | A description of the Global Role. |
| permissions | No | The permissions given to users who are assigned this Global Role. |
| inherit_from | No | If inherit_from field is passed, then the permissions field gets set with the permissions of the parent Global Role. |
| is_default | No | Passing is_default as True will set the newly created Global Role as default role for the current organization. |
Update a Global Role
PATCH /api/v2/global-roles/CUR2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"permissions": [
"archive_application",
"add_project",
"add_application"
],
"is_default": true
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CUR2",
"name": "New Global Role",
"description": "Can create new applications and projects.",
"permissions": [
"archive_application",
"add_project",
"add_application"
],
"is_default": true
}PATCH /api/v2/global-roles/{global_role_id}/
URL Parameters
| Parameter | Description |
|---|---|
| global_role_id | The id of the Global Role to update |
Payload
| Fields | Required | Description |
|---|---|---|
| name | No | The name of the Global Role. |
| description | No | Global Role description. |
| permissions | No | The permissions given to users who are assigned this Global Role. |
| is_default | No | Passing is_default as True will set the Global Role as default role for the current organization. |
Delete a Global Role
DELETE /api/v2/global-roles/CUR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"replacement": "UR1"
}HTTP/1.1 204 NO CONTENTDELETE /api/v2/global-roles/{global_role_id}/
URL Parameters
| Parameter | Description |
|---|---|
| global_role_id | The id of the Global Role to delete |
Payload
| Fields | Required | Description |
|---|---|---|
| replacement | Yes | The id of the Global Role to replace the one to be deleted. |
Glossary Terms
Get all Glossary Terms
GET /api/v2/glossary-terms/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "G2",
"title": "Use Notification",
"text": "<p>This is a type of notification or message that basically describes...</p>",
"summary": "<p>A message that notifies the users of their actions.</p>",
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
},
{
"id": "G3",
"title": "Unauthenticated part of application",
"text": "<p>An unauthenticated (or authentication-free) part of an application consists...</p>",
"summary": "<p>An unauthenticated (or authentication-free) part of an application is a public portion of an application.</p>",
"created": "2015-03-26T19:52:34.854000Z",
"updated": "2015-03-26T19:52:34.853000Z"
}
]
}This endpoint returns a list of Glossary Term resources.
Get a Specific Glossary Term
GET /api/v2/glossary-terms/G2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "G2",
"title": "Use Notification",
"text": "<p>This is a type of notification or message that basically describes...</p>",
"summary": "<p>A message that notifies the users of their actions.</p>",
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
}This endpoint returns a specific Glossary Term resource.
GET /api/v2/glossary-terms/{glossary_term_id}/
URL Parameters
| Parameter | Description |
|---|---|
| glossary_term_id | The id of the Glossary Term to retrieve |
Create a New Glossary Term
POST /api/v2/glossary-terms/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"title": "New Glossary Term",
"text": "Full description of the term goes here.",
"summary": "The summary of the glossary term goes here."
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "CG13",
"title": "New Glossary Term",
"text": "<p>This is the new glossary term for our API documentation example<p>",
"summary": "<p>Example POST glossary Term<p>",
"created": "2015-06-23T19:05:46.175048Z",
"updated": "2015-06-23T19:05:46.107520Z"
}This endpoint creates a new Glossary Term resource.
| Fields | Required | Description |
|---|---|---|
| text | Yes | |
| title | Yes | |
| summary | Yes |
Groups
Get All Groups
GET /api/v2/groups/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "G64",
"name": "Group 64",
"updated": "2016-07-29T21:02:33.764620Z",
"description": "Group description",
"role": "UR4"
}]
}This endpoint returns a list of Group resources.
GET /api/v2/groups/
Expand Parameters
GET /api/v2/groups/?expand=role
Accept: application/json
Authorization: Token: "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "G64",
"name": "Group 64",
"updated": "2016-07-29T21:02:19.780768Z",
"description": "Group description",
"role": {
"id": "UR1",
"name": "User"
}
}]
}See the Expand Parameters section for more details.
| Parameter | Description |
|---|---|
| role | Role field is expanded to include to id and name fields. |
Include Parameters
GET /api/v2/groups/?include=groups,users,all_users,total_user_count
Accept: application/json
Authorization: Token: "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "G64",
"name": "Group 64",
"updated": "2016-07-29T21:02:19.780768Z",
"description": "Group description",
"role": "UR4"
"users": [{
"first_name": "Frank",
"last_name": "Testerton",
"is_active": true,
"id": 2,
"email": "frank@example.com",
"role": {
"id": "UR1",
"name": "User"
}
}],
"groups": [{
role: "User",
id: "G1",
name: "Example Group"
}],
"total_user_count": 2,
"all_users": "users": [
{
"first_name": "Frank",
"last_name": "Testerton",
"is_active": true,
"id": 2,
"email": "frank@example.com",
"role": {
"id": "UR1",
"name": "User"
}
},
{
"first_name": "Linda",
"last_name": "Graham",
"is_active": false,
"id": 3,
"email": "linda@example.com",
"role": {
"id": "UR1",
"name": "User"
}
},
]
"sync_connections": ["LDAP Connection"]
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| groups | Includes a list of nested groups that are directly a member of the parent group |
| users | Includes a list of direct users a part of the group. |
| all_users | Include a list of direct and indirect users of the group. |
| total_user_count | Includes the total number of users (direct and indirect) in the group. |
| sync_connections | Includes a list of Sync Connections that include the group in their mappings |
Get a Specific Group
GET /api/v2/groups/G64/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "G64",
"name": "Group 64",
"updated": "2016-07-29T21:02:19.780768Z",
"description": "Group description",
"role": "UR4",
}This endpoint retreives a specific Group Resource as specified by the group_id.
GET /api/v2/groups/{group_id}/
URL Parameters
| Parameter | Description |
|---|---|
| group_id | The id of the Group to retrieve |
Create a Group
POST /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "Group 2",
"role": "UR5",
"users": [{"email": "frank@example.com"}],
"groups": ["G1"]
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "G2",
"name": "Group 2",
"updated": "2016-07-29T21:02:19.780768Z",
"description": "",
"role": "UR5",
"users": [{
"first_name": "Frank",
"last_name": "Testerton",
"is_active": true,
"id": 2,
"email": "frank@example.com",
"role": {
"id": "UR1",
"name": "User"
}
}],
"groups": [{
"role": "User",
"id": "G1",
"name": "Example Group"
}]
}Create a Group resource.
POST /api/v2/groups/
| Fields | Required | Description |
|---|---|---|
| name | Yes | The name of the group resource |
| description | No | The description of the group |
| role | Yes | The role of the group |
| users | No | A list of dictionaries representing the users who are part of the business unit. Each dictionary has an email field. |
| groups | No | A list of group ids representing the nested groups who are part of the parent group. |
Update a specific Group
PUT /api/v2/groups/G2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "User Experience Group",
"description": "Deals with designing user experiences"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "G2",
"name": "User Experience Group",
"updated": "2016-07-29T21:02:19.780768Z",
"description": "Deals with designing user experiences",
"role": "UR1"
"users": [{
"first_name": "Frank",
"last_name": "Testerton",
"is_active": true
"id": 2,
"email": "frank@example.com",
"role": {
"id": "UR1",
"name": "User"
}
}],
"groups": [{
"role": "User"
"id": "G1",
"name": "Example Group"
}]
}Update a specific Group resource.
PUT /api/v2/users/{group_id}/
URL Parameters
| Parameter | Description |
|---|---|
| group_id | The ID of the Group to update |
Delete a Group
DELETE api/v2/groups/G1/
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 204 NO 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": "admin@example.com",
"succeeded": true,
"automatic": true,
"ready": true,
"result_message": "",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 23,
"params": {
"sde_project": "Demo Project",
"alm_user": "rally_user",
"sde_verification_filter": "none,partial,pass,fail",
"rally_workspace": "Rally Workspace",
"alm_method": "https",
"alm_title_format": "$task_id $title",
"alm_server": "rally1.rallydev.com",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"alm_project": "Rally Project",
"alm_pass": "rally_password",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7
},
"project": 7,
"system": "Rally"
}
}]
}Returns a list of all alm jobs associated with all projects. Note that the params are only shown if you have 'Edit ALM connections' permission.
GET /api/v2/jobs/alm/
Query Parameters
The following parameters may be used to filter the ALM connections resources in the response.
| Parameter | Description |
|---|---|
| automatic | Returns all ALM jobs that were created automatically. |
| connection | Returns all ALM jobs that correspond to a specific connection. |
| ready | Returns all ALM jobs that have finished running, successfully or otherwise. |
| succeeded | Returns all ALM jobs that completed successfully. |
| user | Returns all ALM jobs created by the specified user. |
Get a Specific ALM Job
GET /api/v2/jobs/alm/{job_id} HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 12,
"user": "admin@example.com",
"succeeded": true,
"automatic": true,
"ready": true,
"result_message": "",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 23,
"params": {
"sde_project": "Demo Project",
"alm_user": "rally_user",
"sde_verification_filter": "none,partial,pass,fail",
"rally_workspace": "Rally Workspace",
"alm_method": "https",
"alm_title_format": "$task_id $title",
"alm_server": "rally1.rallydev.com",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"alm_project": "Rally Project",
"alm_pass": "rally_password",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7
},
"project": 7,
"system": "Rally"
}
}Returns a specific alm job. Note that the params are only shown if you have 'Edit ALM connections' permission.
GET /api/v2/jobs/alm/{job_id}
Post Results of an ALM Job of a Project
POST /api/v2/projects/1/jobs/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"connection": 12,
"result_message": "My Message",
"succeeded": true,
"automatic": true
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 12,
"user": "admin@example.com",
"succeeded": true,
"automatic": true,
"ready": true,
"result_message": "My Message",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 12,
"params": {
"sde_project": "Demo Project",
"alm_user": "rally_user",
"sde_verification_filter": "none,partial,pass,fail",
"rally_workspace": "Rally Workspace",
"alm_method": "https",
"alm_title_format": "$task_id $title",
"alm_server": "rally1.rallydev.com",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"alm_project": "Rally Project",
"alm_pass": "rally_password",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7
},
"project": 7,
"system": "Rally"
}
}Will submit the results of an ALM job.
POST /api/v2/jobs/alm/
| Fields | Required | Description |
|---|---|---|
| automatic | Yes | Whether the job was run automatically. |
| connection | Yes | The connection id associated with the job. |
| result_message | Yes | The result message of the job. |
| succeeded | Yes | Whether the job was run successfully. |
Initiate an ALM Connection Sync Job
POST /api/v2/projects/1/jobs/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"connection": 12,
"automatic": false,
"ready": false
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 12,
"user": "admin@example.com",
"succeeded": false,
"automatic": false,
"ready": false,
"result_message": "",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 12,
"params": {
"sde_project": "Demo Project",
"alm_user": "rally_user",
"sde_verification_filter": "none,partial,pass,fail",
"rally_workspace": "Rally Workspace",
"alm_method": "https",
"alm_title_format": "$task_id $title",
"alm_server": "rally1.rallydev.com",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"alm_project": "Rally Project",
"alm_pass": "rally_password",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7
},
"project": 7,
"system": "Rally"
}
}Will add a sync job to the queue to be run.
POST /api/v2/jobs/alm/
| Fields | Required | Description |
|---|---|---|
| automatic | Yes | Whether the job was run automatically. |
| connection | Yes | The connection id associated with the job. |
| ready | Yes | Whether the job is ready to post its result or not. This field must be set to "false" in order for the import to commence. |
| succeeded | No | Boolean Field. Use this along with the 'ready: true' to record when a job was successful/unsuccessful. |
Get All Analysis Jobs for All Projects
GET /api/v2/jobs/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 12,
"user": "admin@example.com",
"succeeded": true,
"automatic": true,
"ready": true,
"result_message": "",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 23,
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
},
"project": 7,
"system": "Whitehat"
}
}]
}Returns a list of all analysis jobs associated with all projects. Note that the params are only shown if you have 'Edit security tool connections' permission.
GET /api/v2/jobs/analysis/
Query Parameters
The following parameters may be used to filter the analysis connections resources in the response.
| Parameter | Description |
|---|---|
| automatic | Returns all Analysis jobs that were created automatically. |
| connection | Returns all Analysis jobs that correspond to a specific connection. |
| ready | Returns all Analysis jobs that have finished running, successfully or otherwise. |
| succeeded | Returns all Analysis jobs that completed successfully. |
| user | Returns all Analysis jobs created by the specified user. |
Get a Specific Analysis Job
GET /api/v2/jobs/analysis/{job_id} HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 12,
"user": "admin@example.com",
"succeeded": true,
"automatic": true,
"ready": true,
"result_message": "",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 23,
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
},
"project": 7,
"system": "Whitehat"
}
}Returns a specific analysis job. Note that the params are only shown if you have 'Edit security tool connections' permission.
GET /api/v2/jobs/analysis/{job_id}
Post Results of an Analysis Job of a Project
POST /api/v2/projects/1/jobs/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"connection": 12,
"result_message": "My Message",
"succeeded": true,
"automatic": true
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 12,
"user": "admin@example.com",
"succeeded": true,
"automatic": true,
"ready": true,
"result_message": "My Message",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 23,
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
},
"project": 7,
"system": "Whitehat"
}
}Will submit the results of an analysis job.
POST /api/v2/jobs/analysis/
| Fields | Required | Description |
|---|---|---|
| automatic | Yes | Whether the job was run automatically. |
| connection | Yes | The connection id associated with the job. |
| result_message | Yes | The result message of the job. |
| succeeded | Yes | Whether the job was run successfully. |
| ready | No | Whether the job is ready to post the result or not. Defaults to True. |
Initiate an Analysis Connection Import Job
POST /api/v2/projects/1/jobs/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"connection": 12,
"automatic": false,
"ready": false
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 12,
"user": "admin@example.com",
"succeeded": false,
"automatic": false,
"ready": false,
"result_message": "",
"last_run": "2015-04-15T20:27:24.396442Z",
"connection": {
"alias": "My Connection",
"command": "run_my_connection",
"frequency": "daily",
"id": 23,
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
},
"project": 7,
"system": "Whitehat"
}
}Will put the import job on the queue to be run.
POST /api/v2/jobs/analysis/
| Fields | Required | Description |
|---|---|---|
| automatic | Yes | Whether the job was run automatically. |
| connection | Yes | The connection id associated with the job. |
| ready | Yes | Whether the job is ready to post its result or not. This field must be set to "false" in order for the import to commence. |
| succeeded | No | Boolean Field. Use this along with the 'ready: true' to record when a job was successful/unsuccessful. |
Get All LDAP Jobs
GET /api/v2/jobs/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"automatic": false,
"connection": {
"id": 29,
"alias": "gg'",
"system": "LDAP",
"frequency": "manually",
"command": "sync_ldap",
"params": {
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "geneva.labs.sdelements.com:389",
"bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"deactivation": false,
"group_member_query": "(&(objectClass=user)(memberOf=%s))",
"page_size": 666,
"base_dn": "DC=labs,DC=sdelements,DC=com",
"group_mapping": {
"mathematicians": "group2",
"analyst": "group3",
"scientists": "group1"
},
"ldap_method": "LDAP",
"ldap_validate_cert": true
},
"inaccessible": false
},
"id": 57,
"last_run": "2017-01-05T18:38:42.604983Z",
"ready": true,
"result_message": "",
"succeeded": true,
"user": "admin@example.com"
}]
}Returns a list of all LDAP jobs. Note that the params are only shown if you have 'Edit security tool connections' permission.
GET /api/v2/jobs/ldap/
Query Parameters
The following parameters may be used to filter the analysis connections resources in the response.
| Parameter | Type | Description |
|---|---|---|
| automatic | Boolean | Returns all LDAP jobs that were created automatically. |
| connection | Integer | Returns all LDAP jobs that correspond to a specific connection. |
| ready | Boolean | Returns all LDAP jobs that have finished running, successfully or otherwise. |
| succeeded | Boolean | Returns all LDAP jobs that completed successfully. |
| user | Returns all LDAP jobs created by the specified user. |
Get a Specific LDAP Job
GET /api/v2/jobs/ldap/{job_id} HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"automatic": false,
"connection": {
"id": 29,
"alias": "gg'",
"system": "LDAP",
"frequency": "manually",
"command": "sync_ldap",
"params": {
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "geneva.labs.sdelements.com:389",
"bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"deactivation": false,
"group_member_query": "(&(objectClass=user)(memberOf=%s))",
"page_size": 666,
"base_dn": "DC=labs,DC=sdelements,DC=com",
"group_mapping": {
"mathematicians": "group2",
"analyst": "group3",
"scientists": "group1"
},
"ldap_method": "LDAP",
"ldap_validate_cert": true
},
"inaccessible": false
},
"id": 57,
"last_run": "2017-01-05T18:38:42.604983Z",
"ready": true,
"result_message": "",
"succeeded": true,
"user": 1
}Returns a specific LDAP job. Note that the params are only shown if you have 'Edit security tool connections' permission.
GET /api/v2/jobs/ldap/{job_id}
Post Results of an LDAP Job
POST /api/v2/jobs/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"connection": 29,
"result_message": "My Message",
"succeeded": true,
"automatic": true
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"automatic": false,
"connection": {
"id": 29,
"alias": "gg'",
"system": "LDAP",
"frequency": "manually",
"command": "sync_ldap",
"params": {
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "geneva.labs.sdelements.com:389",
"bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"deactivation": false,
"group_member_query": "(&(objectClass=user)(memberOf=%s))",
"page_size": 666,
"base_dn": "DC=labs,DC=sdelements,DC=com",
"group_mapping": {
"mathematicians": "group2",
"analyst": "group3",
"scientists": "group1"
},
"ldap_method": "LDAP",
"ldap_validate_cert": true
},
"inaccessible": false
},
"id": 57,
"last_run": "2017-01-05T18:38:42.604983Z",
"ready": true,
"result_message": "My Message",
"succeeded": true,
"user": 1
}Will submit the results of an LDAP job.
POST /api/v2/jobs/LDAP/
| Fields | Required | Type | Description |
|---|---|---|---|
| automatic | Yes | Boolean | Whether the job was run automatically. |
| connection | Yes | Integer | The connection id associated with the job. |
| result_message | Yes | String | The result message of the job. |
| succeeded | Yes | Boolean | Whether the job was run successfully. |
| ready | No | Boolean | Whether the job is ready to post the result or not. Defaults to True. |
Initiate an LDAP Connection Import Job
POST /api/v2/jobs/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"connection": 29,
"automatic": false,
"ready": false
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"automatic": false,
"connection": {
"id": 29,
"alias": "gg'",
"system": "LDAP",
"frequency": "manually",
"command": "sync_ldap",
"params": {
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "geneva.labs.sdelements.com:389",
"bind_dn": "CN=Bind User2,CN=Users,DC=labs,DC=sdelements,DC=com",
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"deactivation": false,
"group_member_query": "(&(objectClass=user)(memberOf=%s))",
"page_size": 666,
"base_dn": "DC=labs,DC=sdelements,DC=com",
"group_mapping": {
"mathematicians": "group2",
"analyst": "group3",
"scientists": "group1"
},
"ldap_method": "LDAP",
"ldap_validate_cert": true
},
"inaccessible": false
},
"id": 57,
"last_run": "2017-01-05T18:38:42.604983Z",
"ready": true,
"result_message": "",
"succeeded": true,
"user": "admin@example.com"
}Will put the import job on the queue to be run.
POST /api/v2/jobs/ldap/
| Fields | Required | Type | Description |
|---|---|---|---|
| automatic | Yes | Boolean | Whether the job was run automatically. |
| connection | Yes | Integer | The connection id associated with the job. |
| ready | Yes | Boolean | Whether the job is ready to post its result or not. This field must be set to "false" in order for the import to commence. |
| succeeded | No | Boolean | Use this along with the 'ready: true' to record when a job was successful/unsuccessful. |
LDAP Connections
Get LDAP Connections for the current organization
GET /api/v2/connections/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"results": [{
"id": 15,
"alias": "LDAP",
"system": "ldap",
"frequency": "manually",
"command": "sync_ldap",
"params": {
"ldap_filter": {
"users": [
"user@example.org",
"user2@example.org"
],
"groups": [
"LDAPGroup",
"LDAPGroup3"
]
},
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "ldapServer:12345",
"deactivate_groupless_users": false,
"deactivate_stale_users": false,
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
"bind_password": "qweASD123",
"base_dn": "dc=example,dc=org",
"group_mapping": {
"ldap_group2": "G2",
"ldap_group1": "G1"
},
"ldap_start_tls": false,
"ldap_validate_cert": true
},
"inaccessible": true
}]
}Returns a list of all LDAP integration connections in the current organization.
Note, this is different from the LDAP connection configured for Single Sign-On.
GET /api/v2/connections/ldap/
Include Parameters
GET /api/v2/connections/ldap/?include=last_job HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 15,
"alias": "LDAP",
"system": "ldap",
"frequency": "manually",
"command": "sync_ldap",
"params": {
"ldap_filter": {
"users": [
"user@example.org",
"user2@example.org"
],
"groups": [
"LDAPGroup",
"LDAPGroup3"
]
},
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "ldapServer:12345",
"deactivate_groupless_users": false,
"deactivate_stale_users": false,
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
"bind_password": "qweASD123",
"base_dn": "dc=example,dc=org",
"group_mapping": {
"ldap_group2": "G2",
"ldap_group1": "G1"
},
"ldap_start_tls": false,
"ldap_validate_cert": true
},
"inaccessible": true,
"last_job": {
"succeeded": false,
"last_run": "2016-12-15T22:45:27.412Z",
"result_message": "Error Message",
"user": 1,
"ready": true,
"automatic": false,
"id": 4
}
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| last_job | Include the details of the last job executed for this connection. |
Create an LDAP Connection
POST /api/v2/connections/ldap/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"alias": "LDAP",
"params": {
"ldap_server": "ldapServer:12345",
"group_mapping": {
"ldap_group1": "G1",
"ldap_group2": "G2"
},
"ldap_filter": {
"groups": ["LDAPGroup", "LDAPGroup3"],
"users": ["user@example.org", "user2@example.org"]
},
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"full_name": "cn",
"email": "mail"
},
"deactivate_groupless_users": false,
"deactivate_stale_users": false,
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
"base_dn": "dc=example,dc=org",
"bind_password": "pass",
"ldap_start_tls": true
}
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 15,
"alias": "LDAP",
"system": "ldap",
"frequency": "manually",
"command": "sync_ldap",
"params": {
"ldap_filter": {
"users": [
"user@example.org",
"user2@example.org"
],
"groups": [
"LDAPGroup",
"LDAPGroup3"
]
},
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "ldapServer:12345",
"deactivate_groupless_users": false,
"deactivate_stale_users": false,
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
"base_dn": "dc=example,dc=org",
"group_mapping": {
"ldap_group2": "G2",
"ldap_group1": "G1"
},
"ldap_start_tls": true,
"ldap_validate_cert": true
},
"inaccessible": false
}| Fields | Required | Description |
|---|---|---|
| alias | Yes | The name of the new connection. |
| frequency | No | The frequency in which this connection will sync. The available options are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually". |
| params | Yes | A dictionary containing connections options. Please refer to the table below |
| inaccessible | No | Is the connection inaccessible from the SDE server. Defaults to false. |
Params fields
| Fields | Required | Description |
|---|---|---|
| ldap_server | Yes | The address of the LDAP server. |
| ldap_start_tls | No | Determines whether or not to secure connection using TLS/SSL (defaults to True). |
| group_mapping | Yes | Object that maps LDAP group names to SDE group ids. |
| ldap_filter | No | Fine-grained control for users and groups during synchronization |
| ldap_validate_cert | No | Determines whether or not to validate the SSL certificate for the LDAP server (defaults to True). |
| user_schema | No | Define a custom user schema. |
| deactivate_groupless_users | No | Automatically deactivate SDE users that are not assigned to any groups (defaults to False). |
| deactivate_stale_users | No | Automatically deactivate SDE users not found in LDAP (defaults to False). |
| bind_dn | Yes | The bind dn |
| bind_password | Yes | The bind password |
| page_size | No | Number of users to return per page. (defaults to 1000) |
| group_member_query | No | Gives the users of the specified group |
| group_base_dn | Yes | Base DN of the LDAP groups to sync |
| base_dn | No | The base dn (will be computed from bind_dn if unspecified) |
Delete an LDAP Connection
DELETE /api/v2/connections/ldap/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO ContentThis endpoint deletes a single LDAP Connection resource, as specified by the id parameter.
DELETE /api/v2/connections/ldap/{connection_id}/
URL Parameters
| Parameter | Description |
|---|---|
| connection_id | The id of the LDAP Connection to delete. |
Update a specific LDAP Connection
PUT /api/v2/connections/ldap/31/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"alias": "Example Connection Updated Name",
"frequency": "daily",
"params": {
"ldap_filter": {
"users": [
"user@example.org",
"user2@example.org"
],
"groups": [
"LDAPGroup",
"LDAPGroup3"
]
},
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "ldapServer:12345",
"bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"deactivate_groupless_users": false,
"deactivate_stale_users": false,
"group_member_query": "(&(objectClass=user)(memberOf=%s))",
"page_size": 1000,
"bind_password": "pass",
"base_dn": "dc=example,dc=org",
"group_mapping": {
"group": "G1"
},
"ldap_start_tls": true,
"ldap_validate_cert": true
}
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 31,
"alias": "Example Connection Updated Name",
"system": "LDAP",
"frequency": "daily",
"command": "sync_ldap",
"params": {
"ldap_filter": {
"users": [
"user@example.org",
"user2@example.org"
],
"groups": [
"LDAPGroup",
"LDAPGroup3"
]
},
"group_base_dn": "OU=SyncGroups,DC=example,DC=com",
"ldap_server": "ldapServer:12345",
"bind_dn": "cn=Administrator,cn=Users,dc=example,dc=org",
"user_schema": {
"first_name": "gn",
"last_name": "sn",
"email": "mail",
"full_name": "cn"
},
"deactivate_groupless_users": false,
"deactivate_stale_users": false,
"group_member_query": "(&(objectClass=user)(memberOf=%s))",
"page_size": 1000,
"base_dn": "dc=example,dc=org",
"group_mapping": {
"group": "G1"
},
"ldap_start_tls": true,
"ldap_validate_cert": true
},
"inaccessible": false
}Update a specific LDAP Connection resource.
PUT /api/v2/connections/ldap/{connection_id}/
URL Parameters
| Parameter | Description |
|---|---|
| connection_id | The ID of the LDAP Connection to update |
| Fields | Required | Description |
|---|---|---|
| alias | Yes | The name of the new connection. |
| frequency | No | The frequency in which this connection will sync. The available options are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually". |
| params | Yes | A dictionary containing connections options. Please refer to the table below |
| inaccessible | No | Is the connection inaccessible from the SDE server. Defaults to false. |
Params fields
| Fields | Required | Description |
|---|---|---|
| ldap_server | Yes | The address of the LDAP server. |
| ldap_start_tls | No | Determines whether or not to secure connection using TLS/SSL (defaults to True). |
| group_mapping | Yes | Object that maps LDAP group names to SDE group ids. |
| ldap_filter | No | Fine-grained control for users and groups during synchronization |
| ldap_validate_cert | No | Determines whether or not to validate the SSL certificate for the LDAP server (defaults to True). |
| user_schema | No | Define a custom user schema. |
| deactivate_groupless_users | No | Automatically deactivate SDE users that are not assigned to any groups (defaults to False). |
| deactivate_stale_users | No | Automatically deactivate SDE users not found in LDAP (defaults to False). |
| bind_dn | Yes | The bind dn |
| bind_password | No | The bind password |
| page_size | No | Number of users to return per page. (defaults to 1000) |
| group_member_query | No | Gives the users of the specified group |
| group_base_dn | Yes | Base DN of the LDAP groups to sync |
| base_dn | No | The base dn (will be computed from bind_dn if unspecified) |
Library Tasks
Get All Library Tasks
GET /api/v2/library/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"priority": 8,
"url": "http://example.com/library/tasks/T179/",
"problem": "P1",
"title": "Allow access for users to remove their data from the system",
"text": "Some example description",
"phase": "X1",
"id": "T179"
}]
}This endpoint retrieves a list of Library Task resources.
GET /api/v2/library/tasks/
Query Parameters
The following parameters may be used to filter the library task resources in the response.
| Parameter | Description |
|---|---|
| priority | Given a priority 0-10, returns all tasks with specified priority |
Expand Parameters
GET /api/v2/library/tasks/?expand=problem HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"priority": 8,
"tags": [],
"url": "http://example.com/library/tasks/T179/",
"problem": {
"text": "This is some example content.",
"cwe": [{
"url": "http://cwe.mitre.org/data/definitions/359",
"title": "Exposure of Private Information ('Privacy Violation')",
"cwe_id": 359
}],
"id": "P257",
"title": "P257: Privacy Violation"
},
"title": "Allow access for users to remove their data from the system",
"text": "Some example description",
"phase": "X1",
"id": "T179"
}]
}See the Expand Parameters section for more details.
| Parameter | Description |
|---|---|
| problem | Expands the problem fields in the task response object |
Include Parameters
GET /api/v2/library/tasks/?include=verification_coverage,categories,tags,how_tos,amendments HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"priority": 8,
"tags": [1, 2, 3],
"url": "http://example.com/library/tasks/T179/",
"problem": "P1",
"title": "Allow access for users to remove their data from the system",
"text": "Some example description",
"phase": "X1",
"id": "T179",
"categories": [
"Authorization"
],
"amendments": [{
"id": "TA123",
"title": "TA123",
"text": "Some additional information about this task..."
}],
"verification_coverage": [
"No Automated Static Analysis Coverage"
],
"how_tos": [{
"id": "I131",
"title": "I131: Manually with browser",
"slug": "test-account-lockout-manually-browser",
"url": "http://a7069ccda519b00c4/....",
"text": "1. Open your web browser ..."
}]
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| amendments | Includes a list of amendments on each task |
| categories | Includes a list of categories that apply to each task |
| how_tos | Includes a list of How-Tos for each task. These are language specific examples of how to implement the task |
| tags | Includes a list of tags attached to each task |
| verification_coverage | Includes a list of verification coverages of each task |
Get a Specific Library Task
GET /api/v2/library/tasks/T3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"priority": 8,
"tags": [],
"url": "http://example.com/library/tasks/T3/",
"problem": "P1",
"title": "Example Library Task",
"text": "Some example description",
"phase": "X1",
"id": "T3"
}]
}This endpoint retrieves a single library task resource, as specified by the id parameter.
GET /api/v2/library/task/{task_id}/
URL Parameters
| Parameter | Description |
|---|---|
| task_id | The id of the task to retrieve |
All of the expand and include parameters for the 'Get All Library Tasks' endpoint apply here as well.
Library Problems
Get All Library Problems
GET /api/v2/library/problems/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"text": "This is some example description.",
"cwes": [359],
"id": "P257",
"title": "Privacy Violation",
"risk_rating": 5
}]
} This endpoint retrieves a list of Library Problem resources.
GET /api/v2/library/problems/
Query Parameters
The following parameters may be used to filter the library problem resources in the response.
| Parameter | Description |
|---|---|
| risk_rating | Given a risk rating 0-10, returns all problems with specified rating |
Include Parameters
GET /api/v2/library/problems/?include=related_tasks,category,cwe HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "P257",
"title": "Privacy Violation",
"text": "This is some example description.",
"risk_rating": 5,
"category": "XML and Web Services",
"cwe": [{
"url": "http://cwe.mitre.org/data/definitions/359",
"title": "Exposure of Private Information ('Privacy Violation')",
"id": 359
}],
"related_tasks": [{
"id": "CT1",
"title": "Example Task 1",
"priority": 10,
"text": "Example task solution",
"phase": "X1"
}]
}]
} See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| category | Includes the category that applies to each problem |
| cwe | Includes the list of CWEs that apply to each problem |
| related_tasks | Includes a list of tasks that relate to each problem |
Get a Specific Library Problem
GET /api/v2/library/problems/P3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"text": "This is some example description.",
"id": "P3",
"title": "Example Library Problem",
"risk_rating": 5
}]
} This endpoint retrieves a single library problem resource, as specified by the id parameter.
GET /api/v2/library/problems/{problem_id}/
URL Parameters
| Parameter | Description |
|---|---|
| problem_id | The id of the problem to retrieve |
All of the expand and include parameters for the 'Get All Library Problems' endpoint apply here as well.
Phases
Get All Phases
GET /api/v2/phases/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "X1",
"description": "Application security requirements, generally used to assist requirements analysts.",
"name": "Requirements",
"slug": "requirements",
"tip": "One-time tasks that you can verify. Similar to traditional functional requirements or user stories.",
"ordinal": 1,
"active": "true",
"is_custom": "true",
"retain": "true"
}
]
}This endpoint retrieves a list of Phase resources, which describe phases of a software development process.
GET /api/v2/phases/
Query Parameters
The following parameters may be used to filter the phases resources in the response.
| Parameter | Description |
|---|---|
| name | Returns the phase resource with specified name |
| slug | Returns the phase resource with the specified slug |
Get a Specific Phase
GET /api/v2/phases/X1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "X1",
"description": "Application security requirements, generally used to assist requirements analysts.",
"name": "Requirements",
"slug": "requirements",
"tip": "One-time tasks that you can verify. Similar to traditional functional requirements or user stories.",
"ordinal": 1,
"active": "true",
"is_custom": "true",
"retain": "true"
}This endpoint retrieves a specific Phase resource, as specified by the id parameter.
GET /api/v2/phases/{phase_id}/
URL Parameters
| Parameter | Description |
|---|---|
| phase_id | The id of the phase to retrieve |
Create a Phase
POST /api/v2/phases/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "New Phase",
"description": "description",
"tip": "tip",
"ordinal": 1,
"retain": "true"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CX1",
"name": "New Phase",
"slug": "new_phase",
"description": "description",
"tip": "tip",
"ordinal": 1,
"active": "true",
"is_custom": "true",
"retain": "true"
}This endpoint creates a new Phase resource.
POST /api/v2/phases/{phase_id}/
| Fields | Required | Description |
|---|---|---|
| name | Yes | The name of the phase. |
| description | Yes | The description of the phase. |
| tip | Yes | The tooltip for the phase. |
| ordinal | Yes | The order of the phase. |
| retain | No | Determines whether this phase carries over statuses and notes by default. |
Update a Phase
PUT /api/v2/phases/CX1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "Updated Requirements",
"description": "Updated Application security requirements",
"tip": "updated tip",
"ordinal": 1,
"retain": "true",
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CX1",
"name": "Updated Requirements",
"slug": "updated_requirements",
"description": "Updated Application security requirements",
"tip": "updated tip",
"ordinal": 1,
"active": "true",
"is_custom": "true",
"retain": "true"
}This endpoint updates a specific Phase resource, as specified by the id parameter.
PUT /api/v2/phases/{phase_id}/
| Fields | Required | Description |
|---|---|---|
| name | Yes | The name of the phase. |
| description | Yes | The description of the phase. |
| tip | Yes | The tooltip for the phase. |
| ordinal | Yes | The order of the phase. |
| retain | No | Determines whether this phase carries over statuses and notes by default. |
PATCH /api/v2/phases/{phase_id}/
| Fields | Required | Description |
|---|---|---|
| name | No | The name of the phase. |
| description | No | The description of the phase. |
| tip | No | The tooltip for the phase. |
| ordinal | No | The order of the phase. |
| retain | No | Determines whether this phase carries over statuses and notes by default. |
URL Parameters
| Parameter | Description |
|---|---|
| phase_id | The id of the phase to update |
Delete a Phase
DELETE /api/v2/phases/CX1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"replacement": "CX2"
}HTTP/1.1 204 NO CONTENT
Content-Type: application/json
{}This endpoint deletes a specific Phase resource, as specified by the id parameter.
DELETE /api/v2/phases/{phase_id}/
| Fields | Required | Description |
|---|---|---|
| replacement | Yes | The phase to move the tasks of the current phase to. |
URL Parameters
| Parameter | Description |
|---|---|
| phase_id | The id of the phase to delete |
Profiles
Get All Profiles
GET /api/v2/profiles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "P1",
"name": "No Profile",
"description": "An empty Profile",
"answers": ["A740"],
"logo_url": "/static/images/logo-other.png"
},
{
"id": "P3",
"name": ".NET Web App",
"description": "Microsoft .NET Web Application",
"answers":["A1061", "A740", "A48", "A4", "A2"],
"logo_url": "/static/images/logo-net.png"
}
]
}This endpoint retrieves a list of Profiles resources.
Query Parameters
| Parameter | Description |
|---|---|
| ordering | Returns a list of profile resources ordered by the specified field. This endpoint supports ordering by id, name and description. |
Project Roles
Get All Project Roles
GET /api/v2/project-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "PR4",
"name": "Manage Project",
"description": "Can change project survey, ...",
"permissions": [
"edit_project_membership",
"archive_project",
"lock_project_survey",
"write_task_note",
"verify_task",
"sync_with_alm",
"edit_project_survey",
"edit_project_details",
"assign_task",
"mark_task",
"view_project",
"create_project_specific_task"
]
},
{
"id": "PR5",
"name": "Normal",
"description": "Can view project and update task statuses",
"permissions": [
"verify_task",
"mark_task",
"view_project",
"write_task_note"
]
},
{
"id": "PR6",
"name": "Read Only",
"description": "Can view project, but not modify it",
"permissions": [
"view_project"
]
}
]
}This endpoint returns a list of Project Role resources.
URL Parameters
| Parameter | Description |
|---|---|
| ordering | Sort project roles by the specified field. Prefix field name with minus to sort descending. Sortable fields: name. |
| search | Filter project roles by performing a textual search on name. |
Get a Specific Project Role
GET /api/v2/project-roles/CPR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CPR1",
"name": "Custom Role",
"description": "Can view project.",
"permissions": [
"view_project"
]
}This endpoint returns a specific Project Role resource, specified by its id.
GET /api/v2/project-roles/{project_role_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_role_id | The id of the Project Role to retrieve. |
Create a New Project Role
POST /api/v2/project-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "New Project Role",
"description": "Can view project!",
"inherit_from": "PR6"
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "CPR3",
"name": "New Project Role",
"description": "Can view project!",
"permissions": [
"view_project"
]
}POST /api/v2/project-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "New Project Role",
"description": "Can view project!",
"permissions": [
"view_project"
]
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "CPR3",
"name": "New Project Role",
"description": "Can view project!",
"permissions": [
"view_project"
]
}| Fields | Required | Description |
|---|---|---|
| name | Yes | The name of the Project Role. |
| description | Yes | A description of the Project Role. |
| permissions | No | The permissions given to users who are assigned this Project Role. |
| inherit_from | No | If inherit_from field is passed, then the permissions field gets set with the permissions of the parent Project Role. |
Update a Project Role
PATCH /api/v2/project-roles/CPR3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"permissions": ["view_project", "archive_project"]
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CPR3",
"name": "New Project Role",
"description": "Can view project!",
"permissions": [
"view_project",
"archive_project"
]
}PATCH /api/v2/project-roles/{project_role_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_role_id | The id of the Project Role to update |
Payload
| Fields | Required | Description |
|---|---|---|
| name | No | The name of the Project Role. |
| description | No | Project Role description. |
| permissions | No | The permissions given to users who are assigned this Project Role. |
Delete a Project Role
DELETE /api/v2/project-roles/CPR1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"replacement": "PR1"
}HTTP/1.1 204 NO CONTENTDELETE /api/v2/project-roles/{project_role_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_role_id | The id of the Project Role to delete |
Payload
| Fields | Required | Description |
|---|---|---|
| replacement | Yes | The id of the Project Role to replace the one to be deleted. |
Project Survey
Get the project survey of a project
GET /api/v2/projects/1/survey/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [
"A21",
"A493"
],
"survey_complete": true
}This endpoint returns data relevant to the profile for the current project
GET /api/v2/projects/{project_id}/survey/
Expand Filters
GET /api/v2/projects/1/survey/?expand=answers HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [
{
"id": "A21",
"cpe": "cpe:/question/answer",
"text": "",
"selected_by": [],
"question": "Q100"
}
],
"survey_complete": true
}See the Expand Parameters section for more details.
| Parameter | Description |
|---|---|
| answers | answers in answers field are expanded to include id, cpe, text, selected_by |
Project Survey Draft
Get the current state of the project survey draft
GET /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [{
"id": "A21",
"selected": false,
"valid": true
}, ...],
"survey_complete": true,
"dirty": false
}Returns the current state of the survey draft. All non-hidden answers are returned along with whether they are selected and whether they are valid for the current survey state. Dirty is a boolean representing whether the current draft state is different from the last saved survey.
GET /api/v2/projects/{project_id}/survey/draft/
Include Filters
GET /api/v2/projects/1/survey/draft/?include=survey HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [{
"id": "A21",
"selected": false,
"valid": true
}, ...],
"survey_complete": true,
"dirty": false,
"survey": {
"sections": [{
"id": "S1",
"title": "Application Survey",
"slug": "application-survey",
"subsections": [{
"id": "Q1",
"title": "Programming Language",
"questions": [{
"id": "Q21",
"text": "Is this a question?",
"description": "Help text",
"format": "MC", // SC for single choice, else MC
"mandatory": false,
"satisfied": true,
"subquestions": [{
"mandatory": false,
"description: "",
"format: "MC",
"text: "Sub Question?",
"satisfied": true,
"answers": [{
"description": "Description 1",
"text": "Answer 1",
"selected": false,
"selected_by": [ ],
"valid": true,
"id": "A11"
}, {
"description": "Description 2",
"text": "Answer 2",
"selected": false,
"selected_by": [ ],
"valid": true,
"id": "A12"
}],
id: "Q216"
}],
"answers": [{
"id": "A21",
"text": "Yes",
"description": "Help text",
"selected": false,
"valid": true,
"selected_by": []
}, ...]
}, ...]
}, ...]
}, ...]
}
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| survey | Includes a full representation of the survey structure with metadata |
Reset the draft
DELETE /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [{
"id": "A21",
"selected": false,
"valid": true
}, ...],
"survey_complete": true,
"dirty": false,
}Reverts changes to the draft to the last saved state.
DELETE /api/v2/projects/{project_id}/survey/draft/
Save the draft
POST /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [{
"id": "A21",
"selected": false,
"valid": true
}, ...],
"survey_complete": true,
"dirty": false,
}This saves the current changes to the draft to the project. This may cause changes in the applicable tasks & other content for the project as well as accepting any other unaccepted changes to the tasks.
POST /api/v2/projects/{project_id}/survey/draft/
Modify an answer in the draft
PUT /api/v2/projects/1/survey/draft/A21/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{"selected": true}HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [{
"id": "A21",
"selected": true,
"valid": true
}, ...],
"survey_complete": true,
"dirty": true
}Modifies the specified answer in the draft and returns the full draft state. This may affect other answer's selected and valid values.
PUT /api/v2/projects/{project_id}/survey/draft/{answer_id}/
| Field | Required | Description |
|---|---|---|
| selected | Yes | Selects or unselects the specified answer |
Clone a profile to the draft
PUT /api/v2/projects/1/survey/draft/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{"profile": "P21"}HTTP/1.1 200 OK
Content-Type: application/json
{
"answers": [{
"id": "A21",
"selected": true,
"valid": true
}, ...],
"survey_complete": true,
"dirty": true
}Clears the current draft and uses the answers set on the specified profile for the draft instead. Any unsaved changes will be lost.
PUT /api/v2/projects/{project_id}/survey/draft/
| Field | Required | Description |
|---|---|---|
| profile | Yes | Profile id of profile to clone from |
Project Activities
Get Activities associated with a Project
This endpoint returns a list of Activities associated with a Project. Activities are events that have occurred in the application. The date the event occurred and some additional data is returned.
GET /api/v2/projects/{project_id}/activities/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project to retrieve the activities of. |
GET /api/v2/projects/{project_id}/activities/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
count: 3,
next: null,
previous: null,
results: [
{
id: 4278,
name: "ModifiedProjectActivity",
actor: 1,
text: "Admin Testerton modified project 123444321443 in application Flipism",
date: "2016-10-31T19:43:23.648726Z",
data: {
project_desc: "123444321443",
application_desc: "Flipism",
project: 11,
application: 5,
business_unit: 1,
business_unit_desc: "Test BU"
},
icon: "modify",
log_level: "modify"
},
{
id: 4271,
name: "CreatedProjectActivity",
actor: 1,
text: "Admin Testerton created project 123444321 in application Flipism",
date: "2016-10-31T19:20:13.887289Z",
data: {
project_desc: "123444321",
application_desc: "Flipism",
project: 11,
application: 5,
business_unit: 1,
business_unit_desc: "Test BU"
},
icon: "createProject",
log_level: "create"
},
{
id: 4270,
name: "AddedUserToProjectActivity",
actor: 1,
text: "Admin Testerton added Admin Testerton to project 123444321 in application Flipism",
date: "2016-10-31T19:20:12.570855Z",
data: {
project_desc: "123444321",
application_desc: "Flipism",
project: 11,
application: 5,
business_unit: 1,
user: "U1",
user_desc: "Admin Testerton",
business_unit_desc: "Test BU"
},
icon: "personAdd",
log_level: "user"
}
]
}Projects
Get All Projects
GET /api/v2/projects/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1936,
"slug": "project-test",
"url": "http://example.com/bunits/bu-test/app-test/project-test",
"application": 1280,
"profile" : {
"id": "P9",
"name": "Android App",
"logo_url": "/static/images/android.png"
},
"archived": false,
"name": "Project Test",
"creator": 1,
"description": "API Project",
"tags": ["foo", "bar"],
"application_tags": ["baz", "qux"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"parent": {
"id": 8,
"slug": "parent-984-gamma",
"name": "Parent 9.8.4 Gamma",
"url": "http://example.com/bunits/bu-test/app-test/parent-984-gamma/"
},
"base_project": {
"id": 10,
"name": "base 9.8.4 Gamma",
"slug": "base-984-gamma",
"url": "http://example.com/bunits/bu-test/app-test/base-984-gamma/"
},
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}],
"custom_attributes": {
"slug": "value"
},
"locked_on": null,
"locked_by": null,
"locked": false
}]
}This endpoint retrieves a list of Project resources.
GET /api/v2/projects/
Query Parameters
The following parameters may be used to filter the project resources in the response.
| Parameter | Description |
|---|---|
| application | Filter projects by Application ID. |
| name | Filter projects by name. |
| slug | Filter projects by slug. |
| ordering | Sort projects by the specified field. Prefix field name with minus to sort descending. Sortable fields: name, created, updated. |
| search | Filter projects by performing a textual search on name and profile name. |
Include Parameters
GET /api/v2/projects/1/?include=permissions,task_counts,incomplete_tasks 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"],
"application_tags": ["baz", "qux"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"parent": null,
"base_project": 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"
],
"incomplete_tasks": {
"high": 38,
"medium": 60,
"low": 11
},
"task_counts": {
"Requirements": {
"total": 28,
"complete": 4,
"slug": "requirements"
},
"Architecture & Design": {
"total": 6,
"complete": 1,
"slug": "architecture-design"
},
"Development": {
"total": 30,
"complete": 5,
"slug": "development"
},
"Testing": {
"total": 57,
"complete": 2,
"slug": "testing"
}
},
"locked_on": null,
"locked_by": null,
"locked": false
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| permissions | Includes a list of permissions the requesting user has for the project |
| task_counts | Includes counts of tasks broken down by phase, priority and completeness for the project. Priorities are: high (7-10), medium (4-6), low (1-3). |
Expand Parameters
GET /api/v2/projects/?expand=creator HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1936,
"slug": "project-test",
"url": "http://example.com/bunits/bu-test/app-test/project-test",
"application": 1280,
"profile" : {
"id": "P9",
"name": "Android App",
"logo_url": "/static/images/android.png"
},
"archived": false,
"name": "Project Test",
"creator": {
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true
},
"description": "API Project",
"tags": ["foo", "bar"],
"application_tags": ["baz", "qux"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"parent": null,
"base_project": 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"],
"application_tags": ["baz", "qux"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"parent": null,
"base_project": null,
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}],
"custom_attributes": {
"slug": "value"
},
"locked_on": null,
"locked_by": null,
"locked": false
}This endpoint retrieves a specific Project resource, as specified by the id parameter.
GET /api/v2/projects/{project_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project to retrieve |
Create a New Project
POST /api/v2/projects/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"application": 1280,
"name": "API Test",
"profile": "P9",
"users": [{"email": "test@example.com", "role": "PR4"}],
"groups": [{"id": "G1", "role": "PR4"}]
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 1936,
"slug": "project-test",
"url": "http://example.com/bunits/bu-test/app-test/project-test",
"application": 1280,
"profile" : {
"id": "P9",
"name": "Android App",
"logo_url": "/static/images/android.png"
},
"archived": false,
"name": "Project Test",
"creator": 1,
"description": "API Project",
"tags": [],
"application_tags": [],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"parent": null,
"base_project": 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"],
"application_tags": ["baz", "qux"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-07-23T15:52:14.482992Z",
"parent": null,
"base_project": null,
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}],
"custom_attributes": {
"slug": "value"
},
"locked_on": "2016-06-01T14:39:45.083334Z",
"locked_by": 1,
"locked": true
}Update a single project by specifying a new name and a new application. The project to update is identified by the id.
PATCH /api/v2/projects/{project_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project to update |
Payload
| Fields | Required | Description |
|---|---|---|
| locked | No | A boolean field to lock or unlock the project. It can only be used by users that have lock_project_survey permission |
| application | No | The ID of the application the project should be created under. |
| profile | No | The ID of the desired profile for the project. |
| archived | No | A boolean to archive and unarchive a project. |
| name | No | The name of the project. |
| description | No | Project description. |
| tags | No | List of project tags. |
| parent | No | ID, name, slug, and URL of the parent project. |
| base_project | No | ID, name, slug, and URL of the original project. |
| users | No | A list of dictionaries per user that are to be assigned to the project. Each dictionary should contain the user's email and the desired role. |
| groups | No | A list of dictionaries per group that are to be assigned to the project. Each dictionary should contain the group's id and the desired role. |
Delete a Project
DELETE /api/v2/projects/10/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 204 NO 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/
Single Sign On
Test LDAP Connection Bind
POST /api/v2/sso/ldap/connection-test/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"server_uri": "ldaps://ldap.server.com:777",
"bind_dn": "CN=Bind User,CN=Users,DC=server,DC=com",
"bind_password": "Password1",
"start_tls": false
}HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"details": ""
}Performs a simple connection bind and query test against the LDAP server.
POST /api/v2/sso/ldap/connection-test/
| Fields | Required | Description |
|---|---|---|
| server_uri | Yes | The URI of the LDAP server. |
| bind_dn | No | The distinguished name to use when binding to the LDAP server. Leave blank for anonymous bind. |
| bind_password | No | The password used with the bind DN. Leave blank for anonymous bind. |
| start_tls | No | If checked, each connection to the LDAP server will enable TLS encryption over the standard LDAP port. |
Test LDAP User Authentication
POST /api/v2/sso/ldap/authentication-test/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"server_uri": "ldaps://ldap.server.com:777",
"bind_dn": "CN=Bind User,CN=Users,DC=server,DC=com",
"bind_password": "Password1",
"start_tls": true,
"username": "john@server.com",
"password": "password",
"base_dn": "DC=server,DC=com",
"scope": 2,
"search_filter": "(mail=%(user)s)"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"details": ""
}Tests user authentication against an LDAP server from the SDE instance.
POST /api/v2/sso/ldap/authentication-test/
| Fields | Required | Description |
|---|---|---|
| server_uri | Yes | The URI of the LDAP server. |
| bind_dn | No | The distinguished name to use when binding to the LDAP server. Leave blank for anonymous bind. |
| bind_password | No | The password used with the bind DN. Leave blank for anonymous bind. |
| start_tls | No | If checked, each connection to the LDAP server will enable TLS encryption over the standard LDAP port. |
| username | Yes | The username/email of the authenticating user. |
| password | Yes | The password of the authenticating user. |
| base_dn | Yes | The DN within which to search for the user. |
| scope | No | The scope of the search. A numerical value from 0 to 2 where 0 = base, 1 = one-level and 2 = subtree. |
| search_filter | Yes | Used by SD Elements to look-up users on the LDAP server. Should almost always be '(mail=%(user)s)'. |
Tags
Get all tags
GET /api/v2/tags/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"name": "important"
},
{
"name": "deployment"
},
{
"name": "my_tag"
}]
}This endpoint returns a list of Tag resources.
GET /api/v2/tags/
Tasks
Get all tasks of a project
GET /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"phase": "Requirements",
"manually_added_from_library": false,
"project_specific": false,
"relevant": true,
"accepted": true,
"assigned_to": [],
"updated": "2015-06-16T19:37:44.710100Z",
"updater": 7,
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": null,
"status": "TS2",
"note_count": 0,
"artifact_proxy": null
}]
}This endpoint returns a list of Task resources associated with the project having id "project_id".
GET /api/v2/projects/{project_id}/tasks/
Expand Parameters
GET /api/v2/projects/1/tasks/?expand=description,status,text,updater HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": {
"description": "Insecure forgotten password and password reset...",
"amendments": []
},
"priority": 8,
"phase": "Requirements",
"manually_added_from_library": false,
"project_specific": false,
"relevant": true,
"accepted": true,
"assigned_to": [],
"updated": "2015-06-16T19:37:44.710100Z",
"updater": {
"first_name": "Hamish",
"last_name": "Stout",
"is_active": true,
"email": "hamish.stout@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 7
},
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": null,
"status": {
"id": "TS2",
"meaning": "TODO",
"icon": "clock-o",
"name": "Incomplete",
"slug": "TODO"
},
"note_count": 0,
"artifact_proxy": null
}]
}See the Expand Parameters section for more details.
| Parameter | Description |
|---|---|
| description | Description field is expanded into content and amendments sub-fields. |
| status | Status field is expanded into id, meaning, icon, name and slug sub-fields. |
| phase | Phase field is expanded into id, name, slug, description and tip sub-fields. |
| updater | Updater field is expanded into id, first name, last name, email, role, and active status sub-fields. |
Include Parameters
GET /api/v2/projects/1/tasks/?include=tags,related,problem,how_tos,references,training HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"phase": "Requirements",
"manually_added_from_library": false,
"project_specific": false,
"relevant": true,
"accepted": true,
"assigned_to": [],
"updated": "2015-06-16T19:37:44.710100Z",
"updater": 7,
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": null,
"status": "TS2",
"note_count": 0,
"artifact_proxy": null,
"tags": ["tag1", "tag2"],
"related": [
{
"id": "T227",
"phase": "Testing",
"title": "Verify that application's access to database is restricted",
"url": "http://example.com/bunits/test-bu/codebot/bug-fix-81028-rc3/tasks/phase/testing/2-T227"
},
{
"id": "T14",
"phase": "Architecture & Design",
"title": "Enforce the Principle of Least Privilege",
"url": "http://example.com/bunits/test-bu/codebot/bug-fix-81028-rc3/tasks/phase/architecture-design/2-T14"
}
],
"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": [
{
"description": "Denial of service (DoS) protection and working in a degraded mode during DoS attacks.",
"id": "RS1026",
"name": "CR2.7 (L3 and higher)",
"regulation_id": "CR45",
"regulation_name": "ANSI/ISA 62443-4-2"
},
{
"description": "Denial of service (DoS) protection and working in a degraded mode during DoS attacks.",
"id": "RS642",
"name": "SR2.7 (L3 and higher)",
"regulation_id": "CR39",
"regulation_name": "ANSI/ISA 62443-3-3"
}
],
"references": [
{
"id": 10,
"alm_connection": 1,
"reference": "47300",
"name": "US451",
"link": "https://sdetest.atlassian.net/rest/api/2/issue/47300"
}
],
"training": [
{
"title": "OWASP Top 10 2013",
"id": "TR1",
"modules": [
{
"title": "Cross-site request forgery (CSRF)",
"id": "M5",
"link": "/static/05_CSRF/story_html5.html?tincan=true&endpoint=%2Ftincan%2F&enrollment_id=1",
"completed": false
},
{
"title": "Broken authentication and session management",
"id: "M7",
"link": "/static/07_Broken_Auth/story_html5.html?tincan=true&endpoint=%2Ftincan%2F&enrollment_id=1",
"completed": true
}
},
{
"title": "Development",
"id": "TR6",
"modules": [
{
"title": "Software Development, Operation, Maintenance & Disposal",
"id: "M8",
"link": "/static/08_Software_dev/story_html5.html?tincan=true&endpoint=%2Ftincan%2F&enrollment_id=1",
"completed": true
}
]
}
]
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| how_tos | Includes a list of applicable how-tos |
| problem | Includes the problem that the task is related to |
| related | Includes a list of related tasks |
| tags | Includes a list of tags associated to the task |
| regulation_sections | Includes a list of regulation sections to which this task belongs |
| references | Includes a list of task references linked to this task |
| training | Includes a list of training courses/modules linked to this task |
Filter Parameters
GET /api/v2/projects/1/tasks/?accepted=true&relevant=false HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"phase": "Requirements",
"manually_added_from_library": false,
"project_specific": false,
"relevant": false,
"accepted": true,
"assigned_to": [],
"updated": "2015-06-16T19:37:44.710100Z",
"updater": 7,
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": null,
"status": "TS2",
"note_count": 0,
"artifact_proxy": null,
}]
}Tasks can be filtered by their relevance and whether or not they have been accepted into a project by a project lead. If no filters are passed, we default to returning accepted tasks to match with the list shown in the web application.
| Parameter | Expected values | Description |
|---|---|---|
| accepted | true | false | Return the accepted/unaccepted tasks |
| relevant | true | false | Return the relevant/irrelevant tasks |
Get a Specific Task
GET /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"accepted": true,
"manually_added_from_library": false,
"project_specific": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"text": "Insecure forgotten password.",
"id": "1-T2",
"library_task_created": "2010-10-20T17:46:50Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "Requirements",
"priority": "8",
"relevant": true,
"status": "TS2",
"task_id": "T2",
"title": "Secure forgotten password",
"updated": "2015-07-08T02:16:33.923315Z",
"updater": 7,
"url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
"verification_status": null
}This endpoint retrieves a single Task resource, as specified by the id parameter.
GET /api/v2/projects/{project_id}/tasks/{task_id}/
Create a New Project Specific Task
POST /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"artifact_proxy": "ABC-XYZ",
"assigned_to": ["admin@example.com"],
"phase": "X1",
"priority": 9,
"status": "TS1",
"text": "Task Description",
"title": "Project Specific Task"
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"accepted": true,
"manually_added_from_library": false,
"project_specific": true,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"text": "Task Description",
"id": "1-PT1",
"library_task_created": "2015-05-07T18:58:26.732000Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "X1",
"priority": "9",
"relevant": true,
"status": "TS1",
"task_id": "PT1",
"title": "Project Specific Task",
"updater": 7,
"updated": "2015-05-07T18:58:26.732000Z",
"url": "http://example.com/.../1-PT1",
"verification_status": null
}Creates a new Task resource that is project-specific.
POST /api/v2/projects/{project_id}/tasks/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the project the new task belongs to |
Payload
| Fields | Required | Description |
|---|---|---|
| artifact_proxy | No | Arbitrary string which identifies a synchronized ALM issue |
| assigned_to | No | A list of emails for users that belong to the project |
| phase | Yes | The id of a phase |
| priority | Yes | The priority value from 0-10 |
| status | No | The id of a status |
| text | Yes | The description of the new task |
| title | Yes | The title of the new task |
Create a new Task from an existing Library Task
POST /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"task_id": "T21"
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"accepted": true,
"manually_added_from_library": true,
"project_specific": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"text": "Task Description",
"id": "1-T21",
"library_task_created": "2015-05-07T18:58:26.732000Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "X1",
"priority": "8",
"relevant": false,
"status": "TS1",
"task_id": "T21",
"title": "Ensure Confidential Data Is Sent Over an Encrypted Channel",
"updater": 7,
"updated": "2015-05-07T18:58:26.732000Z",
"url": "http://example.com/.../1-T21",
"verification_status": null
}Add a Library Task to a project. Only library tasks that aren't applicable to a project can be added.
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 |
| status | No | The id of a status |
| task_id | Yes | The id of the library task to add to the project. |
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,
"manually_added_from_library": false,
"project_specific": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"text": "Insecure forgotten password.",
"id": "1-T2",
"library_task_created": "2010-10-20T17:46:50Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "X1",
"priority": "8",
"relevant": true,
"status": "TS1",
"task_id": "T2",
"title": "Secure forgotten password",
"updated": "2015-07-08T02:16:33.923315Z",
"updater": 7,
"url": "http://example.com/.../1-T2",
"verification_status": null
}Updates a single Task resource, as specified by the project and task id parameters.
PATCH /api/v2/projects/{project_id}/tasks/{id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the project this task belongs to |
| id | The id of the task to modify |
Payload
| Fields | Required | Description |
|---|---|---|
| artifact_proxy | No | Arbitrary string which identifies a synchronized ALM issue |
| assigned_to | No | A list of emails for users that belong to the project |
| phase | No | The id of a phase. Available only if the updated task is a project specific task. |
| priority | No | The priority value from 0-10. Available only if the updated task is a project specific task. |
| status | No | The id of a status |
| text | No | The description of the task. Available only if the updated task is a project specific task. |
| title | No | The title of the task. Available only if the updated task is a project specific task. |
Delete a Task
DELETE /api/v2/projects/{project_id}/tasks/{id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 204 NO CONTENTDelete a single Task resource, as specified by the project and task id parameters.
Only manually added library tasks and project specific tasks may be deleted.
DELETE /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 delete |
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": {
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR4",
"name": "Administrator"
},
"id": 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": {
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR4",
"name": "Administrator"
},
"id": 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": {
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR4",
"name": "Administrator"
},
"id": 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": {
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR4",
"name": "Administrator"
},
"id": 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"
}
],
"password_reset_in_progress": false
}]
}This endpoint returns a list of User resources.
GET /api/v2/users/
Get a Specific User
GET /api/v2/users/599/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 599,
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
"last_login": "2015-06-05T02:55:54.231254Z",
"date_joined": "2015-06-05T02:55:54.231254Z",
"is_active": true,
"is_superuser": false,
"role": "No Role",
"groups": [],
"password_reset_in_progress": false
}This endpoint returns a specific User resource.
GET /api/v2/users/{user_id}/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to retrieve |
Get the Current User
GET /api/v2/users/me/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
}This endpoint returns the current User resource.
Update the Current User
PUT /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
}HTTP/1.1 200 OK
Content-Type: application/json
{
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
}Update the current User resource. Note: only users with "Manage users & groups" can change email addresses.
PUT /api/v2/users/me/
| Fields | Required | Description |
|---|---|---|
| No | User's email | |
| first_name | No | First name of the user |
| last_name | No | Last name of the user |
Create a User
POST /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
"role": "UR5",
"groups": ["G1", "G2"]
}HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 599,
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
"last_login": "2015-09-29T18:52:41.247207Z",
"date_joined": "2015-09-29T18:52:41.247207Z",
"is_active": true,
"is_superuser": false,
"role": "UR5",
"groups": [
{
"id": "G1",
"name": "Group1",
"role": "Project Lead"
},
{
"id": "G2",
"name": "Group2",
"role": "No Role"
}
],
"password_reset_in_progress": true
}Create a User resource.
POST /api/v2/users/
| Fields | Required | Description |
|---|---|---|
| Yes | User's email | |
| first_name | Yes | First name of the user |
| last_name | Yes | Last name of the user |
| role | No | Id of the role to add user to |
| groups | No | Ids of the groups to add user to |
Update a specific User
PUT /api/v2/users/599/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
"groups": ["G2"],
"role": "UR2"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 599,
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
"last_login": "2015-06-05T02:55:54.231254Z",
"date_joined": "2015-06-05T02:55:54.231254Z",
"is_active": true,
"is_superuser": false,
"role": "UR2",
"groups": [
{
"id": "G2",
"name": "Group2",
"role": "No Role"
}
],
"password_reset_in_progress": true
}Update a specific User resource.
PUT /api/v2/users/{user_id}/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to update |
Get Password Reset Info
GET /api/v2/users/1/reset-password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"expiry_date": "2016-09-30T14:51:55.889Z",
"reset_url": "http://example.com/accounts/new-password/12e33fbfc0f5774"
}This endpoint returns the password reset information for a specific user. This endpoint only uses either basic or session authentication.
Note: If the returned fields are null, then there is no password reset in progress.
GET /api/v2/users/{user_id}/reset-password/
Reset Password
POST /api/v2/users/1/reset-password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OKRequest a password reset for a specific user.
POST /api/v2/users/{user_id}/reset-password/
Change Password
POST /api/v2/users/me/password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"current_password": "hunter2",
"new_password": "superstrongpassword123"
}HTTP/1.1 200 OK
{"last_password_change":"2016-12-14T18:47:04.544Z"}Changes the password for the current user.
This endpoint only uses either basic or session authentication.
POST /api/v2/users/me/password/
Get Password Metadata
GET /api/v2/users/me/password/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
{"last_password_change":"2016-12-14T18:47:04.544Z"}Gets metadata regarding the password for the current user.
This endpoint only uses either basic or session authentication.
GET /api/v2/users/me/password/
Get Password Reset Questions
GET /api/v2/users/me/password-reset-questions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"last_modified": "2017-01-24T22:23:23.448047Z",
"questions": [
{
"id": 1,
"question": "What was your childhood nickname?"
},
{
"id": 2,
"question": "What is the street name of the house you grew up in?"
},
{
"id": 3,
"question": "What is your mothers middle name?"
}
]
}Get the password reset questions for the current user. Note: answers will not be returned.
GET /api/v2/users/me/password-reset-questions/
Change Password Reset Questions
PATCH /api/v2/users/me/password-reset-questions/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"current_password": "superstrongpassword123",
"questions": [
{
"question": "What was your childhood nickname?",
"answer": "Hunter2"
},
{
"question": "What is the street name of the house you grew up in?",
"answer": "Younge"
},
{
"question": "What is your mothers middle name?",
"answer": "Jane"
}
]
}HTTP/1.1 200 OK
{
"last_modified": "2017-01-24T22:23:23.448047Z",
"questions": [
{
"id": 1,
"question": "What was your childhood nickname?"
},
{
"id": 2,
"question": "What is the street name of the house you grew up in?"
},
{
"id": 3,
"question": "What is your mothers middle name?"
}
]
}Changes the password reset questions for the current user.
Note: Any existing question not included will be overwritten. To exclude a question from being overwritten/deleted, include it without a new answer.
PATCH /api/v2/users/me/password-reset-questions/
User Profile
Get User Profile
GET /api/v2/users/me/profile/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"plaintext_emails_only": false,
"notify_on_task_status_changed": true,
"notify_on_task_note_added": true,
"notify_on_job_failed": true,
"notify_on_new_relevant_tasks_in_project": true,
"notify_on_task_assigned": true,
"notify_on_task_added_to_project": true,
"notify_on_task_team_changed": true,
"notify_tasks": [{
"id": "T514",
"name": "Prevent formula injection in CSV Excel"
},{
"id": "T506",
"name": "Verify that iOS in-app purchases are securely implemented"
}]
}This endpoint returns the profile data of the current user.
GET /api/v2/users/me/profile/
Update User Profile
PATCH /api/v2/users/me/profile/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
Content-Type: application/json
{
"plaintext_emails_only": false,
"notify_on_task_status_changed": false,
"notify_on_task_note_added": false,
"notify_on_job_failed": true,
"notify_on_new_relevant_tasks_in_project": true,
"notify_on_task_assigned": true,
"notify_on_task_added_to_project": true,
"notify_on_task_team_changed": true,
"notify_tasks": ["T514"]
}HTTP/1.1 200 OK
Content-Type: application/json
{
"plaintext_emails_only": false,
"notify_on_task_status_changed": true,
"notify_on_task_note_added": true,
"notify_on_job_failed": true,
"notify_on_new_relevant_tasks_in_project": true,
"notify_on_task_assigned": true,
"notify_on_task_added_to_project": true,
"notify_on_task_team_changed": true,
"notify_tasks": [{
"id": "T514",
"name": "Prevent formula injection in CSV Excel in 0"
}]
}Update the current user's profile.
PATCH /api/v2/users/me/profile/
User Activities
Get all activities
GET /api/v2/users/me/activities/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 23,
"actor": 7,
"name": "MarkedTaskActivity",
"text": "Cindy Lu marked T21: Ensure confidential data is sent over an encrypted channel as Complete in project proj1 of application app1",
"date": "2016-05-11T18:53:02.216545Z",
"data":{
"status": "TS1",
"project_desc": "proj1",
"application_desc": "app1",
"status_desc": "Complete",
"standard": "T21",
"standard_desc": "T21: Ensure confidential data is sent over an encrypted channel",
"task_desc": "T21: Ensure confidential data is sent over an encrypted channel",
"business_unit_desc": "Example BU"
},
"icon" : "check",
"log_level": ""
},
{
"id": 20,
"name": "AddedUserToProjectActivity",
"actor": 1,
"text": "Admin Testerton added Cindy Luto project proj1 in application app1",
"date": "2016-05-11T18:52:34.548759Z",
"data": {
"project_desc": "proj1",
"application_desc": "app1",
"user": "U7",
"user_desc": "Cindy Lu",
"business_unit_desc": "Example BU"
},
"icon": "users",
"log_level": ""
},
{
"id": 4,
"name": "UserCreatedActivity",
"actor": 1,
"text": "Admin Testerton created user Cindy Lu",
"date": "2016-05-06T14:53:10.961953Z",
"data": {
"user": "U2",
"user_desc": "Cindy Lu"
},
"icon": "user",
"log_level": ""
}]
}This endpoint returns a list of Activities that impact the current user. This includes activities performed by the current user, activites that affect the current user directly, and activities about projects the current user is a part of. Login/logout activities are not included in this list.
Activities are events that have occurred in the application. We return when they occurred and some additional data about the event.
GET /api/v2/users/me/activities/
Note: this endpoint uses the term 'standard' to reference what we call 'library tasks' elsewhere in the API.
The application, business_unit, project, and standard fields have associated description fields, suffixed with '_desc'. These fields contain a description of the related item, and can be used to filter if the related item has been deleted.
Query Parameters
The following parameters may be used to filter the activity resources in the response.
| Parameter | Description |
|---|---|
| actor | Returns a list of activities performed by the user with the id specified. |
| application | Returns a list of activities that reference the application with the specified id. |
| application_desc | Returns a list of activities that reference the application with the specified application name. |
| business_unit | Returns a list of activities that reference the business unit with the specified id. |
| business_unit_desc | Returns a list of activities that reference the business_unit with the specified business unit name. |
| date_to | Returns all activities performed at or before the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime. |
| date_from | Returns all activities performed at or after the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime. |
| id | Returns the activities with the specified id. |
| name | Returns a list of activities with the specified name. |
| project | Returns a list of activities that reference the project with the specified id. |
| project_desc | Returns a list of activities that reference the project with the specified project name. |
| user | Returns a list of activities that reference the user with the specified user id (not to be confused with activities that are performed by this user). The id used here is a number, for example ?user=1. |
| standard | Returns a list of activities that reference the standard with the specified id. The format of this parameter value is the standard id prefixed by a 'T' for builtin standards or 'CT' for custom standards. |
| standard_desc | Returns a list of activities that reference the standard with the specified standard's full name, for example: "T21: Ensure confidential data is sent over an encrypted channel". |
Get a Specific Activity
GET /api/v2/users/me/activities/2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 4,
"date": "2016-03-30T15:16:05.659610+00:00",
"actor": 1,
"name": "UserCreatedActivity",
"text": "Admin Testerton created user Cindy Lu",
"data": {"user": "U7"},
"icon": "user",
"log_level": ""
}This endpoint retreives a specific Activity Resource as specified by the activity_id.
GET /api/v2/users/me/activities/{activity_id}/
URL Parameters
| Parameter | Description |
|---|---|
| activity_id | The id of the Activity Resource to retrieve. |
User Assigned Tasks
Get all assigned tasks
GET /api/v2/users/me/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"accepted": true,
"ad_hoc": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"email": "admin@example.com",
"id": 3
}
],
"text": "Insecure forgotten password.",
"id": "1-T2",
"library_task_created": "2010-10-20T17:46:50Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"manually_added_from_library": false,
"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",
"manually_added_from_library": false,
"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",
"manually_added_from_library": false,
"note_count": 0,
"phase": "Requirements",
"priority": "8",
"relevant": true,
"status": "TS2",
"task_id": "T2",
"title": "Secure forgotten password",
"updated": "2015-07-08T02:16:33.923315Z",
"url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
"verification_status": null,
"project": 1,
"application": 1
}This endpoint retreives a specific assigned task as specified by the Task id.
GET /api/v2/users/me/tasks/{task_id}/
URL Parameters
| Parameter | Description |
|---|---|
| task_id | The id of the Task to be retrieved. |
Changelog
v4.10
- Add support for creation and deletion of manually added library tasks to Tasks endpoint
- Add
manually_added_from_libraryfield to Task resources - Add
manually_added_from_libraryfield to Assigned Task - The
ad_hocfield has been renamed toproject_specific
- Add
v4.9
- Add
tagsto the Application endpoint - Add
application_tagsto Project endpoint - Change
related_tasksto include the title, phase, and url of each related task in the Tasks and specific Task endpoints. - Change
notify_tasksattribute of UserProfile to include id, name. - Change
updaterfield to be expanded by default in Task Notes endpoint.
v4.8
- Rename
basetobase_projectfor the Project endpoint - Add incomplete_tasks include filter and redesign task_counts include filter on projects endpoint.
- Remove
business_unitas expand filter - Expand instances of
business_unitinapplicationsby default - Add ALM plugins endpoint, which returns metadata for each ALM integration. Used to render ALM forms.
- Add params field to connector endpoint & make connector endpoint writeable.
v4.7
- Add
base(original project that spawned any number of new releases) to the Project endpoint. (Note: this field will be renamed tobase_projectin v4.8)
v4.6
- Add
persist_phasesto Business Unit endpoint - Add
updaterandupdatedfields to Analysis Note endpoint - Rename ldap group query field to group base dn
- Original SDE phases can now be edited via the API
v4.5
- Phases can be created, edited, or deleted.
- Changed the value of user to email instead of id, since we filter users by email.
- Password can be changed, password metadata retrieved on GET (session / basic authentication only)
- Password reset questions can be created, edited, or deleted
- API tokens can be generated, revoked or regenerated
- Email notification settings can be updated
- Group endpoint now has sync_connections include filter to fetch LDAP connections that reference groups
- Group can no longer be deleted if referenced by LDAP connection
- User Profile can be retrieved or updated via
/users/me/ - LDAP Connections
- Added
ldap_start_tls - Removed
ldap_method - Renamed deactivation to
deactivate_stale_users - Change group_mapping to use SDE group ids instead of group names
- Added
v4.4
- Added include field
last_jobfor connections returned by the ALM, Analysis and LDAP Connection endpoints. - Added
updaterfield tasks returned from thetasksendpoint. - Added documentation for LDAP connections and jobs
- LDAP Connections can be created, edited, or deleted.
- LDAP Jobs can be initiated or the results may be submitted.
v4.3
- Initiate a password reset via the API (session / basic authentication only)
- Global roles can be created, edited, or deleted.
v4.2
- Add documentation for session and basic authentication.
- Business Units, Groups, and Tasks includes the role of the users the resource returns.
- Include the first name, last name for the users returned by the tasks endpoint.
- ALM and Analysis Connections include whether they are accessible or not, and the id of their parent Connector.
- ALM and Analysis Connections can be created, edited, or deleted.
- ALM sync jobs can be initiated by POSTing to the alm jobs endpoint.
- Analysis import jobs can be initiated by POSTing to the analysis jobs endpoint.
- Project Role can be ordered and searched for by name.
- (Customer created) Project Roles can be deleted.
- Users endpoint returns if a password reset is in progress.
v4.1, v4.0, v3.9, etc.
- The dark times where we had no change log.