HTTP and REST
The REST URL structure follows typical resource-oriented conventions.
To get a list of sheets, use the following:
GET https://api.smartsheet.com/2.0/sheets
This returns a list of Sheet objects, where each sheet has an id attribute.
To get details on the sheet with id 123456, use the following:
GET https://api.smartsheet.com/2.0/sheets/123456
This Id pattern is repeated throughout the API. Columns, rows, cells, comments, attachments, or any other data element have a unique Id.
If you don't want to make raw HTTP calls, Smartsheet also has several Software Development Kits (SDKs) that provide a higher level interface for popular programming languages. For more information, see SDKs and Samples.
HTTP Verbs
Call the API using the following standard HTTP methods:
- GET (to retrieve an object or list multiple objects in a specific category)
- POST (to create)
- PUT (to modify)
- DELETE
HTTP Headers
Unless otherwise specified, all API endpoints expect request body data to be in JSON, and the response body data is returned as JSON.
The following HTTP request headers may be required, depending on the operation and endpoint being invoked:
| Header | Definition | Example |
|---|---|---|
| Authorization | Required for all endpoints, except for POST /token. The access token. | Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789 |
| Content-Type | Required for POST and PUT requests. Defines the structure for the response. | application/json |
| Assume-User | Optional. Allows System Administrators (admins) to impersonate or act on behalf of any user in their plan to make API calls. The email address used to identify the user must be URI-encoded. | jane.doe%40smartsheet.com |
HTTP Status Codes
Smartsheet uses a combination of [](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" target="_blank" rel="noopener noreferrer">HTTP status codes and custom error codes with a descriptive message in JSON-formatted Error objects to give you a more complete picture of what has happened with your request.
| HTTP status code | Meaning | To Retry or Not to Retry? |
|---|---|---|
| 2xx | Request was successful. Example: 200 Success | -- |
| 4xx | A problem with request prevented it from executing successfully. | Never automatically retry the request. If the error code indicates a problem that can be fixed, fix the problem and retry the request. |
| 5xx | The request was properly formatted, but the operation failed on Smartsheet's end. | In some scenarios, requests should be automatically retried using exponential backoff. |
For example, doing a GET on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456 results in an HTTP status code of 404, indicating the resource was not found.
{
"errorCode": 1006,
"message": "Not Found"
}Some errors may contain a detail attribute set to an object with additional error details that may be useful in programmatically handling the error. If so, it is noted in the specific API operation for which the error may occur.
NOTE: Smartsheet has custom error codes to help you troubleshoot issues. See Error Codes.