Documentation | 2025.1

# Attachments: Swarm comment attachments

## Get attachments details

### Summary

Get attachment details

GET /api/v11/attachments?ids[]={id}

### Description

Get details of attachments the user has permission to view.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Specify the attachments you want details returned for by specifying attachment ids on the request. | Array of ids (integers) | query | Yes

### Example usage

#### Get details for attachments 1, 2, and 500

curl -u "username:ticket" "https://myswarm-url/api/v11/attachments?ids[]=1&ids[]=2&ids[]=500"

Swarm responds with details for attachment ids 1, 2, and 500:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data" : {
        "attachments": [
          {
            "id": 1,
            "name": "motorbike.png",
            "type": "image/png",
            "size": 19844,
            "depotFile": "//.swarm/attachments/0000000001-motorbike.png",
            "references": {
              "comment": [
                502
              ]
            }
          },
          {
            "id": 2,
            "name": "house.png",
            "type": "image/png",
            "size": 16109,
            "depotFile": "//.swarm/attachments/0000000002-house.png",
            "references": {
              "comment": [
                503
              ]
            }
          },
          {
            "id": 500,
            "name": "car.png",
            "type": "image/png",
            "size": 26123,
            "depotFile": "//.swarm/attachments/0000000500-car.png",
            "references": {
              "comment": [
                890
              ]
            }
          }
        ]
      }
    }

#### If a request fails

<error code>:

404 Attachment does not exist

    HTTP/1.1 <response error code>

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

## Get attachment thumbnail

### Summary

Get the thumbnail of an attachment.

GET /api/v11/attachments/{id}/content/{filename}/thumb

### Description

Get the thumbnail of an attachment the user has permission to view.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Attachment id | integer | query | Yes
filename | This is the attachment filename and extension encoded to URL safe Base64. Various tools are available online to encode the filename to URL safe Base64, for example: BASE64 Decode and Encode. | string | path | Yes

### Example usage

Get the thumbnail for attachment ID 118 ( house.png which is aG91c2UucG5n when encoded in URL safe Base64):

curl -u "username:ticket" "https://myswarm-url/api/v11/attachments/118/content/aG91c2UucG5n/thumb"

Swarm responds with the thumbnail for the attachment.

#### If a request fails

<error code>:

404 Attachment does not exist

    HTTP/1.1 <response error code>

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

## Open an attachment

### Summary

Open an attachment.

GET /api/v11/attachments/{id}/content/{filename}

### Description

Open the attachment the user has permission view.

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Attachment id | integer | query | Yes
filename | This is the attachment filename and extension encoded to URL safe Base64. Various tools are available online to encode the filename to URL safe Base64, for example: BASE64 Decode and Encode. | string | path | Yes

### Example usage

Open attachment ID 118 ( house.png which is aG91c2UucG5n when encoded in URL safe Base64):

curl -u "username:ticket" "https://myswarm-url/api/v11/attachments/118/content/aG91c2UucG5n"

Swarm opens the attachment.

#### If a request fails

<error code>:

404 Attachment does not exist

    HTTP/1.1 <response error code>

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

## Download an attachment

### Summary

Download an attachment.

GET /api/v11/attachments/{id}/content/{filename}/download

### Description

Download the attachment the user has permission to view.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Attachment id | integer | query | Yes
filename | This is the attachment filename and extension encoded to URL safe Base64. Various tools are available online to encode the filename to URL safe Base64, for example: BASE64 Decode and Encode. | string | path | Yes

### Example usage

Download attachment ID 118 ( house.png which is aG91c2UucG5n when encoded in URL safe Base64):

curl -u "username:ticket" "https://myswarm-url/api/v11/attachments/118/content/aG91c2UucG5n/download"

Swarm responds by downloading the attachment.

#### If a request fails

<error code>:

404 Attachment does not exist

    HTTP/1.1 <response error code>

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

## Create an attachment

### Summary

Create an attachment.

POST /api/v11/attachments

### Description

Create a standalone attachment.

Once the attachment is created, Swarm dynamically assigns a unique id to the attachment. To add an attachment to a comment, pass the unique attachment id as a parameter using the Add a comment with an attachment to a review API endpoint.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
file | This is the complete path with the attachment file name. | string | path | Yes

### Example usage

Create an attachment for the house.png file:

curl -X POST -H “Content-Type: multipart/form-data” -u "username:ticket" "https://myswarm-url/api/v11/attachments/" -F "file=@/home/perforce/client1/house.jpg"

Swarm responds with the details of the attachment:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
      "attachments": [
        {
          "id": 12,
          "name": "house.png",
          "type": "image/png",
          "size": 106689,
          "blur": "L1SPX_I,Mw~W~qofa{WV56yDcDkq",
          "depotFile": "//depot/Jam/MAIN/src/attachments/0000000118-house.png",
          "references": []
         }
       ]
      }
    }

#### If a request fails

<error code>:

404 Attachment 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