Projects
Get all projects
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. Use in conjunction with Custom Filtering Lookups for greater utility.
| 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. |
| components | Filter projects by component IDs. |
| creator | Filter projects by user ID. |
| created | Filter projects by the date they were created. See Custom Filtering Lookups. |
| updated | Filter projects by date were updated. See Custom Filtering Lookups. |
| custom_attributes | Filter projects by their custom attributes. |
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,
"external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
"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",
"active": true
},
"profile_draft": null,
"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/",
"archived": false
},
"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/",
"archived": false
},
"components": ["CSC7"],
"connected_component": null,
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"is_creator": true
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}],
"custom_attributes": {
"slug": "value"
},
"survey_complete": true,
"survey_dirty": false,
"locked_on": null,
"locked_by": null,
"locked": false,
"release_project": true,
"risk_policy_compliant": true,
"risk_policy": 1,
"project_classification": 1,
"project_locked": false,
"project_lock_modified_on": null,
"project_lock_modified_by": null
}]
}
Include Parameters
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 Countermeasures broken down by phase and completeness for the project. See note below. |
| incomplete_tasks | Includes a count of incomplete Countermeasures broken down by high (7-10), medium (4-6), and low (1-3) priorities. |
| task_metrics | Includes metrics associated with Countermeasures. |
| problem_metrics | Includes metrics associated with Weaknesses. |
Note: The "total" count represents the total number of applicable Countermeasures (those not marked N/A), and "complete" marks the number of Countermeasures whose status meaning is Done.
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,
"external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
"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",
"active": true
},
"profile_draft": null,
"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,
"components": [],
"connected_component": null,
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"is_creator": 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_issue_tracker",
"edit_project_survey"
],
"incomplete_tasks": {
"high": 38,
"medium": 60,
"low": 11
},
"task_counts": {
"Requirements": {
"total": 28,
"na": 3,
"complete": 4,
"slug": "requirements"
},
"Architecture & Design": {
"total": 6,
"na": 3,
"complete": 1,
"slug": "architecture-design"
},
"Development": {
"total": 30,
"na": 3,
"complete": 5,
"slug": "development"
},
"Testing": {
"total": 57,
"na": 3,
"complete": 2,
"slug": "testing"
}
},
"survey_complete": true,
"survey_dirty": false,
"locked_on": null,
"locked_by": null,
"locked": false,
"release_project": false,
"risk_policy_compliant": true,
"risk_policy": 1,
"project_classification": 1,
"project_locked": false,
"project_lock_modified_on": null,
"project_lock_modified_by": null
}]
}
Exclude Parameters
See the Exclude Parameters section for more details.
| Parameter | Description |
|---|---|
| members | Excludes the list of users and groups in a project. |
GET /api/v2/projects/1/?exclude=members HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1936,
"external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
"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",
"active": true
},
"profile_draft": null,
"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,
"components": [
{
"id": "CSC7",
"title": "My Component"
},
{
"id": "CSC8",
"title": "My Component2"
}
],
"connected_component": null,
"custom_attributes": {
"slug": "value"
},
"survey_complete": true,
"survey_dirty": false,
"locked_on": null,
"locked_by": null,
"locked": false,
"release_project": false,
"risk_policy_compliant": true,
"risk_policy": 1,
"project_classification": 1,
"project_locked": false,
"project_lock_modified_on": null,
"project_lock_modified_by": null
}]
}
Expand Parameters
See the Expand Parameters section for more details.
| Parameter | Description |
|---|---|
| application | The application field is expanded to display information about the project's application. |
| creator | The creator field is expanded to display information about the project creator. |
| risk_policy | The Risk Policy field is expanded to display information about the associated Risk Policy. |
| project_classification | The Project Classification field is expanded to display information about the associated project classification. |
GET /api/v2/projects/?expand=application,creator,risk_policy HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [{
"id": 1936,
"external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
"slug": "project-test",
"url": "http://example.com/bunits/bu-test/app-test/project-test",
"application": {
"id": 1280,
"name": "Application Test",
"slug": "application-test"
},
"profile" : {
"id": "P9",
"name": "Android App",
"logo_url": "/static/images/android.png",
"active": true
},
"profile_draft": null,
"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,
"components": [],
"connected_component": 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"
},
"survey_complete": true,
"survey_dirty": false,
"locked_on": null,
"locked_by": null,
"locked": false,
"release_project": false,
"risk_policy_compliant": true,
"risk_policy": {
"id": 1,
"name": "All Risk",
"description": "Applies to all applications",
"filters": {
"phases": ["requirements", "architecture-design", "development", "testing"],
"priority": 7,
"tags": ["tag1", "tag2"]
},
"conditions": {
"task_statuses": ["TS1"]
},
"is_org_default": true,
"created": "2018-01-31T17:30:26.175423-05:00",
"last_updated": "2018-01-31T17:30:26.175253-05:00"
},
"project_classification": {
"id": 1,
"ordinal": 1,
"name": "Maximum",
"description": "Used for projects with maximum risk.",
"default_risk_policy": 1,
"risk_policies": [1],
"answers": ["A168"],
"last_update_date_time": "2019-05-28T11:34:21.908541-04:00",
"is_unclassified": false
},
"project_locked": false,
"project_lock_modified_on": null,
"project_lock_modified_by": null
}]
}
Get a specific project
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. |
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,
"external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
"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"
},
"profile_draft": null,
"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,
"components": [
{
"id": "CSC7",
"title": "My Component"
},
{
"id": "CSC8",
"title": "My Component2"
}
],
"connected_component": null,
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"is_creator": true
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}],
"custom_attributes": {
"slug": "value"
},
"survey_complete": true,
"survey_dirty": false,
"locked_on": null,
"locked_by": null,
"locked": false,
"release_project": false,
"risk_policy_compliant": true,
"risk_policy": 1,
"project_classification": 1,
"project_locked": false,
"project_lock_modified_on": null,
"project_lock_modified_by": null
}
Create a new project
| 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 desired role. Note: If this parameter is included, the Business Unit that the application will add the new project to must either have these groups as members or be configured with the "All Users" option. |
| 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 desired role. |
| locked | No | A boolean field to lock or unlock the project. It can only be used by users that have the lock_project_survey permission. |
| risk_policy | No | The ID of the Risk Policy that applies to this project. |
| tags | No | A list of tags applicable to the project. |
| answers | No | An array of Answer IDs that represent survey answers that apply to this project. Answer IDs are strings and deployment-specific. Note: For each project, SD Elements selects Answers first from the Survey profile and then from the Answers that users provide while manually completing the Survey. |
| custom_attributes | Depends | The JSON of custom attributes as defined by your administrator. This field is not required unless mandated by your administrator. See Project attributes for more information. Note: The custom_attributes field is case-sensitive. Fields included with a project payload that have not been added through the web front-end are saved but only accessible via the API. |
POST /api/v2/projects/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"application": 1280,
"name": "Project Test",
"profile": "P9",
"answers": ["A1", "A2"],
"users": [{"email": "test@example.com", "role": "PR4"}],
"groups": [{"id": "G1", "role": "PR4"}]
}
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": 1936,
"external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
"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"
},
"profile_draft": null,
"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,
"is_creator": true
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}],
"custom_attributes": {
},
"survey_complete": true,
"survey_dirty": false,
"locked_on": null,
"locked_by": null,
"locked": false,
"risk_policy_compliant": true,
"risk_policy": 1,
"project_classification": null,
"project_locked": false,
"project_lock_modified_on": null,
"project_lock_modified_by": null
}
Update a project
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 |
|---|---|---|
| project_locked | No | A boolean field to lock or unlock the project. It can only be used by users that have the lock_project permission. Note: The project_locked field can only be edited if the ENABLE_PROJECT_LOCKING flag is enabled. |
| locked | No | A boolean field to lock or unlock the project survey. It can only be used by users that have the lock_project_survey permission. Note: This field is deprecated and will be changed to survey_locked in future releases. |
| 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 | The description of the project. |
| tags | No | The list of project tags. |
| parent | No | The ID, name, slug, and URL of the parent project. |
| base_project | No | The 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 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 desired role. |
| risk_policy | No | The ID of the Risk Policy that applies to this project. |
| custom_attributes | Depends | The JSON of custom attributes as defined by your administrator. This field is not required unless mandated by your administrator. See Project attributes for more information. Note: The custom_attributes field is case-sensitive. Fields included with a project payload that have not been added through the web front-end are saved but only accessible via the API. |
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,
"external_id": "project-f06725cc-8b93-4eb4-95be-0691d6f2c3f7",
"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"
},
"profile_draft": null,
"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,
"components": [
{
"id": "CSC7",
"title": "My Component"
},
{
"id": "CSC8",
"title": "My Component2"
}
],
"users": [{
"id": "1",
"email": "test@example.com",
"role": "PR4",
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"is_creator": true
}],
"groups": [{
"id": "G1",
"name": "Devs",
"role": "PR4"
}],
"custom_attributes": {
"slug": "value"
},
"survey_complete": true,
"survey_dirty": false,
"locked_on": "2016-06-01T14:39:45.083334Z",
"locked_by": 1,
"locked": true,
"risk_policy_compliant": true,
"risk_policy": 1,
"project_classification": 1
}
Delete a project
This endpoint deletes a specific project, specified by the project id.
DELETE /api/v2/projects/{project_id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the Project to delete. |
DELETE /api/v2/projects/10/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT