Introduction
Welcome to SD Elements API v2! Our API provides RESTful HTTP access to a large part of the functionality of SD Elements.
SD Elements's API documentation page was created with Slate
API Format
API results are currently returned in XML and JSON formats. It is advised to use the JSON format only. Specify the JSON format by including the HTTP header in all requests:
Content-type: application/json
Include Parameters
Some endpoints allow users to include extra fields in the response the API returns. This is used to add a specific field to an element, or collection of elements. For example, we may wish to receive a collection of projects that are within an application. Since projects are normally not a field of the applications resource, we can include projects in our request to see the projects as an additional field.
/?include={field_to_include}
Expand Parameters
Some endpoints allow users to expand a field that is already present in the response. For example, by default, an application element contains the id of the business unit to which it belongs. If we wish to retrieve more information about the business unit, we would expand the business unit field to get more information.
/?expand={field_to_expand}
It is possible to include and expand more than one field simultaneously.
/?include={field1},{field2}&expand={field3},{field4}
Pagination
Consume long responses by enabling pagination on an endpoint. Specify a page size in the URL:
/?page_size=100
and use the next and previous values to move through the complete response.
Authentication
GET /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"To authenticate against SD Elements, you need to pass an API access token via an Authorization header.
A token can be generated as follows:
- Go to the menu option in the top right of SD Elements:
/API Settings - Select the APIv2 tab and click on the Generate Token Button.
- The token will be displayed only once. If you forget your token you will need to regenerate a new one.
Help
If you have any questions/feedback regarding the SD Elements APIv2, please reach out to us. We're here to help. You can email SD Elements Support at support@sdelements.com.
Errors
The SD Elements API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid |
| 401 | Unauthorized -- Your API key is incorrect |
| 403 | Forbidden -- The resource requested is hidden for administrators only |
| 404 | Not Found -- The specified resource could not be found |
| 405 | Method Not Allowed -- You tried to access a resource with an invalid method |
| 406 | Not Acceptable -- You requested a format that isn't json |
| 429 | Too Many Requests -- You're requesting too many resources! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Resources
The most common types of resources obtained from this API are Collections and Elements. A collection represents the set of all resources of a particular type (such as "projects" or "applications"). An element resource represents an individual member of a collection. Each element consists of a set of name/value pairs.
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"
}]
}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"
}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 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"
}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. |
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 200 OK
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 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
}Applications
Get All Applications
GET /api/v2/applications/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"business_unit": 1,
"name": "Application Test",
"created": "2015-04-15T20:27:24.396442Z",
"updated": "2015-04-15T20:27:24.389957Z",
"priority": "0-none",
"slug": "application-test"
}]
}This endpoint retrieves a list of Application resources.
GET /api/v2/applications/
Query Parameters
The following parameters may be used to filter the application resources in the response.
| Parameter | Description |
|---|---|
| name | Returns the application resource with the specified name. |
| ordering | Returns a list of application resources ordered by the specified field. This endpoint accepts ordering by name. |
| priority | Returns a list of application resources with specified priority. |
| slug | Returns the application resource with the specified slug. |
Include Parameters
GET /api/v2/applications/?include=projects HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 3,
"business_unit": 1,
"name": "Application Test",
"created": "2015-04-15T20:27:24.396442Z",
"updated": "2015-04-15T20:27:24.389957Z",
"priority": "0-none",
"slug": "application-test",
"projects": [
{
"id": "1",
"name": "Project 1",
"slug": "project-1"
},
{
"id": "2",
"name": "Project 2",
"slug": "project-2"
}
]
}]
}See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| projects | Includes a list of projects associated with an application |
Get a Specific Application
GET /api/v2/applications/3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 3,
"business_unit": 1,
"name": "Application Test",
"created": "2015-04-15T20:27:24.396442Z",
"updated": "2015-04-15T20:27:24.389957Z",
"priority": "0-none",
"slug": "application-test"
}]
}This endpoint retrieves a specific Application resource, as specified by the id parameter.
GET /api/v2/applications/{application_id}/
URL Parameters
| Parameter | Description |
|---|---|
| application_id | The id of the application to retrieve |
All of the expand and include parameters for the 'Get all Applications' endpoint apply here as well.
Create a New Application
POST /api/v2/applications/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"business_unit": 1,
"name":"API Test"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 3,
"business_unit": 1,
"name": "API Test",
"created": "2015-04-15T20:27:24.396442Z",
"updated": "2015-04-15T20:27:24.389957Z",
"priority": "0-none",
"slug": "api-test"
}]
}| Fields | Required | Description |
|---|---|---|
| business_unit | Yes | The ID of the business unit the application belongs to |
| name | Yes | The name of the new application |
| priority | No | Specifies the priority of the application to be either '0-none', '1-high', '2-medium' or '3-low' |
Update an Application
PUT /api/v2/applications/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"name": "Edit Test",
"business_unit": 2
}HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"business_unit": 2,
"name": "Edit Test",
"created": "2015-06-18T19:27:14.860536Z",
"updated": "2015-06-18T21:00:03.827952Z",
"priority": "0-none",
"slug": "api-test"
}]
}Update a single application by specifying a new name and new business unit. The application to update is identified by the id.
PUT /api/v2/applications/{application_id}/
URL Parameters
| Parameter | Description |
|---|---|
| application_id | The id of the application to edit must be submitted in the request |
Payload
| Fields | Required | Description |
|---|---|---|
| name | No | The name of the application can be changed to any other string |
| business_unit | No | This can be edited by setting the business unit id |
| priority | No | The three options are: '0-none', '1-high', '2-medium', '3-low' |
Delete an Application
DELETE /api/v2/applications/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 204 NO CONTENTThis endpoint deletes a single Application resource, as specified by the id parameter.
DELETE /applications/{application_id}/
URL Parameters
| Parameter | Description |
|---|---|
| application_id | The id of the application to retrieve |
Business Units
GET /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"
},
{
"id": 2,
"slug": "example-business-unit-2",
"name": "example business unit 2"
}
]
}This endpoint retrieves a list of Business Unit resources, respecting the permissions of the user who has made the requested.
Query Parameters
The following parameters may be used to filter the business unit resources in the response.
| Parameter | Description |
|---|---|
| id | Returns the business unit resource with the specified id. |
| name | Returns the business unit resource with the specified name. |
| ordering | Returns a list of business unit resources ordered by the specified field. This endpoint accepts ordering by id. |
Connections
Get All ALM Connections of All Projects
GET /api/v2/connections/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"project": 2,
"system": "Rally",
"alias": "Rally Integration",
"frequency": "manually",
"command": "sync_rally",
"params": {
"sde_project": "Demo Project",
"alm_user": "rally_user",
"sde_verification_filter": "none,partial,pass,fail",
"rally_workspace": "Rally Workspace",
"alm_method": "https",
"alm_title_format": "$task_id $title",
"alm_server": "rally1.rallydev.com",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"alm_project": "Rally Project",
"alm_pass": "rally_password",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7
}
}]
}Returns a list of all ALM connections associated with all projects. The params are only displayed if you have the 'Edit ALM connections' permission.
GET /api/v2/connections/alm/
Query Parameters
The following parameters may be used to filter the ALM connections resources in the response.
| Parameter | Description |
|---|---|
| alias | Returns all ALM connections with the specified alias. |
| frequency | Returns all ALM connections with the specified frequency of synchronization. |
| system | Returns all ALM connections associated with a particular system. |
Get a Specific ALM Connection
GET /api/v2/connections/alm/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"project": 2,
"system": "Rally",
"alias": "Rally Integration",
"frequency": "manually",
"command": "sync_rally",
"params": {
"sde_project": "Demo Project",
"alm_user": "rally_user",
"sde_verification_filter": "none,partial,pass,fail",
"rally_workspace": "Rally Workspace",
"alm_method": "https",
"alm_title_format": "$task_id $title",
"alm_server": "rally1.rallydev.com",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"alm_project": "Rally Project",
"alm_pass": "rally_password",
"alm_phases": "requirements,architecture-design,development",
"sde_statuses_in_scope": "TODO",
"conflict_policy": "alm",
"sde_min_priority": 7
}
}Returns a specific ALM connection. The params are only displayed if you have the 'Edit ALM connections' permission.
GET /api/v2/connections/alm/{connection_id}/
Get All Analysis Connections of All Projects
GET /api/v2/connections/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"project": 1,
"system": "WhiteHat",
"alias": "WhiteHat Integration",
"frequency": "manually",
"command": "sync_whitehat",
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
}
}]
}Returns a list of all analysis connections associated with all projects. The params are only displayed if you have the 'Edit security tool connections' permission.
GET /api/v2/connections/analysis/
Query Parameters
The following parameters may be used to filter the analysis connections resources in the response.
| Parameter | Description |
|---|---|
| alias | Returns all analysis connections with the specified alias. |
| frequency | Returns all analysis connections with the specified frequency of synchronization. |
| system | Returns all analysis connections associated with a particular system. |
Get a Specific Analysis Connection
GET /api/v2/connections/analysis/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"project": 1,
"system": "WhiteHat",
"alias": "WhiteHat Integration",
"frequency": "manually",
"command": "sync_whitehat",
"params": {
"asset_name": "WebGoat Java",
"sde_project": "WhiteHat",
"sde_businessunit": "General",
"sde_application": "Demo Application",
"import_behaviour": "replace-scanner",
"analysis_server": "server.whitehatsec.com",
"task_status_mapping": "{}"
}
}Returns a specific analysis connection. The params are only displayed if you have the 'Edit security tool connections' permission.
GET /api/v2/connections/analysis/{connection_id}/
Connectors
Get All ALM Connectors
GET /api/v2/connectors/alm/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"name": "Rally Connector",
"system": "Rally"
}]
}Returns a list of all ALM connectors available.
GET /api/v2/connectors/alm/
Query Parameters
The following parameters may be used to filter the ALM connectors.
| Parameter | Description |
|---|---|
| system | Returns all ALM connectors associated with a particular system. |
Get a Specific ALM Connector
GET /api/v2/connectors/alm/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"name": "Rally Connector",
"system": "Rally"
}Returns a specific ALM connector.
GET /api/v2/connectors/alm/{id}
Get All Analysis Connectors
GET /api/v2/connectors/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1,
"name": "Fortify Connector",
"system": "Fortify"
}]
}Returns a list of all analysis connectors available.
GET /api/v2/connectors/analysis/
Query Parameters
The following parameters may be used to filter the analysis connectors.
| Parameter | Description |
|---|---|
| system | Returns all analysis connectors associated with a particular system. |
Get a Specific Analysis Connector
GET /api/v2/connectors/analysis/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"name": "Fortify Connector",
"system": "Fortify"
}Returns a specific analysis connector.
GET /api/v2/connectors/analysis/{id}
Global Roles
Get All Global Roles
GET /api/v2/global-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "UR4",
"name": "Administrator",
"description": "An administrator can create new..."
},
{
"id": "UR5",
"name": "No Role",
"description": "This role confers no permissions."
},
{
"id": "UR2",
"name": "Project Lead",
"description": "A project lead has permission to..."
},
{
"id": "UR1",
"name": "User",
"description": "A regular SD Elements user has..."
}
]
}This endpoint returns a list of Global Role resources.
Get a Specific Global Role
GET /api/v2/global-roles/UR4/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "UR4",
"name": "Administrator",
"description": "An administrator can create new..."
}This endpoint returns a specific Global Role resource as specified by the id parameter.
GET /api/v2/global-roles/{global_role_id}/
URL Parameters
| Parameter | Description |
|---|---|
| global_role_id | The id of the Global Role to retrieve |
Glossary Terms
Get all Glossary Terms
GET /api/v2/glossary-terms/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "G2",
"title": "Use Notification",
"text": "<p>This is a type of notification or message that basically describes...</p>",
"summary": "<p>A message that notifies the users of their actions.</p>",
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
},
{
"id": "G3",
"title": "Unauthenticated part of application",
"text": "<p>An unauthenticated (or authentication-free) part of an application consists...</p>",
"summary": "<p>An unauthenticated (or authentication-free) part of an application is a public portion of an application.</p>",
"created": "2015-03-26T19:52:34.854000Z",
"updated": "2015-03-26T19:52:34.853000Z"
}
]
}This endpoint returns a list of Glossary Term resources.
Get a Specific Glossary Term
GET /api/v2/glossary-terms/G2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "G2",
"title": "Use Notification",
"text": "<p>This is a type of notification or message that basically describes...</p>",
"summary": "<p>A message that notifies the users of their actions.</p>",
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
}This endpoint returns a specific Glossary Term resource.
GET /api/v2/glossary-terms/{glossary_term_id}/
URL Parameters
| Parameter | Description |
|---|---|
| glossary_term_id | The id of the Glossary Term to retrieve |
Create a New Glossary Term
POST /api/v2/glossary-terms/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"title": "New Glossary Term",
"text": "Full description of the term goes here.",
"summary": "The summary of the glossary term goes here."
}HTTP/1.1 200 OK
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": "Group2",
"description": "Group description",
"role": "Administrator"
}]
}This endpoint returns a list of Group resources.
GET /api/v2/groups/
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": "Group2",
"description": "Group description",
"role": "Administrator"
}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 |
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": "bob@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": "bob@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 200 OK
Content-Type: application/json
{
"id": 12,
"user": "bob@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. |
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": "bob@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": "bob@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 200 OK
Content-Type: application/json
{
"id": 12,
"user": "bob@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. |
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": 2,
"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 |
| phase | Given a phase id, returns all tasks in specified phase |
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": 3,
"id": "T179"
}]
}See the Expand Parameters section for more details.
| Parameter | Description |
|---|---|
| problem | Expands the problem fields in the task response object |
| phase | Expands the phase field 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": 1,
"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": 3,
"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": 3
}]
}]
} 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": [
{
"description": "Application security requirements, generally used to assist requirements analysts.",
"name": "Requirements",
"slug": "requirements",
"tip": "One-time tasks that you can verify. Similar to traditional functional requirements or user stories."
}
]
}This endpoint retrieves a list of Phase resources, which describe phases of a software development process.
GET /api/v2/phases/
Query Parameters
The following parameters may be used to filter the phases resources in the response.
| Parameter | Description |
|---|---|
| name | Returns the phase resource with specified name |
| slug | Returns the phase resource with the specified slug |
Get a Specific Phase
GET /api/v2/phases/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"description": "Application security requirements, generally used to assist requirements analysts.",
"name": "Requirements",
"slug": "requirements",
"tip": "One-time tasks that you can verify. Similar to traditional functional requirements or user stories."
}This endpoint retrieves a specific Phase resource, as specified by the id parameter.
GET /api/v2/phases/{phase_id}/
URL Parameters
| Parameter | Description |
|---|---|
| phase_id | The id of the phase to retrieve |
Profiles
Get All Profiles
GET /api/v2/profiles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "P1",
"name": "No Profile",
"description": "An empty Profile",
"answers": ["A740"],
"logo_url": "/static/images/logo-other.png"
},
{
"id": "P3",
"name": ".NET Web App",
"description": "Microsoft .NET Web Application",
"answers":["A1061", "A740", "A48", "A4", "A2"],
"logo_url": "/static/images/logo-net.png"
}
]
}This endpoint retrieves a list of Profiles resources.
Query Parameters
| Parameter | Description |
|---|---|
| ordering | Returns a list of profile resources ordered by the specified field. This endpoint supports ordering by id, name and description. |
Project Roles
Get All Project Roles
GET /api/v2/project-roles/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"id": "PR4",
"name": "Manage Project",
"description": "Can change project settings, ..."
},
{
"id": "PR5",
"name": "Normal",
"description": "Can view project and update task statuses"
},
{
"id": "PR6",
"name": "Read Only",
"description": "Can view project, but not modify it"
}
]
}This endpoint returns a list of Project Role resources.
Get a Specific Project Role
GET /api/v2/project-roles/PR4/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "PR4",
"name": "Manage Project",
"description": "Can change project settings, ..."
}This endpoint returns a specific Project Role resource, specified its id.
GET /api/v2/project-roles/{project_role_id}/
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"
},
"archived": false,
"name": "Project Test",
"creator": "geoff+demo@sdelements.com",
"description": "API Project",
"tags": ["foo", "bar"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4"
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}]
}]
}This endpoint retrieves a list of Project resources.
GET /api/v2/projects/
Query Parameters
The following parameters may be used to filter the application resources in the response.
| Parameter | Description |
|---|---|
| application | Returns a list of project resources that belong to the specified application id. |
| id | Returns the project resource with the specified id. |
| name | Returns the project resource with the specified name. |
| slug | Returns the project resource with the specified slug. |
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"
},
"archived": false,
"name": "Project Test",
"creator": "geoff+demo@sdelements.com",
"description": "API Project",
"tags": ["foo", "bar"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4"
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}]
}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 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"
},
"archived": false,
"name": "Project Test",
"creator": "geoff+demo@sdelements.com",
"description": "API Project",
"tags": ["foo", "bar"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-04-15T19:57:15.042353Z",
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4"
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}]
}| 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. |
Update a Project
PUT /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"
},
"archived": false,
"name": "This is the project's new name!",
"creator": "geoff+demo@sdelements.com",
"description": "API Project",
"tags": ["foo", "bar"],
"created": "2015-04-15T19:30:04.132712Z",
"updated": "2015-07-23T15:52:14.482992Z",
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4"
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}]
}Update a single project by specifying a new name and a new application. The project to update is identified by the id.
PUT /api/v2/projects/{project_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project to update |
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 200 OK
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 settings. |
| 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 |
Tasks
Get all tasks of a project
GET /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"phase": "Requirements",
"ad_hoc": false,
"relevant": true,
"accepted": true,
"assigned_to": [],
"updated": "2015-06-16T19:37:44.710100Z",
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": null,
"status": "TODO",
"note_count": 0,
"artifact_proxy": null
}]
}This endpoint returns a list of Task resources associated with the project having id "project_id".
GET /api/v2/projects/{project_id}/tasks/
Expand Parameters
GET /api/v2/projects/1/tasks/?expand=status,text HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": {
"description": "Insecure forgotten password and password reset...",
"amendments": []
},
"priority": 8,
"phase": "Requirements",
"ad_hoc": false,
"relevant": true,
"accepted": true,
"assigned_to": [],
"updated": "2015-06-16T19:37:44.710100Z",
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": null,
"status": {
"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 meaning, icon, name and slug sub-fields. |
Include Parameters
GET /api/v2/projects/1/tasks/?include=tags,related,problem,how_tos HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"phase": "Requirements",
"ad_hoc": false,
"relevant": true,
"accepted": true,
"assigned_to": [],
"updated": "2015-06-16T19:37:44.710100Z",
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": null,
"status": "TODO",
"note_count": 0,
"artifact_proxy": null,
"tags": ["tag1", "tag2"],
"related": ["1-T31", "1-T32", "1-T34", "1-T98"],
"problem": {
"id": "P526",
"title": "P526: Weak Password Recovery Mechanism...",
"text": "It is common for an application...",
"cwe": [
{
"url": "http://example.com/640",
"id": 640,
"title": "Weak Password Recovery..."
}
]
},
"how_tos": [
{
"id": "I131",
"title": "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 |
|---|---|
| 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 |
=======
Get a Specific Task
GET /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"accepted": true,
"ad_hoc": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"email": "admin@example.com",
"id": 3
}
],
"text": "Insecure forgotten password.",
"id": "1-T2",
"library_task_created": "2010-10-20T17:46:50Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "Requirements",
"priority": "8",
"relevant": true,
"status": "TODO",
"task_id": "T2",
"title": "Secure forgotten password",
"updated": "2015-07-08T02:16:33.923315Z",
"url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
"verification_status": null
}This endpoint retrieves a single Task resource, as specified by the id parameter.
GET /api/v2/projects/{project_id}/tasks/{task_id}/
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": "DONE" }
HTTP/1.1 200 OK
Content-Type: application/json
{
"accepted": true,
"ad_hoc": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"email": "user1@example.com",
"id": 3
}
],
"text": "Insecure forgotten password.",
"id": "1-T2",
"library_task_created": "2010-10-20T17:46:50Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "Requirements",
"priority": "8",
"relevant": true,
"status": "DONE",
"task_id": "T2",
"title": "Secure forgotten password",
"updated": "2015-07-08T02:16:33.923315Z",
"url": "http://example.com/.../1-T2",
"verification_status": null
}Updates a single Task resource, as specified by the project and task id parameters.
PATCH /api/v2/projects/{project_id}/tasks/{task_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the project to edit this task belongs to |
| task_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 |
| status | No | The slug of a status |
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...",
"updater": 1,
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
}]
}This endpoint returns a list of Task Note resources.
GET /api/v2/projects/{project_id}/tasks/{task_id}/notes/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project |
| task_id | The id of the Task |
Get a Specific Task Note
GET /api/v2/projects/1/tasks/1-T2/notes/682/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 682,
"task": "1-T2",
"text": "This task is on-hold until we...",
"updater": 1,
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
}This endpoint returns a specific Task Note resource.
GET /api/v2/projects/{project_id}/tasks/{task_id}/notes/{note_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project |
| task_id | The id of the Task |
| note_id | The id of the Task Note to retrieve |
Create a Task Note
POST /api/v2/projects/1/tasks/1-T2/notes/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"text": "This task is on-hold until we...",
}HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 682,
"task": "1-T2",
"text": "This task is on-hold until we...",
"updater": 1,
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
}This endpoint creates a Task Note resource with the specified content.
POST /api/v2/projects/{project_id}/tasks/{task_id}/notes/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project |
| task_id | The id of the Task |
Fields
| Field | Required | Description |
|---|---|---|
| text | Yes | The note text |
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...",
"updater": 1,
"created": "2015-03-26T19:50:46.348000Z",
"updated": "2015-03-26T19:50:46.348000Z"
}This endpoint updates a Task Note resource.
PUT /api/v2/projects/{project_id}/tasks/{task_id}/notes/{note_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project |
| task_id | The id of the Task |
| note_id | The id of the Task Note to update |
Fields
| Field | Required | Description |
|---|---|---|
| text | Yes | The note text |
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 Status Resources
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": [
{
"meaning": "NA",
"icon": "minus-circle",
"name": "Not Applicable",
"slug": "NA"
},
{
"meaning": "TODO",
"icon": "clock-o",
"name": "Incomplete",
"slug": "TODO"
},
{
"meaning": "DONE",
"icon": "check",
"name": "Complete",
"slug": "DONE"
}
]
}This endpoint returns a list of Task Status resources.
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 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": "Requirements",
"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}/tasks-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/tasks-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": "Requirements",
"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
}]
}This endpoint returns a list of User resources.
GET /api/v2/users/
Get a Specific User
GET /api/v2/users/599/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 599,
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith",
"last_login": "2015-06-05T02:55:54.231254Z",
"date_joined": "2015-06-05T02:55:54.231254Z",
"is_active": true,
"is_superuser": false,
"role": "No Role",
"groups": []
}This endpoint returns a specific User resource.
GET /api/v2/users/{user_id}/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to retrieve |
Create a User
POST /api/v2/users/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"email": "user@example.com",
"first_name": "Bob",
"last_name": "Smith"
"role": "UR5",
"groups": ["G1", "G2"]
}HTTP/1.1 200 OK
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"
},
{
"id": "G2",
"name": "Group2"
}
]
}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"
}
]
}Update a specific User resource.
PUT /api/v2/users/{user_id}/
URL Parameters
| Parameter | Description |
|---|---|
| user_id | The ID of the User to update |