Projects : Swarm Projects
Get List of Projects
Summary
Get List of Projects and metadata
GET /api/v10/projects
Description
Returns a list of projects in Swarm that are visible to the current user.
- 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 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:password" "https://my-swarm-host/api/v10/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": [
"//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
},
{
...
<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:password" "https://my-swarm-host/api/v10/projects?fields=id,description,members"
curl -u "username:password" "https://my-swarm-host/api/v10/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/v10/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 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:password" "https://my-swarm-host/api/v10/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:password" "https://my-swarm-host/api/v10/projects/jam?fields=id,description,members"
curl -u "username:password" "https://my-swarm-host/api/v10/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
}