Documentation | 2025.1

# Projects : Swarm Projects

## Get List of Projects

### Summary

Get List of Projects and metadata

GET /api/v11/projects

### Description

Returns a list of projects in Swarm that are visible to the current user.

The branch paths field is always returned empty for all project branches returned with the project list endpoint. This is because calculating the paths for all of the project branches is an expensive operation when there are a lot of projects and paths. To check the branch paths for a specific project, use the Get Project Information endpoint.

- tests and deploy fields:
  - If a project has an owner: only project owners and users with super user permissions can view the tests and deploy fields when fetching projects.
  - If a project does not have an owner: only project members and users with super user permissions can view the tests and deploy fields when fetching projects.
- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
fields | An optional comma-separated list or array of top level fields to return for the projects. Omitting this parameter or passing an empty value shows all fields. | string | query | No

### Example usage

#### Fetch a list of projects

To fetch all projects:

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects"

Pagination is not currently supported by this endpoint. Swarm responds with a list of projects:

    {
      "error": null,
      "messages": [],
      "data": {
        "projects": [
          {
            "id": "jam",
            "branches": [
              {
                "id": "main",
                "name": "Main",
                "workflow": null,
                "paths": [],
                "defaults": {
                  "reviewers": []
                },
                "minimumUpVotes": null,
                "retainDefaultReviewers": false,
                "moderators": [],
                "moderators-groups": []
              },
              ...
              ...
            ],
            "defaults": {
              "reviewers": []
            },
            "deleted": false,
            "deploy": {
              "enabled": false,
              "url": null
            },
            "description": "This is the project Jam description",
            "emailFlags": {
              "change_email_project_users": "1",
              "review_email_project_members": "1"
            },
            "jobview": null,
            "members": [
              "Bruno",
              "raj"
            ],
            "minimumUpVotes": null,
            "name": "Jam",
            "owners": [],
            "private": true,
            "retainDefaultReviewers": false,
            "subgroups": [],
            "tests": {
              "enabled": false,
              "url": null,
              "postBody": null,
              "postFormat": "url"
            },
            "workflow": null,
          },
          {
            ...
            <other projects formatted as above>
            ...
          },
        ],
      }
    }

#### Fetch specified fields for all projects

To fetch the id, description, and members fields for all projects, use one of the following methods:

- Using a comma-separated list of top level fields:

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects?fields=id,description,members"

- Using an array of top level fields:

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects?fields[]=id&fields[]=description&fields[]=members"

Pagination is not currently supported by this endpoint. Swarm responds with a list of all projects:

    {
      "error": null,
      "messages": [],
      "data": {
        "projects": [
          {
            "id": "blue-book",
            "description": "This is a private project for use only by users with sufficient clearance.",
            "members": [
              "alex.randolph",
              "allison.clayborne"
            ],
          },
          {
            "id": "jam",
            "description": "This the project Jam description.",
            "members": [
              "Bruno",
              "raj"
            ],
          },
          {
            "id": "jplugin",
            "description": "A Java plugin for continuous integration.",
            "members": [
              "allison.clayborne",
              "jack.boone",
              "steve.russell"
            ],
          },
        ],
      }
    }

#### If a request fails

<error code>:

400 metadata request invalid, boolean required

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Get Project Information

### Summary

Get Project Information

GET /api/v11/projects/{id}

### Description

Retrieve all information about a project or specify which fields you want to return for the project.

- tests and deploy fields:
  - If a project has an owner: only project owners and users with super user permissions can view the tests and deploy fields when fetching projects.
  - If a project does not have an owner: only project members and users with super user permissions can view the tests and deploy fields when fetching projects.
- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes
fields | An optional comma-separated list or array of top level fields to return for the project. Omitting this parameter or passing an empty value shows all fields. | string | query | No

### Example usage

#### Fetch all fields for a project

To fetch all fields for project jam:

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects/jam"

Swarm responds with a project entity:

    {
      "error": null,
      "messages": [],
      "data": {
        "projects": [
          {
            "id": "jam",
            "branches": [
              {
                "id": "main",
                "name": "Main",
                "workflow": null,
                "paths": [
                  "//depot/Jam/MAIN/...",
                  "//jam/main/..."
                ],
                "defaults": {
                  "reviewers": []
                },
                "minimumUpVotes": null,
                "retainDefaultReviewers": false,
                "moderators": [],
                "moderators-groups": []
              },
              ...
              ...
            ],
            "defaults": {
              "reviewers": []
            },
            "deleted": false,
            "deploy": {
              "enabled": false,
              "url": ""
            },
            "description": "This the project Jam description",
            "emailFlags": {
              "change_email_project_users": "1",
              "review_email_project_members": "1"
            },
            "jobview": "",
            "members": [
              "Bruno",
              "raj"
            ],
            "minimumUpVotes": null,
            "name": "Jam",
            "owners": [],
            "private": false,
            "retainDefaultReviewers": false,
            "subgroups": [],
            "tests": {
              "enabled": false,
              "url": "",
              "postBody": "",
              "postFormat": "url"
            },
            "workflow": null
          },
        ],
      }
    }

#### Fetch specified fields for a project

To fetch the id, description, and members fields for project Jam, use one of the following methods:

- Using a comma-separated list of top level fields:

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects/jam?fields=id,description,members"

- Using an array of top level fields:

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects/jam?fields[]=id&fields[]=description&fields[]=members"

Swarm responds with a project entity containing the requested fields:

    {
      "error": null,
      "messages": [],
      "data": {
        "projects": [
          {
            "id": "jam",
            "description": "This the project Jam description",
            "members": [
              "Bruno",
              "raj"
            ],
          },
        ],
      }
    }

#### If a request fails

<error code>:

404 Project does not exist or you do not have permission to view it

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Get a list of Perforce jobs on a project

### Summary

Get a list of Perforce jobs on a project.

GET /api/v11/projects/{project_id}/jobs

### Description

Get a list of Perforce jobs on a project.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
filter | Filter Perforce jobs by using a combination of a job field and value. The job fields and values available depend on your Perforce job configuration. If you have a job filter selected for the project you can also limit jobs returned by field name and value, see Job filter in Project settings. | string | query | No
max | Maximum number of Perforce jobs to return. This does not guarantee that max jobs are returned. It does guarantee that the number of jobs returned won’t exceed max. If not specified, the 50 most recent jobs are returned. | integer | query | No

### Example usage

#### Get all Perforce jobs on the Acme project

curl -u "username:ticket" "https://myswarm-url/api/v11/projects/acme/jobs"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job001002",
            "link": "/jobs/job001002",
            "fixStatus": "open",
            "subsystem": "backend",
            "description": "The description is blank when not specified for schedules in release 2.0.  Please resolve.\n",
            "descriptionMarkdown": "<span class=\"first-line\">The description is blank when not specified for schedules in release 2.0.</span><br><span class=\"more-lines\">\n &nbsp;Please resolve.</span>"
          },
          {
          ...
          <Other job ids formatted as above>
          ...
          }
        ]
      }
    }

#### Get the 10 most recent Perforce jobs in project Acme

curl -u "username:ticket" "https://myswarm-url/api/v11/projects/acme/jobs?max=10"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job000999",
            "link": "/jobs/job000999",
            "fixStatus": "fixed",
            "subsystem": "docs",
            "description": "Copyright text is incomplete.  Please resolve.\n",
            "descriptionMarkdown": "<span class=\"first-line\">Copyright text is incomplete.</span><br><span class=\"more-lines\">\n &nbsp;Please resolve.</span>"
          },
          {
          ...
          <Other job ids formatted as above>
          ...
          }
        ]
      }
    }

#### Get Perforce jobs in the range of job000050 to job000059 that are part of project Acme

curl -u "username:ticket" "https://myswarm-url/api/v11/projects/acme/jobs?filter=job00005*"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job000050",
            "link": "/jobs/job000050",
            "fixStatus": "fixed",
            "subsystem": "frontend",
            "description": "Update API call for status. Use the new repsonse style.\n",
            "descriptionMarkdown": "<span class=\"first-line\">Update API call for status.</span><br><span class=\"more-lines\">\n &nbsp;Use the new repsonse style.</span>"
          }
        ]
      }
    }

#### Get all Perforce jobs with a Job filter matching subsystem=frontend for project Acme

curl -u "username:ticket" "https://myswarm-url/api/v11/projects/acme/jobs?filter=subsystem=frontend"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job000050",
            "link": "/jobs/job000050",
            "fixStatus": "fixed",
            "subsystem": "frontend",
            "description": "Update API call for status. Use the new repsonse style.\n",
            "descriptionMarkdown": "<span class=\"first-line\">Update API call for status.</span><br><span class=\"more-lines\">\n &nbsp;Use the new repsonse style.</span>"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 404 Project does not exist or you do not have permission to view it

- 500 Invalid field name specified, the error text contains the invalid field name.

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Create a new project

### Summary

Create a new Swarm project.

POST /api/v11/projects

### Description

Create a new Swarm project.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes

### Example usage

Create project Saturn:

curl -X POST -u "username:ticket" -H "Content-Type: application/json" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/projects"

The "mybodyfilename.txt" file contains details for project Saturn:

    {
      "id": "saturn",
      "name": "Saturn",
      "description": "Project Saturn is our moonshot project.",
      "jobView":"project=swarm",
      "members":["bruno", "alice", "bob"],
      "defaults": {
        "reviewers": ["bob", "alice"]
      },
      "tests": {
        "enabled": false
      },
      "branches": [
        {
          "id": "main",
          "name": "main",
          "paths": ["//depot/saturn/..."],
          "defaults": {
            "reviewers": ["bob"]
          }
        }
      ]
    }

Swarm responds with:

    {
      "error": null,
      "messages": [],
      "data": {
        "projects": [
    	{
    	  "id": "saturn",
    	  "name": "Saturn",
    	  "defaults": {
    	    "reviewers": {
    	       "bob",
    	       "alice"
    	      }
    	    },
    	    "description": "Project Saturn is our moonshot project.",
    	    "members": [
    	      "bruno"
    	    ],
    	    "subgroups": [],
    	    "owners": [],
    	    "branches": [
    	      {
    		"id": "main",
    		"name": "main",
    		"paths": [
    			"//depot/saturn/..."
    		],
    		"defaults": {
    		  "reviewers": {
    		    "Aruna_Gupta": []
    		   }
    	         },
    		 "moderators": [],
    		 "moderators-groups": [],
    		 "workflow": null,
    		 "retainDefaultReviewers": false,
    		 "minimumUpVotes": null
    		}
    	       ],
    	       "jobview": null,
    	       "emailFlags": {
    		  "change_email_project_users": "1",
    		  "review_email_project_members": "1"
    		},
    		"tests": {
    		  "enabled": false,
    		  "url": null,
    		  "postBody": null,
    		  "postFormat": "url"
    		},
    		"deploy": {
    		  "enabled": false,
    		  "url": null
    		},
    		"deleted": false,
    		"private": false,
    		"workflow": null,
    		"retainDefaultReviewers": false,
    		"minimumUpVotes": null
    		}
    	    ]
          }
    }

#### If a request fails

<error code>:

400 Invalid data specified for the project or invalid references such as references to tests and workflows.

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Update a project

### Summary

Update a Swarm project.

PATCH /api/v11/projects/{{PROJECTID}}

### Description

Update details for a Swarm project.

If sharing is switched off for a workflow, any projects or branches that were associated with the workflow while it was shared will remain associated with it.

If you edit a project or branch associated with that unshared workflow, you will still see the name of the workflow in the Workflow field, even if you don't own that workflow. If you remove that workflow from the project/branch you will not be able to see the workflow in the Workflow dropdown list unless you own it.

By default, any member of a project can edit the project's configuration. Administrators can configure Swarm to prevent changes to the project's name and branch definition(s). See Projects for details.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes

### Example usage

Update project Saturn:

curl -X PATCH -u "username:ticket" "https://my-swarm-host/api/v11/projects/saturn"

    {"workflow": "1"}

Swarm responds with the details of the updated project.

    {
      "error": null,
      "messages": [],
      "data": {
      "projects": [
        {
          "name": "Saturn",
          "defaults": {
    	 "reviewers": ["bob", "alice"]
    	},
    	"description": "",
    	"members": [
    	  "bruno", "alice", "bob"
    	],
    	"subgroups": [],
    	"owners": [
    	  "bob"
    	],
    	"branches": [
                        {
                          "id": "main",
                          "name": "main",
                          "paths": ["//depot/saturn/..."],
                          "defaults": {
                          "reviewers": ["bob"]
                             }
                         }
           ],
    	"jobview": "",
    	"emailFlags": {
    	  "change_email_project_users": "1",
    	  "review_email_project_members": "1"
    	},
    	"tests": {
    	  "enabled": false,
    	  "url": "",
    	  "postBody": "",
    	  "postFormat": "url"
    	},
    	"deploy": {
    	  "enabled": false,
    	  "url": ""
    	},
    	"deleted": true,
    	"private": false,
    	"workflow": 1,
    	"retainDefaultReviewers": false,
    	"minimumUpVotes": null,
    	"id": "saturn"
    	}
         ]
       }
    }

#### If a request fails

<error code>:

404 Project does not exist or you do not have permission to view it

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Delete a project

### Summary

Delete a Swarm project.

DEL /api/v11/projects/{{PROJECTID}}

### Description

Delete a Swarm project.

- Users with super or admin privileges in Helix Core Server can delete projects.
  - If the Swarm user has insufficient permissions, cleanup on the deleted Helix Core projects will fail.
- Project owners can delete projects that they own.
- If a project has no owners, any member of the project can delete the project.

When you delete a project, Swarm will try to clean it up by doing the following:

- The deleted project is removed from the Swarm project list on the dashboard, and from project searches.
- The deleted project is removed from the profile page of the project owners, members, moderators, and followers.
- The project name is removed from the Project column on the Reviews list page.
- Reviews that belong to the deleted project are not changed. The open and closed reviews remain accessible, their review states, comments, and tasks can be modified as normal.
- Reviews that belong to the deleted project, the project branch name link in the review heading is replaced with a link to the common depot location that contains the files included in the review.

The deleted project name cannot be reused for a new project. This behavior is not case sensitive, this means that if you delete a project called Project B you cannot create a new project called project b.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes

### Example usage

Delete project Saturn:

curl -X DEL -u "username:ticket" "https://my-swarm-host/api/v11/projects/saturn"

    {
      "id": "saturn",
      "name": "Saturn",
      "description": "Project Saturn is our moonshot project.",
      "jobView":"project=swarm",
      "members":["bruno", "alice", "bob"],
      "defaults": {
        "reviewers": ["bob", "alice"]
      },
      "tests": {
        "enabled": false
      },
      "workflow": 12,
      "branches": [
        {
          "id": "main",
          "name": "main",
          "paths": ["//depot/saturn/..."],
          "defaults": {
            "reviewers": ["bob"]
          }
        }
      ]
    }

Swarm responds with the details of the deleted project.

    {
      "error": null,
      "messages": [],
      "data": {
      "projects": [
        {
          "name": "Saturn",
          "defaults": {
    	 "reviewers": ["bob", "alice"]
    	},
    	"description": "",
    	"members": [
    	  "bruno", "alice", "bob"
    	],
    	"subgroups": [],
    	"owners": [
    	  "bob"
    	],
    	"branches": [
                        {
                          "id": "main",
                          "name": "main",
                          "paths": ["//depot/saturn/..."],
                          "defaults": {
                          "reviewers": ["bob"]
                             }
                         }
           ],
    	"jobview": "",
    	"emailFlags": {
    	  "change_email_project_users": "1",
    	  "review_email_project_members": "1"
    	},
    	"tests": {
    	  "enabled": false,
    	  "url": "",
    	  "postBody": "",
    	  "postFormat": "url"
    	},
    	"deploy": {
    	  "enabled": false,
    	  "url": ""
    	},
    	"deleted": true,
    	"private": false,
    	"workflow": null,
    	"retainDefaultReviewers": false,
    	"minimumUpVotes": null,
    	"id": "saturn"
    	}
         ]
       }
    }

#### If a request fails

<error code>:

- 401 This operation is limited to project or group owners.

- 404 Project does not exist or you do not have permission to view it

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Undelete a Project

### Summary

Undelete a Swarm project.

POST /api/v11/projects/{{PROJECTID}}/undelete

### Description

Undelete a Swarm project.

- Users with super or admin privileges in Helix Core Server can undelete projects.
- Project owners can undelete projects that they own.
- If a project has no owners, any member of the project can undelete the project.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes

### Example usage

Undelete project Saturn that has two branches:

curl -X POST -u "username:ticket" "https://my-swarm-host/api/v11/projects/saturn/undelete"

Swarm responds with the details of the undeleted project.

    {
      "error": null,
      "messages": [],
      "data": {
      "projects": [
        {
          "name": "Saturn",
          "defaults": {
            "reviewers": []
          },
          "description": null,
          "members": [
            "mei"
          ],
          "subgroups": [],
          "owners": [],
          "branches": [
          {
              "name": "branch1",
              "paths": [
                "//depot/paths/..."
              ],
              "id": "branch1",
              "moderators": [],
              "moderators-groups": [],
              "defaults": {
                "reviewers": []
              },
              "workflow": null,
              "retainDefaultReviewers": false,
              "minimumUpVotes": null
          },
          {
              "name": "branch2",
              "paths": [
                "//gwt/..."
              ],
              "id": "branch2",
              "moderators": [],
              "moderators-groups": [],
              "defaults": {
                "reviewers": []
              },
              "workflow": null,
              "retainDefaultReviewers": false,
              "minimumUpVotes": null
           }
          ],
          "jobview": null,
          "emailFlags": {
            "change_email_project_users": "1",
            "review_email_project_members": "1"
          },
          "deleted": false,
          "private": false,
          "workflow": null,
          "retainDefaultReviewers": false,
          "minimumUpVotes": null,
          "id": "saturn"
         }
        ]
      }
    }

#### If a request fails

<error code>:

- 401 This operation is limited to project or group owners.

- 404 Project does not exist or you do not have permission to view it.

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

Your search for returned results