Projects : Swarm Projects

Important

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

Get List of Projects

Summary

Get List of Projects

GET /api/v9/projects/

Description

Returns a list of projects in Swarm that are visible to the current user. Administrators will see all projects, including private ones.

Tip
  • 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 fields to show for each project. Omitting this parameter or passing an empty value shows all fields.

string

query

No

workflow

An optional parameter to only list projects using a workflow.

string

query

No

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "jplugin",
    "branches": [],
    "defaults": {
      "reviewers": {
        "users": {
          "allison.clayborne": {
            "required": true
          },
          "jack.boone": [ ],
          "steve.russell": [ ]
        }
      }
    },
    "deleted": false,
    "deploy": {
      "enabled": false,
      "url": ""
    },
    "description": "A Java plugin for continuous integration.",
    "emailFlags": {
      "change_email_project_users": "1",
      "review_email_project_members": "1"
    },
    "jobview": "",
    "members": [
      "allison.clayborne",
      "jack.boone",
      "steve.russell"
    ],
    "minimumUpVotes": 1,
    "name": "JPlugin",
    "owners": [
      "allison.clayborne"
    ],
    "private": false,
    "retainDefaultReviewers": false,
    "subgroups": [ ],
    "tests": {
      "enabled": false,
      "url": "",
      "postBody": "",
      "postFormat": "URL"
    },
    "workflow": null
  },
  "readme":<h1>P4 Plugin</h1>\n<p>Jenkins plugin for a Perforce Helix Versioning Engine (P4D).</p>\n<h2>Contents</h2>\n<ul>\n<li><a href=\"https://github.com/jenkinsci/p4-plugin/blob/main/RELEASE.md\">Release notes</a></li>\n\">
}

Example usage

Listing projects

To list all projects:

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

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

HTTP/1.1 200 OK

{
  "projects": [
    {
      "id": "blue-book",
      "description": "This is a private project for use only by users with sufficient clearance.",
      "members": [
        "alex.randolph",
        "allison.clayborne"
      ],
      "name": "Blue Book"
    },
    {
      "id": "jplugin",
      "description": "A Java plugin for continuous integration.",
      "members": [
        "allison.clayborne",
        "jack.boone",
        "steve.russell"
      ],
      "name": "JPlugin"
    },
    {
      "id": "mercury",
      "description": "Mercury project for code management.",
      "members": [
        "alex.randolph",
        "claire.brevia",
        "jack.boone"
      ],
      "name": "Mercury"
    },
    {
      "id": "test-data",
      "description": "",
      "members": [
        "steve.russell"
      ],
      "name": "Test Data"
    },
    {
      "id": "test-project-for-workflow",
      "description": "This project has been created to test Swarm workflow.",
      "members": [
        "alex.randolph",
        "allison.clayborne",
        "claire.brevia",
        "jack.boone",
        "paula.boyle",
        "steve.russell"
      ],
      "name": "Test project for workflow"
    }
  ]
}

Project administrators wishing to see the tests and deploy fields must fetch projects individually.

Get Project Information

Summary

Get Project Information

GET /api/v9/projects/{id}

Description

Retrieve information about a project.

Tip
  • 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 fields to show for each project. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "jplugin",
    "branches": [
      {
        "id": "main",
        "name": "MAIN",
        "workflow": null,
        "paths": [
          "//projects/jplugin/main/..."
        ],
        "defaults": {
          "reviewers": {
            "users": {
              "steve.russell": [ ]
            }
          }
        },
        "minimumUpVotes": null,
        "retainDefaultReviewers": false,
        "moderators": [
          "claire.brevia"
        ],
        "moderators-groups": [ ]
      },
      {
        "id": "candidate",
        "name": "CANDIDATE",
        "workflow": null,
        "paths": [
          "//projects/jplugin/candidate/..."
        ],
        "defaults": {
          "reviewers": [ ]
        },
        "minimumUpVotes": null,
        "retainDefaultReviewers": false,
        "moderators": [ ],
        "moderators-groups": [ ]
      }
    ],
    "defaults": {
      "reviewers": {
        "users": {
          "allison.clayborne": {
            "required": true
          },
          "jack.boone": [ ],
          "steve.russell": [ ]
        }
      }
    },
    "deleted": false,
    "deploy": {
      "enabled": false,
      "url": ""
    },
    "description": "A Java plugin for continuous integration.",
    "emailFlags": {
      "change_email_project_users": "1",
      "review_email_project_members": "1"
    },
    "jobview": "",
    "members": [
      "allison.clayborne",
      "jack.boone",
      "steve.russell"
    ],
    "minimumUpVotes": 1,
    "name": "JPlugin",
    "owners": [
      "allison.clayborne"
    ],
    "private": false,
    "retainDefaultReviewers": false,
    "subgroups": [ ],
    "tests": {
      "enabled": false,
      "url": "",
      "postBody": "",
      "postFormat": "URL"
    },
    "workflow": null
  },
  "readme":<h1>P4 Plugin</h1>\n<p>Jenkins plugin for a Perforce Helix Versioning Engine (P4D).</p>\n<h2>Contents</h2>\n<ul>\n<li><a href=\"https://github.com/jenkinsci/p4-plugin/blob/main/RELEASE.md\">Release notes</a></li>\n 
}			

Example usage

Fetching a project

To fetch an individual project:

curl -u "username:password" "https://my-swarm-host/api/v9/projects/testproject2?fields=id,description,members,name"

Swarm responds with a project entity:

HTTP/1.1 200 OK

{
  "project": {
    "id": "jplugin",
    "description": "A Java plugin for continuous integration.",
    "members": [
      "allison.clayborne",
      "jack.boone",
      "steve.russell"
    ],
    "name": "JPlugin"
  }
}

Project administrators have access to additional fields (tests and deploy) when fetching individual projects using this endpoint.

Create a new Project

Summary

Create a new Project

POST /api/v9/projects/

Description

Creates a new project in Swarm.

Parameters

Parameter Description Type Parameter Type Required

name

Project Name (is also used to generate the Project ID)

string

form

Yes

members

An array of project members.

array

form

Yes

subgroups

An optional array of project subgroups.

array

form

No

owners

An optional array of project owners.

array

form

No

description

An optional project description.

string

form

No

private

Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false)

boolean

form

No

deploy

Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"}

array

form

No

tests

Configuration for testing/continuous integration.

array

form

No

branches

Optional branch definitions for this project.

array

form

No

jobview

An optional jobview for associating certain jobs with this project.

string

form

No

emailFlags[change_email_project_users]

Email members, moderators and followers when a change is committed.

boolean

form

No

emailFlags[review_email_project_members]

Email members and moderators when a new review is requested.

boolean

form

No

defaults

An optional array of defaults at a project level (for example default reviewers).

array

form

No

retainDefaultReviewers

An optional to retain the default reviewers.

boolean

form

No

minimumUpVotes

An optional to set the minimum number of up votes required.

string

form

No

Example responses

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject",
    "branches": [ ],
    "defaults": {
      "reviewers": [ ]
    },
    "deleted": false,
    "deploy": {
      "enabled": false,
      "url": null
    },
    "description": "My project is great",
    "emailFlags": [ ],
    "jobview": null,
    "members": [
      "bruno"
    ],
    "minimumUpVotes": null,
    "name": "testProject",
    "owners": [ ],
    "private": false,
    "retainDefaultReviewers": false,
    "subgroups": [ ],
    "tests": {
      "enabled": false,
      "url": null
    },
    "workflow": null
  },
  "readme": "",
  "mode": "add"
}

Successful Response:

HTTP/1.1 200 OK

{
  "project": {
    "id": "project-x",
    "branches": [ ],
    "defaults": {
      "reviewers": {
        "users": {
          "bruno": {
            "required": "1"
          }
        }
      }
    },
    "deleted": false,
    "deploy": {
      "enabled": false,
      "url": null
    },
    "description": "This project is temporary until project Z replaces it",
    "emailFlags": [ ],
    "jobview": null,
    "members": [
      "swarm"
    ],
    "minimumUpVotes": null,
    "name": "project x",
    "owners": [ ],
    "private": false,
    "retainDefaultReviewers": false,
    "subgroups": [ ],
    "tests": {
      "enabled": false,
      "url": null
    },
    "workflow": null
  },
  "readme": "",
  "mode": "add"
}

Example usage

Creating a new project

To create a project:

curl -u "username:password" \
     -X POST \
     -d "name=TestProject 3" \
     -d "description=The third iteration of our test project." \
     -d "members[]=alice" \
     -d "members[]=bob" \
     "https://my-swarm-host/api/v9/projects/"

Swarm responds with the new project entity:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject-3",
    "branches": [ ],
    "defaults": {
      "reviewers": [ ]
    },
    "deleted": false,
    "deploy": {
      "enabled": false,
      "url": null
    },
    "description": "The third iteration of our test project.",
    "emailFlags": [ ],
    "jobview": null,
    "members": [
      "bruno",
      "swarm"
    ],
    "minimumUpVotes": null,
    "name": "TestProject 3",
    "owners": [ ],
    "private": false,
    "retainDefaultReviewers": false,
    "subgroups": [ ],
    "tests": {
      "enabled": false,
      "url": null
    },
    "workflow": null
  },
  "readme": "",
  "mode": "add"
}

Creating a private project with branches

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch - an example of this accompanies the PATCH endpoint documentation.

Projects are public by default. To mark a project as private, set the private parameter to true.

curl -u "username:password" \
     -X POST \
     -d "name=TestProject 4" \
     -d "description=The 4th iteration of our test project." \
     -d "private=true" \
     -d "members[]=bob" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     "https://my-swarm-host/api/v9/projects"

Swarm responds with the new project entity:

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject-4",
    "branches": [ ],
    "defaults": {
      "reviewers": [ ]
    },
    "deleted": false,
    "deploy": {
      "enabled": false,
      "url": null
    },
    "description": "The 4th iteration of our test project.",
    "emailFlags": [ ],
    "jobview": null,
    "members": [
      "bruno"
    ],
    "minimumUpVotes": null,
    "name": "TestProject 4",
    "owners": [ ],
    "private": true,
    "retainDefaultReviewers": false,
    "subgroups": [ ],
    "tests": {
      "enabled": false,
      "url": null
    },
    "workflow": null
  },
  "readme": "",
  "mode": "add"
}

Edit a Project

Summary

Edit a Project

PATCH /api/v9/projects/{id}

Description

Change the settings of a project in Swarm. If a project has owners set, only the owners can perform this action.

Tip
  • 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

name

Project Name (changing the project name does not change the project ID)

string

form

No

members

An array of project members.

array

form

No

subgroups

An optional array of project subgroups.

array

form

No

owners

An optional array of project owners.

array

form

No

description

Your project description.

string

form

No

private

Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false)

boolean

form

No

deploy

Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"}

array

form

No

tests

Configuration for testing/continuous integration.

array

form

No

branches

Optional branch definitions for this project.

array

form

No

jobview

A jobview for associating certain jobs with this project.

string

form

No

emailFlags[change_email_project_users]

Email members, moderators and followers when a change is committed.

boolean

form

No

emailFlags[review_email_project_members]

Email members and moderators when a new review is requested.

boolean

form

No

defaults

An optional array of defaults at a project level (for example default reviewers).

array

form

No

retainDefaultReviewers

An optional to retain the default reviewers.

boolean

form

No

minimumUpVotes

An optional to set the minimum number of up votes required.

string

form

No

Example response

Successful Response:

HTTP/1.1 200 OK

{  
  "project":{  
    "id":"project1",
    "branches":[  
      {  
        "name":"main",
        "paths":[  
          "//depot/dev/APIProject/..."
        ],
        "id":"main",
        "moderators":[ ],
        "moderators-groups":[ ],
        "defaults":{  
          "reviewers":[ ]
        },
        "workflow":null,
        "retainDefaultReviewers":false,
        "minimumUpVotes":null
      }
    ],
    "defaults":{  
      "reviewers":[ ]
    },
    "deleted":false,
    "deploy":{  
      "enabled":false,
      "url":""
    },
    "description":"Updated description",
    "emailFlags":[ ],
    "jobview":"",
    "members":[  
      "swarm-admin"
    ],
    "minimumUpVotes":null,
    "name":"API Project",
    "owners":[ ],
    "private":false,
    "retainDefaultReviewers":false,
    "subgroups":[ ],
    "tests":{  
      "enabled":false,
      "url":""
    },
    "workflow":null
  },
  "readme":"",
  "mode":"edit"
}

Example usage

Editing a project

To edit a project:

Note

It is safe to edit a project without specifying branches, but the instructions for adding branches contain important information for modifying branch configuration.

curl -u "username:password" \
     -X PATCH
     -d "description=Witness the power of a fully operational Swarm project." \
     "https://my-swarm-host/api/v9/projects/jam"

Swarm responds with the updated project entity:

HTTP/1.1 200 OK

{  
  "project":{  
    "id":"jam",
    "branches":[  
      {  
        "id":"main",
        "name":"Main",
        "workflow":null,
        "paths":[  
          "\/\/depot\/Jam\/MAIN\/..."
        ],
        "defaults":{  
          "reviewers":[ ]
        },
        "minimumUpVotes":null,
        "retainDefaultReviewers":false,
        "moderators":[ ],
        "moderators-groups":[ ]
      },
      {  
        "id":"release-2-1",
        "name":"Release 2.1",
        "workflow":null,
        "paths":[  
          "\/\/depot\/Jam\/REL2.1\/..."
        ],
        "defaults":{  
          "reviewers":[ ]
        },
        "minimumUpVotes":null,
        "retainDefaultReviewers":false,
        "moderators":[ ],
        "moderators-groups":[ ]
      },
      {  
        "id":"release-2-2",
        "name":"Release 2.2",
        "workflow":null,
        "paths":[  
          "\/\/depot\/Jam\/REL2.2\/..."
        ],
        "defaults":{  
          "reviewers":[ ]
        },
        "minimumUpVotes":null,
        "retainDefaultReviewers":false,
        "moderators":[ ],
        "moderators-groups":[ ]
      }
    ],
    "defaults":{  
      "reviewers":[ ]
    },
    "deleted":false,
    "deploy":{  
      "enabled":false,
      "url":""
    },
    "description":"Witness the power of a fully operational Swarm project.",
    "emailFlags":{  
      "change_email_project_users":"1",
      "review_email_project_members":"1"
    },
    "jobview":"",
    "members":[  
      "alex_qc",
      "pubuser"
    ],
    "minimumUpVotes":null,
    "name":"Jam",
    "owners":[  
      "bruno"
    ],
    "private":false,
    "retainDefaultReviewers":false,
    "subgroups":[  
      "Administrators"
    ],
    "tests":{  
      "enabled":false,
      "url":"",
      "postBody":"",
      "postFormat":"URL"
    },
    "workflow":"1"
  },
  "readme":"",
  "mode":"edit"
}		

Editing a project to add a moderated branch and make the project public

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch.

Important

If you have existing branches, you must specify all of them in the query to avoid data loss. This operation sets the value of the entire branches property to match the provided input.

To change a private project to public, set the private parameter to false.

curl -u "username:password" \
     -X PATCH \
     -d "private=false" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[1][name]=Branch Two" \
     -d "branches[1][paths][]=//depot/main/SecondBranch/..." \
     -d "branches[1][moderators][]=bob" \
     -d "branches[1][moderators-groups][]=group1" \
     "https://my-swarm-host/api/v9/projects/testproject-4"

Swarm responds with the new project entity:

HTTP/1.1 200 OK

{  
  "project":{
    "id":"testproject-4",
    "branches":[  
      {  
        "name":"Branch One",
        "paths":[  
          "//depot/main/TestProject/..."
        ],
        "id":"branch-one",
        "moderators":[ ],
        "moderators-groups":[ ],
        "defaults":{  
          "reviewers":[ ]
        },
        "workflow":null,
        "retainDefaultReviewers":false,
        "minimumUpVotes":null
      },
      {  
        "name":"Branch Two",
        "paths":[  
          "//depot/main/SecondBranch/..."
        ],
        "moderators":[  
          "non-admin"
        ],
        "moderators-groups":[  
          "group1"
        ],
        "id":"branch-two",
        "defaults":{  
          "reviewers":[ ]
        },
        "workflow":null,
        "retainDefaultReviewers":false,
        "minimumUpVotes":null
      }
    ],
    "defaults":{  
      "reviewers":[ ]
    },
    "deleted":false,
    "deploy":{  
      "enabled":false,
      "url":""
    },
    "description":"Updated description",
    "emailFlags":[ ],
    "jobview":null,
    "members":[  
      "non-admin"
    ],
    "minimumUpVotes":null,
    "name":"testproject-4",
    "owners":[ ],
    "private":false,
    "retainDefaultReviewers":false,
    "subgroups":[ ],
    "tests":{  
      "enabled":false,
      "url":""
    },
    "workflow":null
  },
  "readme":"",
  "mode":"edit"
}

Editing a project to add default reviewers

curl -u "<user>:<password>" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '"defaults":{"reviewers":{"swarm_admin":{"required":true}} \
         "branches":[{ \
           "name":"dev", \
           "paths":{"//depot/dev/API Project/..."} \
           "defaults": { \
               "reviewers":{ \
                   "groups":{"group1":{"required":"1"}}, \
                   "users":{"non_admin":{"required":true}} \
               } \
           }]' \
     "https://my-swarm-host/api/v9/projects/API Project"

Or without JSON content:

curl -u "username:password" \
     -X PATCH \
     -d "name=Udated description" \
     -d "defaults[reviewers][swarm_admin][required]=true" \
     -d "branches[0][name]=dev" \
     -d "branches[0][paths][]=//depot/dev/API Project/..." \
     -d "branches[0][defaults][reviewers][groups][group1][required]=1" \
     -d "branches[0][defaults][reviewers][users][non_admin][required]=true" \
     "https://my-swarm-host/api/v9/projects/API Project"

Swarm responds with project entity similar to:

HTTP/1.1 200 OK

{  
  "project":{  
    "id":"api-project",
    "branches":[  
      {  
        "name":"dev",
        "paths":[  
          "//depot/dev/APIProject/..."
        ],
        "defaults":{  
          "reviewers":{  
            "users":{  
              "non-admin":{  
                "required":true
              }
            },
            "groups":{  
              "group1":{  
                "required":"1"
              }
            }
          }
        },
        "id":"dev",
        "moderators":[ ],
        "moderators-groups":[ ],
        "workflow":null,
        "retainDefaultReviewers":false,
        "minimumUpVotes":null
      }
    ],
    "defaults":{  
      "reviewers":{  
        "users":{  
          "swarm-admin":{  
            "required":true
          }
        }
      }
    },
    "deleted":false,
    "deploy":{  
      "enabled":false,
      "url":""
    },
    "description":"Updated description",
    "emailFlags":[ ],
    "jobview":null,
    "members":[  
      "swarm-admin"
    ],
    "minimumUpVotes":null,
    "name":"API Project",
    "owners":[ ],
    "private":false,
    "retainDefaultReviewers":false,
    "subgroups":[ ],
    "tests":{  
      "enabled":false,
      "url":""
    },
    "workflow":null
  },
  "readme":"",
  "mode":"edit"
}

Delete a Project

Summary

Delete a Project

DELETE /api/v9/projects/{id}

Description

Mark a Swarm project as deleted. The project ID and name cannot be reused. If a project has owners set, only the owners can perform this action.

Tip
  • 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

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "id": "testproject"
}

Example usage

Deleting a project:

Super users, administrators, and owners can delete projects. Members can delete projects that have no owners set.

curl -u "username:password" -X DELETE "https://my-swarm-host/api/v9/projects/testproject3"

Assuming that the authenticated user has permission, Swarm responds with the id of the deleted project:

HTTP/1.1 200 OK

{
  "id": "testproject3"
}