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.

Note

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.

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

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

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

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 Add a project.

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
}