CSM Attachment API
-
- UpdatedJan 30, 2025
- 17 minutes to read
- Yokohama
- API reference
The CSM Attachment API provides endpoints that allow both internal and external users to upload, download, and remove attachments associated with a table and to retrieve attachment metadata.
Only attachments associated with tables specified in the glide.rest.attachment_csm_api.allowed_tables system property are valid in any of the associated endpoint calls. Any logged in user, both snc_internal and snc_external, can access this API. Guests and public users do not have access rights.
This API respects any system limitations on uploaded files, such as maximum file size and allowed attachment types. You can control these settings using the com.glide.attachment.max_size and glide.attachment.extensions properties.
By default, this API has a rate limit of 500 per hour for unauthenticated and snc_external users. For more information about rate limiting, see Inbound REST API rate limiting.
CSM Attachment - DELETE /now/attachment_csm/{sys_id}
Deletes the specified attachment.
URL format
Versioned URL: /api/now/{api_version}/attachment_csm/{sys_id}
Default URL: /api/now/v1/attachment_csm/{sys_id}
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
sys_id | Sys_id of the attachment to delete. This attachment must belong to one of the
tables listed within the
glide.rest.attachment_csm_api.allowed_tables property in the
System Properties [sys_properties] table. Data type: String |
Name | Description |
---|---|
None |
Name | Description |
---|---|
None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
None |
Header | Description |
---|---|
None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body parameters (JSON or XML)
Name | Description |
---|---|
None |
Example: Sample cURL request
CSM Attachment - GET /now/attachment_csm
Returns the metadata for multiple attachments.
URL format
Versioned URL: /api/now/{api_version}/attachment_csm
Default URL: /api/now/v1/attachment_csm
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
Name | Description |
---|---|
sysparm_limit | Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.
This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance.
Data type: Number Default: 20 Maximum: 100 |
sysparm_offset | Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the
number of records, in small manageable chunks.
For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use
Data type: Number Default: 0 |
sysparm_query | Required. Encoded query to use to search for attachments. This parameter must at least contain For example:
Syntax: sysparm_query=<col_name><operator><value> .
All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>]. For example:
Encoded queries also supports order by functionality. To sort responses based on certain fields, use the
Syntax:
For example: This query filters all active records and orders the results in ascending order by number, and then in descending order by category. Data type: String |
Name | Description |
---|---|
None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Accept | Data format of the response
body. Supported types: application/json or
application/xml.
Default: application/json |
Header | Description |
---|---|
None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Status code | Description |
---|---|
200 | Successful. The request was successfully processed. |
401 | Unauthorized. The user credentials are incorrect or have not been passed. |
500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
Example: Sample cURL request
CSM Attachment - GET /now/attachment_csm/{sys_id}/file
Returns the file attachment for the specified attachment sys_id.
URL format
Versioned URL: /api/now/{api_version}/attachment_csm/{sys_id}/file
Default URL: /api/now/v1/attachment_csm/{sys_id}/file
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
sys_id | Sys_id of the attachment. This attachment must belong to one of the tables listed within the glide.rest.attachment_csm_api.allowed_tables property in the System Properties [sys_properties]
table. Data type: String Table: Attachments [sys_attachment] |
Name | Description |
---|---|
None |
Name | Description |
---|---|
None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Accept | Data format of the response body. For example, use image/jpeg or
image/png to accept JPEG or PNG image files exclusively. To allow
all image types, specify image/* ; to allow any file type, specify
*/* .Default: */* |
Header | Description |
---|---|
X-Attachment-Metadata | Metadata about the returned file, such as size, name, and file type. |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body parameters
Name | Description |
---|---|
Contents of the attachment. |
Example: Sample cURL request
CSM Attachment - GET /now/attachment_csm/{sys_id}
Returns the metadata for the attachment file with the specific attachment sys_id.
URL format
Versioned URL: /api/now/{api_version}/attachment_csm/{sys_id}
Default URL: /api/now/v1/attachment_csm/{sys_id}
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
sys_id | Sys_id of the attachment record for which to return metadata. This attachment
must belong to one of the tables listed within the
glide.rest.attachment_csm_api.allowed_tables property in the
System Properties [sys_properties] table. Data type: String |
Name | Description |
---|---|
None |
Name | Description |
---|---|
None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Accept | Data format of the response
body. Supported types: application/json or
application/xml.
Default: application/json |
Header | Description |
---|---|
None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body parameters (JSON or XML)
Example: Sample cURL request
CSM Attachment - POST /now/attachment_csm/file
Uploads a specified binary file as an attachment to a specified record.
The endpoint also returns the metadata for the saved attachment.
URL format
Versioned URL: /api/now/{api_version}/attachment_csm/file
Default URL: /api/now/v1/attachment_csm/file
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
Name | Description |
---|---|
<String> | Path to the binary file to attach to the specified record. Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Accept | Data format of the response
body. Supported types: application/json or
application/xml.
Default: application/json |
Content-Type | Required. Data format of the file to post. For example, use
image/jpeg or image/png to post JPEG or PNG
image files exclusively. To allow all image types, specify image/* ;
to allow any file type, specify */* . |
Header | Description |
---|---|
None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body parameters (JSON or XML)
Example: Sample cURL request
Shows how to upload the .jpg file Issue_screenshot.jpg in the /images directory.
CSM Attachment - POST /now/attachment_csm/upload
Uploads a multipart file attachment.
Value | Description |
---|---|
Content-Type | Content-Type of the file, included in the message body for multipart
uploads. Note: You must define the Content-Type within the file portion of the
POST message, not within the form data.
Data type: String |
table_name | Name of the table to which you want to attach the file. This table must be
specified in the glide.rest.attachment_csm_api.allowed_tables
property in the System Properties [sys_properties] table. Data type: String |
table_sys_id | Sys_id of the record on the specified table to which you want to attach the
file. Data type: String |
URL format
Versioned URL: /api/now/{api_version}/attachment_csm/upload
Default URL: /api/now/v1/attachment_csm/upload
Supported request parameters
Name | Description |
---|---|
api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
Name | Description |
---|---|
None |
Name | Description |
---|---|
None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Header | Description |
---|---|
Content-Type | Data format of the request body. Set this value to
multipart/form-data when using the multipart POST method. |
Header | Description |
---|---|
Location | URL of the new attachment in the ServiceNow platform instance. |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.