Documentation | 2025.1

# Files: Swarm files

## Get file data

### Summary

Get file data for the specified file

GET /api/v11/files/{id}

### Description

Get file data for the specified file.

You must be authenticated to view the file information.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | File ID, this is the full filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: BASE64 Decode and Encode. | string | path | Yes
fileRevision | Specify the revision of the file using one of the following options: Specific file revision number: fileRevision=#nnn File revision in a pending or submitted changelist: fileRevision=@=nnn File revision in a submitted changelist only: fileRevision=@nnn Where nnn is the revision or changelist number you want. | string | query | No

### Example usage

#### Get file data for a specific revision of a file

Get file data for //depot/main/myfile.txt revision 3. The full filepath and filename must be encoded in URL safe Base64.

curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9kZXBvdC9tYWluL215ZmlsZS50eHQ?fileRevision=#3"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "filename":"//depot/main/myfile.txt"
        "contentLink": "http://myswarm-url/view/depot/main/myfile.txt",
        "fileRevision": "#3",
        "contentType": "text/plain",
        "changeId": "12871"
      }
    }

#### If a request fails

<error code>:

- 400 Invalid file revision specified. Must be one of the following: @ or @= followed by the changelist number, or # followed by the file revision number.
- 403 Insufficient permissions to access the file
- 404 File does not exist

    HTTP/1.1 <response error code>

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

## Get a file diff

### Summary

Get a file diff for the specified file

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

### Description

Get a file diff for the specified file

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | File ID, this is the full filepath including the filename for the diff encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: BASE64 Decode and Encode. | string | path | Yes
from | Specify the file revision to compare against in the form %23{revision-number}. This is the revision that would be displayed on the left side of a Swarm diff. If the from parameter is not specified, the head The most recent revision of a file within the depot. Because file revisions are numbered sequentially, this revision is the highest-numbered revision of that file. revision is used. | string | query | No
to | Specify the file revision being compared in the form %23{revision-number}. This is the revision that would be displayed on the right side of a Swarm diff. | string | query | Yes
type | Specify the file type for the diff: file: All file types except stream specs. This is the default if the parameter is unset. stream: Stream spec files. | string | query | No
lines | Specify the number of lines of context around each diff returned in the response. | integer | query | No
ignoreWs | Specify the whitespace options for the diff: Whitespace characters such as space, tab, and newline characters are returned in the response. This is the default if the parameter is unset. 0: Whitespace characters such as space, tab, and newline characters are not returned in the response. 1: Whitespace changes are not highlighted. Used for file types where whitespace changes are not important. 2: Whitespace changes are highlighted. Used for file types where whitespace is important. | integer | query | No
maxSize | Specify the maximum sized file that can be returned as a diff: -1: Unlimited file size. nnnn: where nnnn is the maximum file size in bytes. 0: Use the file size specified by the max_size configuration setting, see max_size. This is the default if the parameter is unset. The lowest max_size value defaults to 50 bytes. If you set the max_size value lower than 50 bytes then Swarm will ignore it. When a file is in the edit state, depending on the max_size value, the following two flags are set in the response: fetchContent: This flag determines if the size of a file is larger than the max_size value and accordingly enables or disables the show more context buttons in the file diff panel. For more information about the show more context buttons, see File diff panel. Files larger than the max_size value sets the fetchContent flag to false. When the fetchContent flag is set to false, all the show more context buttons in the file diff panel are disabled. When the fetchContent flag is set to true, all the show more context buttons in the file diff panel are enabled. isCut: This flag determines if a file diff size is larger than the max_size value and must be truncated. File diff sizes larger than the max_size value sets the isCut flag value to the max_size value which truncates the diff. When the file diff size is smaller than the max_size value, the isCut flag is set to false. | integer | query | No
maxDiffs | Specify the maximum number of diff sections (chunks) to return in the response: -1: Returns an unlimited number of diff sections (chunks)in the response. nnnn: where nnnn is the maximum number of diff sections (chunks) returned in the response. 0: Return the number of diffs specified by the max_diffs configuration setting in the response, see max_diffs. This is the default if the parameter is unset. | integer | query | No
offset | Specify the diff section (chunk) to start displaying from. The number of diff sections displayed from the offset parameter value is governed by the maxDiffs parameter value specified. For example, if you just want to return the third diff section, set offset=2 and maxDiffs=1. | integer | query | No
fromFile | If the file has been moved or renamed, and edited, use the fromFile parameter to specify the original filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the fromFile to URL safe Base64, for example: BASE64 Decode and Encode. | string | query | No

### Example usage

#### Get a file diff

Get the file diff between revisions 233 and 234 of //projects/acme/main/src/aliqitaq/quosquo/do/53.txt and don't return whitespace characters. The full filepath and filename must be encoded in URL safe Base64.

curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9wcm9qZWN0cy9hY21lL21haW4vc3JjL2FsaXFpdGFxL3F1b3NxdW8vZG8vNTMudHh0/diff?from=%233&to=%234&ignoreWs=0&type=file"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "isCut": false,
        "isSame": false,
        "header": "--- a///projects/acme/main/src/aliqitaq/quosquo/do/53.txt#3\n+++ b///projects/acme/main/src/aliqitaq/quosquo/do/53.txt#4\n",
        "summary": {
          "adds": 1,
          "deletes": 0,
          "updates": 0
        },
        "diffs": [
          "@@ -30,10 +30,12 @@\n このリリースは、バージョン1.0.1g の OpenSSL ライブラリをリンクすること\n によって、Heartbleed CVE-2014-0160 脆弱性に対処しています。\n \n --------------------------------------------------------------------------\n \n+Hello\n+\n 以前のリリースとの互換性\n -------------------------\n \n  1. PERFORCE ブローカは、2007.2以降にリリースされたPERFORCE クライアント及び\n     サーバと互換性があります。 \n"
        ],
        "paging": {
          "diffs": 1,
          "offset": null
        }
      }
    }

#### Get a file diff when the file size is greater than max_size value

Get the file diff between revisions 232 and 40 of //jam/main/src/compile3.c and don't return whitespace characters. The full filepath and filename must be encoded in URL safe Base64. In the response code, the fetchContent flag is set to false as the file size is greater than the max_size value.

curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9qYW0vbWFpbi9zcmMvY29tcGlsZTMuYw/diff?from=%232&to=%40%3D13444&ignoreWs=0&type=file"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
          "isCut": 1000,
          "isSame": false,
          "header": "--- a///jam/main/src/compile3.c#2\n+++ b///jam/main/src/compile3.c@=13444\n",
          "summary": {
              "adds": 1,
              "deletes": 3,
              "updates": 3
          },
          "fetchContent": false,
          "diffs": [
              "@@ -23357,11 +23357,10 @@\n  *\tcompile_set() - compile the \"set variable\" statement\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n  *\n  *\tcompile_foreach() - compile the \"for x in y\" statement\n  *\tcompile_if() - compile 'if' rule\n  *\tcompile_include() - support for 'include' - call include() on file\n  *\tcompile_local() - declare (and set) local variables\n",
              "@@ -24981,24 +24980,10 @@\n  *\tcompile_set() - compile the \"set variable\" statement\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n- *\n- *\tcompile_foreach() - compile the \"for x "
          ],
          "paging": {
              "diffs": 2,
              "offset": null
          }
       }
    }

#### Get a file diff when the file size is not greater than max_size value

Get the file diff between revisions 232 and 40 of //jam/main/src/compile3.c and don't return whitespace characters. The full filepath and filename must be encoded in URL safe Base64. In the response code, the fetchContent flag is set to true as the file size is not greater than the max_size value.

curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9qYW0vbWFpbi9zcmMvY29tcGlsZTMuYw/diff?from=%232&to=%40%3D13444&ignoreWs=0&type=file"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
          "isCut": false,
          "isSame": false,
          "header": "--- a///jam/main/src/compile3.c#2\n+++ b///jam/main/src/compile3.c@=13444\n",
          "summary": {
              "adds": 1,
              "deletes": 3,
              "updates": 3
          },
          "fetchContent": true,
          "diffs": [
              "@@ -23357,11 +23357,10 @@\n  *\tcompile_set() - compile the \"set variable\" statement\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n  *\n  *\tcompile_foreach() - compile the \"for x in y\" statement\n  *\tcompile_if() - compile 'if' rule\n  *\tcompile_include() - support for 'include' - call include() on file\n  *\tcompile_local() - declare (and set) local variables\n",
              "@@ -24981,24 +24980,10 @@\n  *\tcompile_set() - compile the \"set variable\" statement\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n- *\n- *\tcompile_foreach() - compile the \"for x in y\" statement\n- *\tcompile_if() - compile 'if' rule\n- *\tcompile_include() - support for 'include' - call include() on file\n- *\tcompile_local() - declare (and set) local variables\n- *\tcompile_null() - do nothing -- a stub for parsing\n- *\tcompile_rule() - compile a single user defined rule\n- *\tcompile_rules() - compile a chain of rules\n- *\tcompile_set() - compile the \"set variable\" statement\n- *\tcompile_setcomp() - support for `rule` - save parse tree \n- *\tcompile_setexec() - support for `actions` - save execution string \n- *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n- *\tcompile_switch() - compile 'switch' rule\n */\n /*\n  * Copyright 1993, 1995 Christopher Seiwald.\n  * * External routines:\n  *\n",
              "@@ -36086,10 +36071,18 @@\n  *\tcompile_set() - compile the \"set variable\" statement\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n+ **\n+ ** Adding new block\n+  ** Adding new block\n+   ** Adding new block\n+    ** Adding new block\n+     ** Adding new block\n+      ** Adding new block\n+       ** Adding new block\n  * * External routines:\n  *\n  *\tcompile_foreach() - compile the \"for x in y\" statement\n  *\tcompile_if() - compile 'if' rule\n  *\tcompile_include() - support for 'include' - call include() on file\n",
              "@@ -57336,23 +57329,10 @@\n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n  * * External routines:\n  *\n- *\tcompile_foreach() - compile the \"for x in y\" statement\n- *\tcompile_if() - compile 'if' rule\n- *\tcompile_include() - support for 'include' - call include() on file\n- *\tcompile_local() - declare (and set) local variables\n- *\tcompile_null() - do nothing -- a stub for parsing\n- *\tcompile_rule() - compile a single user defined rule\n- *\tcompile_rules() - compile a chain of rules\n- *\tcompile_set() - compile the \"set variable\" statement\n- *\tcompile_setcomp() - support for `rule` - save parse tree \n- *\tcompile_setexec() - support for `actions` - save execution string \n- *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n- *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n  *\n  *\tcompile_foreach() - compile the \"for x in y\" statement\n  *\tcompile_if() - compile 'if' rule\n  *\tcompile_include() - support for 'include' - call include() on file\n  *\tcompile_local() - declare (and set) local variables\n",
              "@@ -99842,11 +99822,11 @@\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n  * * External routines:\n- *\n+ *****\n  *\tcompile_foreach() - compile the \"for x in y\" statement\n  *\tcompile_if() - compile 'if' rule\n  *\tcompile_include() - support for 'include' - call include() on file\n  *\tcompile_local() - declare (and set) local variables\n  *\tcompile_null() - do nothing -- a stub for parsing\n",
              "@@ -99870,11 +99850,34 @@\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n  * * External routines:\n- *\n+ * **\n+ ***\n+ ***\n+ ***\n+  * **\n+ ***\n+ ***\n+ ***\n+  * **\n+ ***\n+ ***\n+ ***\n+  * **\n+ ***\n+ ***\n+ ***\n+  * **\n+ ***\n+ ***\n+ ***\n+  * **\n+ ***\n+ ***\n+ ***\n  *\tcompile_foreach() - compile the \"for x in y\" statement\n  *\tcompile_if() - compile 'if' rule\n  *\tcompile_include() - support for 'include' - call include() on file\n  *\tcompile_local() - declare (and set) local variables\n  *\tcompile_null() - do nothing -- a stub for parsing\n",
              "@@ -99968,11 +99971,11 @@\n  *\tcompile_setcomp() - support for `rule` - save parse tree \n  *\tcompile_setexec() - support for `actions` - save execution string \n  *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n  *\tcompile_switch() - compile 'switch' rule\n  * * External routines:\n- *\n+ *****\n  *\tcompile_foreach() - compile the \"for x in y\" statement\n  *\tcompile_if() - compile 'if' rule\n  *\tcompile_include() - support for 'include' - call include() on file\n  *\tcompile_local() - declare (and set) local variables\n  *\tcompile_null() - do nothing -- a stub for parsing\n"
          ],
          "paging": {
              "diffs": 7,
              "offset": null
              }
         }
    }

#### If a request fails

<error code>:

- 400 Invalid file revision specified.
- 404 File 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
    }

## File edit

- This API endpoint only supports text files.

- File edit is a Technology Preview feature.

  Features offered in Technology Preview are experimental and not guaranteed to always work as expected. If you have feedback and functionality suggestions, email techpreview@perforce.com.

### Summary

Edit the file content and submit or shelve the file

PUT /api/v11/files/{id}

### Description

Edit the file content and submit or shelve the file.

Requirements:

- You must have permissions to edit the file.
- If the file version changes while you are editing it or if you are not editing the Head The most recent revision of a file within the depot. Because file revisions are numbered sequentially, this revision is the highest-numbered revision of that file. revision of the file, committing your file changes will overwrite the current head revision of the file.

If you are unsure, shelving your change is a safer option because it will not overwrite the head revision of the file and you can do a manual resolve when you commit the shelf.

- File edit is enabled by default but can be disabled by your Swarm administrator, see allow_edits.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | File ID, this is the full filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: BASE64 Decode and Encode | string | path | Yes
content | Specify the entire file content to be shelved or submitted. Lines in the content must be separated with backslash and n characters \n. | string | body | Yes
description | Specify a changelist description. Optional: you can create a review for your change or add it to an existing review by including a review keyword in the Change description. For instruction on creating a review and adding a changelist to a review using review keywords, see Create a review and Add a changelist to a review. | string | body | No
action | Specify the file action as either shelve or submit. | string | body | Yes

### Example usage

#### Shelve file with edited content

Shelve //depot/main/myfile.txt file with edited content. The full filepath and filename must be encoded in URL safe Base64.

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/files/Ly9kZXBvdC9tYWluL215ZmlsZS50eHQ"

The "mybodyfilename.txt" file contains the file content, description and the shelve action:

    {
      "content": "My original line\nMy nice new line\nAnother original line"
      "description": "Added a new line."
      "action": "shelve"
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "filename":"//depot/main/myfile.txt"
        "contentLink": "http://myswarm-url/view/depot/main/myfile.txt",
        "fileRevision": "@=12896",
        "contentType": "text/plain",
        "changeId": "12896"
      }
    }

#### If a request fails

<error code>:

- 400 Invalid file revision specified. Must be one of the following: @ or @= followed by the changelist number, or # followed by the file revision number.
- 403 Insufficient permissions to submit or shelve the file
- 404 File does not exist
- 500 Submit command failed because a newer revision of the file exists, you must resolve and submit your changes or revert your changes.

    HTTP/1.1 <response error code>

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

Your search for returned results