Documentation | 2025.1

# Changes: Swarm changes

## Get a list of changes

### Summary

Get a list of changes.

GET /api/v11/changes

### Description

Get a list of changes the user is able to view.

- 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
--- | --- | --- | --- | ---
pending | Determines if all changelists, only pending changelists, or only submitted changelists are returned by the request. Not set: All changelists (submitted and pending) are returned. true: Only pending changelists are returned. false: Only submitted changelists are returned. | boolean | query | No
user | The user parameter enables you to return just the changelists created by a specific user. | string | query | No
rootPath | The rootPath parameter enables you to return all the changelists in a specific root path. The rootPath parameter is encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: https://www.base64encode.org | string | query | No

### Example usage

#### Get a list of changes

curl -u "username:ticket" "https://myswarm-url/api/v11/changes"

Swarm responds with the changes starting with the newest change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "changes": [
          {
            "id": 12853,
            "date": "2022/04/14 08:59:59",
            "client": "swarm-test",
            "user": "bruno",
            "status": "submitted",
            "type": "public",
            "importedBy": null,
            "identity": null,
            "description": "Fix display bug. ",
            "jobStatus": null,
            "jobs": [],
            "stream": null,
            "files": [
              "//depot/main/myfile.txt#6"
            ]
          },
          {
          ...
          <other change ids formatted as above>
          ...
          }
        ]
      }
    }

#### Get a list of the pending changes

curl -u "username:ticket" "https://myswarm-url/api/v11/changes?pending=true"

Swarm responds with a list of pending changes starting with the newest pending change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "changes": [
          {
            "id": 12382,
            "date": "2022/04/10 12:59:59",
            "client": "swarm-test",
            "user": "paula.boyle",
            "status": "pending",
            "type": "public",
            "importedBy": null,
            "identity": null,
            "description": "Update license details. ",
            "jobStatus": null,
            "jobs": [],
            "stream": null,
            "files": [
              "//depot/main/license.txt#2"
            ]
          },
          {
          ...
          <other change ids formatted as above>
          ...
          }
        ]
      }
    }

#### Get a list of changes created by Bruno

curl -u "username:ticket" "https://myswarm-url/api/v11/changes?user=bruno"

Swarm responds with the changes created by Bruno starting with the newest change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "changes": [
          {
            "id": 12853,
            "date": "2022/04/14 08:59:59",
            "client": "swarm-test",
            "user": "bruno",
            "status": "submitted",
            "type": "public",
            "importedBy": null,
            "identity": null,
            "description": "Fix display bug. ",
            "jobStatus": null,
            "jobs": [],
            "stream": null,
            "files": [
              "//depot/main/myfile.txt#6"
            ]
          },
          {
          ...
          <other change ids formatted as above>
          ...
          }
        ]
      }
    }

#### Get a list of changes in //depot/Jam/MAIN/...

//depot/Jam/MAIN/... encoded to URL safe Base64 is Ly9kZXBvdC9KYW0vTUFJTi8uLi4=.

curl -u "username:ticket" "https://myswarm-url/api/v11/changes?rootPath=Ly9kZXBvdC9KYW0vTUFJTi8uLi4="

Swarm responds with changelists in //depot/Jam/MAIN/... starting with the newest change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "changes": [
          {
            "id": 12853,
            "date": "2022/04/14 08:59:59",
            "client": "swarm-test",
            "user": "paula.boyle",
            "status": "pending",
            "type": "public",
            "importedBy": null,
            "identity": null,
            "description": "Update the XML and Word files. ",
            "jobStatus": null,
            "jobs": [],
            "stream": null,
            "files": [
              "//depot/Jam/MAIN/src/anotherfile.xml#3",
              "//depot/Jam/MAIN/src/myfile.xml#15",
              "//depot/Jam/MAIN/src/yetanotherfile.docx#4"
            ]
          },
          {
          ...
          <other change ids formatted as above>
          ...
          }
        ]
      }
    }

#### If a request fails

<error code>:

403 Insufficient permissions to access the changes

    HTTP/1.1 <response error code>

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

## Get a list of files on a change

### Summary

Get a list of files on a change.

GET /api/v11/changes/{id}/files

### Description

Get a list of files on a change. You must be authenticated to view the files on the change.

- 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 | Change ID | integer | path | Yes

### Example usage

Get a list of files on change 12106:

curl -u "username:ticket" "https://myswarm-url/api/v11/changes/12106/files"

Swarm responds with a list of files on change 12106:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "root": "//depot/triggers",
        "files": [
          {
            "depotFile": "//depot/triggers/swarm-trigger.conf",
            "action": "add",
            "type": "text",
            "rev": "1",
            "fileSize": "129",
            "digest": "635CC5C20C0C2F3534D94207C7F7FB25"
          },
          {
            "depotFile": "//depot/triggers/swarm-trigger.pl",
            "action": "add",
            "type": "text+x",
            "rev": "1",
            "fileSize": "51239",
            "digest": "0C0E14975CD4E6195E95805DEC98DA03"
          }
        ],
        "limited": false
      }
    }

#### If a request fails

<error code>:

- 403 Insufficient permissions to access the change

- 404 Change does not exist

    HTTP/1.1 <response error code>

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

## Get job information for jobs associated with a change

### Summary

Get job information for jobs associated with a change

GET /api/v11/changes/{id}/jobs

### Description

Get job information for jobs associated with a change. You must be authenticated to view the jobs associated with the change.

- 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 | Change ID | integer | path | Yes

### Example usage

#### Get job information for change 12344

curl -u "username:<ticket>" "https://myswarm-url/api/v11/changes/12344/jobs"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job000020",
            "link": "/jobs/job000020",
            "fixStatus": "open",
            "description": "Fix final bugs for beta release.\n",
            "description-markdown": "<span class=\"first-line\">Fix final bugs for beta release.</span>"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 403 Insufficient permissions to access the change
- 404 Change does not exist

    HTTP/1.1 <response error code>

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

## Add a job to a change

### Summary

Add a job to a change.

PUT /api/v11/changes/{id}/jobs/{job_id}

### Description

Add a job to a change. You must be authenticated to add a job to a change.

- 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 | Change ID | integer | path | Yes
job_id | Job ID | integer | path | Yes

### Example usage

#### Add a job to a change

Add job000020 to change12344

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job000020"

Swarm responds with all of the jobs associated with the change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job000020",
            "link": "/jobs/job000020",
            "fixStatus": "open",
            "description": "Fix final bugs for beta release.\n",
            "description-markdown": "<span class=\"first-line\">Fix final bugs for beta release.</span>"
          }
        ]
      }
    }

#### Add a job to a change that is already associated with another job

Add job001001 to change12344

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job001001"

Swarm responds with all of the jobs associated with the change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job000020",
            "link": "/jobs/job000020",
            "fixStatus": "open",
            "description": "Fix final bugs for beta release.\n",
            "description-markdown": "<span class=\"first-line\">Fix final bugs for beta release.</span>"
          },
          {
            "job": "job001001",
            "link": "/jobs/job001001",
            "fixStatus": "fixed",
            "description": "Bug fixes by Terry\n",
            "descriptionMarkdown": "<span class=\"first-line\">Bug fixes by Terry</span>"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 403 Insufficient permissions to access the change
- 404 Change does not exist
- 500 Job does not exist

    HTTP/1.1 <response error code>

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

## Remove a job from a change

### Summary

Remove a job from a change.

DELETE /api/v11/changes/{id}/jobs/{job_id}

### Description

Remove a job from a change. You must be authenticated to remove a job from a change.

- 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 | Change ID | integer | path | Yes
job_id | Job ID | integer | path | Yes

### Example usage

#### Remove a job from a change

Remove job000020 from change12344:

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job000020"

Swarm responds with all of the jobs associated with the change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": []
      }
    }

#### Remove a job from a change that is associated with more than one job

Remove job000020 from change12344:

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job000020"

Swarm responds with all of the jobs associated with the change:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "jobs": [
          {
            "job": "job001001",
            "link": "/jobs/job001001",
            "fixStatus": "fixed",
            "description": "Bug fixes by Terry\n",
            "description-markdown": "<span class=\"first-line\">Bug fixes by Terry</span>"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 403 Insufficient permissions to access the change
- 404 Change does not exist
- 500 Job does not exist

    HTTP/1.1 <response error code>

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

Your search for returned results