Like the Smartsheet app, the Smartsheet API allows uploading files to sheets, rows, and comments. You can upload a file by performing either a simple upload or a multipart upload.
A simple upload allows you to add a single file attachment to the specified object. For example, you can perform a simple upload to attach a file to a sheet, attach a file to a row, or attach a file to a comment.
A multipart upload allows you to add a single file attachment to the specified object (that is, attach a file to a sheet, row, or comment), or to create an object and attach a file using a single request. For example, you can perform a multipart upload to add a new comment that contains a single file attachment or to add a new discussion to a sheet that contains a single file attachment.
The max file size for uploads through the API is limited to 30mb.
NOTE: This is a resource-intensive operation. If you encounter an error, see Rate Limiting.
A multipart upload request must include the following HTTP headers:
| Header | Description |
|---|---|
| Content-Length | The length of the request payload. |
| Content-Type | Must be set to multipart/form-data, and include the boundary string that separates the parts in the request payload. |
The request body of a multipart upload request contains one or more parts, each part containing either JSON or a file to upload. The request body must contain at least one part. Each part must start with the boundary string specified in the Content-Type request header, and must contain the following part headers:
| Header | Description |
|---|---|
| Content-Disposition | Contains the following semicolon-delimited items:
|
| Content-Type | The content type of the part: application/json for JSON objects, or the applicable MIME type for file parts |
The last part in the request must be followed by the boundary string, followed by two hyphens.
The documentation for each operation that supports multipart uploads specifies the number and names of parts that are expected for the operation. File parts must have the part name "file", and documentation for operations which allow for JSON object parts specify the required part name for the JSON part.
The following example shows a multipart upload request that creates a comment containing the specified text and file attachment:
POST https://api.smartsheet.com/2.0/sheets/4509093797881732/discussions/2889925487028100/comments
Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Length: 29008
Content-Type: multipart/form-data; boundary=----gU8h01zAAp3LagBr
------gU8h01zAAp3LagBr
Content-Disposition: form-data; name="comment"
Content-Type: application/json
{ "text": "Please review the attached image." }
------gU8h01zAAp3LagBr
Content-Disposition: form-data; name="file"; filename="picture.jpg"
Content-Type: image/jpeg
*< Binary content for file >*
------gU8h01zAAp3LagBr--
NOTE: Most programming languages have libraries that can be used to assemble multipart requests.
To perform this kind of upload, you must set specific headers to tell Smartsheet about the file. The following three headers are required:
| Header | Description |
|---|---|
| Content-Disposition | attachment to tell the API that a file is in the body of the POST request, followed by a semicolon, followed by filename= and the URL-encoded filename in quotes |
| Content-Length | Must be set to the size of the file, in bytes. For example to determine file size using in UNIX:
|
| Content-Type | Can be left blank if it is not known (but must be present); Smartsheet makes its best guess based on the extension of the file. |
The following example request shows a simple upload that adds a file attachment to a sheet:
POST https://api.smartsheet.com/2.0/sheets/4509093797881732/attachments
Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Disposition: attachment; filename="ProgressReport.docx"
Content-Type: application/msword
Content-Length: 5463
*< Binary content for file >*
As shown in this example, the contents of the file is included in the body of the POST request. In most programming languages, this is done by reading the file from an input stream and writing it out to the output stream of the HTTP request.