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": ""
},
"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
},
{
...
<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:
- Using an array of top level fields:
curl -u "username:ticket" "https://my-swarm-host/api/v11/projects?fields=id,description,members"
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:
- Using an array of top level fields:
curl -u "username:ticket" "https://my-swarm-host/api/v11/projects/jam?fields=id,description,members"
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 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 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 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 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.
- 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:
- 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
}