API User's Guide

Working with object attachments

Introduced in 2022.2

Updated in 2024

The API allows working with object attachments. There are two ways to interact with attachments via the API:

  • Direct interaction with attachments - This article focuses on this approach, providing details on how to perform various operations directly with attachments.

  • Attaching files as part of actions – In this method, attachments are added to specific objects as part of a workflow action. For details, see Adding attachments and links while running workflow actions.

Access level

The level of access an API user has to Alloy Navigator is the same, whether the user accesses Alloy Navigator over the API or any other module. That's why adding or removing attachments from objects requires the Modify access permission on those objects.

Authorization HTTP header

When the API is configured for Access Token authentication, all API requests require the Authorization HTTP header.

Authorization: bearer <token>

Available API methods

These API methods are available for working with attachments:

Listing object attachments

The following requests retrieve a list of attachments of a particular object.

GET {{baseUrl}}/Object/{objectId}/Attachments

POST {{baseUrl}}/Object/{objectId}/Attachments

where:

  • baseUrl - the API URL, such as http://www.example.com/api/v2/
  • objectId - the object ID (GUID or OID)

You can use the same GET and POST parameters as in API requests for listing objects (sorting, filtering, object fields, etc.). For details, see Retrieving object activities (GET) and Retrieving object activities (POST).

Response
{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Fields": [
			{
				"Name": "ID",
				"DataType": "guid",
				"Caption": "ID"
			},
			{
				"Name": "...",
				"DataType": "...",
				"Caption": "..."
			},
			{
				"Name": "Created_Date",
				"DataType": "datetime",
				"Caption": "Created Date"
			}
		],
		"Data": [
			[
				"{6D978EE7-7B88-499F-89FB-3B73C4DFE801}",
				"5",
				"2022-10-12.log",
				"File",
				"2022-10-25T11:11:16-07:00"
			],
			[
				"{7B5B7027-E73C-4003-8AD6-4A0478D3AAED}",
				"",
				"Lorem.docx",
				"File",
				"2022-09-13T10:40:51-07:00"
			]
			// Add more entries as needed
		]
	}
}

INFO: For sample PowerShell scripts, see PowerShell: Listing attachments (GET) and PowerShell: Listing attachments (POST).

Getting attachment contents

The following request obtains the contents of a specific object attachment. The attachment contents are base64 encoded.

GET {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}/content

where:

  • baseUrl - the API URL, such as http://www.example.com/api/v2/
  • objectId - the object ID (GUID or OID)
  • attachmentId - the attachment ID (GUID)
Response:
{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Data": "UEsDBBQABgAIAA...AAA==",
		"FileName": "Lorem.docx",
		"Description": "Sample file",
		"Size": 14161
	}
}
Downloading attachments

The following request downloads a specific object attachment.

GET {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}/download

where:

  • baseUrl - the API URL, such as http://www.example.com/api/v2/
  • objectId - the object ID (GUID or OID)
  • attachmentId - the attachment ID (GUID)
Response

The response is just a stream of binary data.

In addition to standard response headers (Content-Type, Content-Length, Content-Disposition), a special header is used: attachment-file-name: "file_name". Using that header allows you to immediately get the file name, without parsing the Content-Disposition header string.

Error
{
	"success": false,
	"errorCode": 101,
	"errorText": "You do not have enough permissions to access this item.",
	"responseObject": null
}

INFO: For a sample PowerShell script, see PowerShell: Downloading attachments.

Adding attachments and links to objects

The following request adds an attachment or link directly to a specific object.

PUT {{baseUrl}}/Object/{objectId}/Attachments

where:

  • baseUrl - the API URL, such as http://www.example.com/api/v2/
  • objectId - the object ID (GUID or OID)

The file name and the file contents (base64 encoded) must be specified in the request body, as follows:

{
	"FileName": "Hello.txt",
	"Description": "Sample file",
	"Data": "SGVsbG8h"
}

You can add multiple attachments, as follows:

[
	{
		"FileName": "Hello.txt",
		"Description": "Sample file",
		"Data": "SGVsbG8h"
	},
	{
		"FileName": "Hello2.txt",
		"Data": "SGVsbG8h"
	}
]

To attach a link to an object, use the IsLink property set to true in your JSON request:

[
	{
		"FileName": "Hello.txt",
		"Description": "Sample link",
		"Data": "",
		"IsLink": true		
	}
]

IMPORTANT: Ensure that the Data property is empty when IsLink is set to true to avoid an invalid combination error.

Response
{
	"success":true,
	"errorCode":0,
	"errorText":"",
	"responseObject":null
}

INFO: For a sample PowerShell script, see PowerShell: Adding attachments.

Removing attachments

The following request removes a specific object attachment.

DELETE {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}

where:

  • baseUrl - the API URL, such as http://www.example.com/api/v2/
  • objectId - the object ID (GUID or OID)
  • attachmentId - the attachment ID (GUID)
Response
{
	"success":true,
	"errorCode":0,
	"errorText":"",
	"responseObject":null
}
Updating attachment descriptions

The following request updates an attachment description.

PATCH {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}

where:

  • baseUrl - the API URL, such as http://www.example.com/api/v2/
  • objectId - the object ID (GUID or OID)
  • attachmentId - the attachment ID (GUID)

The new description must be specified in the request body, as follows:

{
	"Description": "New description"
}

The only available attachment modification is updating the attachment description.

INFO: For a sample PowerShell script, see PowerShell: Updating attachment descriptions.