--- title: "REST Interface" canonical: "https://help.agiloft.com/space/HELP/43715778/REST%20Interface" format: markdown --- Click the link in the Operation column to learn more about a particular operation. | **Operation** | **Supported HTTP Methods** | **REST Endpoint** | **Returns** | | --- | --- | --- | --- | | [Create](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714571) | GET/POST | /ewws/EWCreate | ID of the newly created record | | [Read](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714567) | GET/POST | /ewws/EWRead | Encoded record information | | [Update](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714575) | GET/POST | /ewws/EWUpdate | Encoded record information after update | | [Delete](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714569) | GET/POST/DELETE | /ewws/EWDelete | Does not return anything | | [Select](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714549) | GET/POST | /ewws/EWSelect | A list of record identifiers and a length of that list
Supports limited SQL select functionality. Only available via GET/POST | | [Login](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714204) | GET/POST | /ewws/EWLogin | A session token, expiration time, and authentication scheme | | [Logout](https://wiki.agiloft.com/display/HELP/REST+-+Login#RESTLogin-JWTLogoutOperations) | GET/POST | /ewws/EWLogout | Does not return anything | | [Search](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43717730) | GET/POST | /ewws/EWSearch | Supports saved search and ad hoc queries | | [Attach](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714376) | PUT | /ewws/EWAttach | Adds attachment | | [RemoveAttached](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714589) | GET/POST | /ewws/EWRemoveAttachment | Does not return anything | | [RetrieveAttached](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714587) | GET/POST | /ewws/EWRetrieve | Retrieves attachment | | [Lock](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714340) | GET/PUT/DELETE | /ewws/EWLock | Provides ability to check, lock, and unlock the lock status of a record | | [AttachInfo](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715898) | GET/POST | /ewws/EWAttachInfo | Returns info about the attachments of a record | | [Hotlink](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715003) | POST | /ewws/EWHotlinks | Creates a secure hotlink facility by which Agiloft may be integrated with a third party portal | | [Table](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715609) | GET/POST | /ewws/EWTable | Returns a list of all the tables and fields in the system | | [Async Status](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43712580) | GET/POST | /ewws/EWAsyncStatus | Checks the execution status of an asynchronous call | | [GetChoiceLineId](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714380) | GET | /ewws/GetChoiceLineID | Retrieves the internal ID for a choice value | | [Action Button](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43717142) | POST | /ewws/EWActionButton | Runs an action button from a specified record | | [Saved Search](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714188) | GET/POST | /ewws/EWSavedSearch | Returns details about a saved search defined in a table | | [Upsert](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/763691019) | POST | /ewws/EWUpsert | Creates a new record or updates an existing record | # URL Conventions The following conventions apply to how URLs are constructed for different operations.  KB names and table names are case sensitive. To find the correct styling for your table, go to **Setup > Tables**, select your table, click Edit, and look for the Logical Table Name. Use the same text and format of the Logical Table Name when referencing that particular table. #### REST Use the code block below for REST. However, you should omit `/{id}` when using Create (POST); creating a new record does not require a reference to an existing one. ```javascript /ewws/REST/{kbName}/{table}[/{id}]?$login={login}&password={password}&lang={lang}&... ``` #### GET/POST For the fallback GET/POST interface, use the following: ```javascript /ewws/{operation}?$KB={kbName}&$table={table}&$login={login}&password={password}&lang={lang}&...  ``` The parameters of the POST request can be inserted into the body of the request to conceal the user credentials. #### Name/value pairs The URL string should contain the parameter name/value pairs, as per operation specification: > ℹ️ **Example** > ℹ️ > ℹ️ ```javascript > ℹ️ GET {server name}/ewws/REST/Demo/Company/123?$login=user&$password=123&$lang=en > ℹ️ ``` > ℹ️ > ℹ️ Or > ℹ️ > ℹ️ ```javascript > ℹ️ POST {server name}/ewws/EWRead?$KB=Demo&$table=Company&id=123&$login=user&$password=123&$lang=en > ℹ️ ``` # Return Values Return values come in an encoded form suitable for applying the JavaScript `eval()` operations. Extended characters (like ö) are returned in a UTF-encoded format. Return values can be accessed from local variables. Fields with empty values are returned as nulls. To avoid interfering with variables that may already exist in the client script or document, all table column names in the variables that result from the `eval()` call are prefixed with `EWREST_`. As such, what is returned is escaped using JavaScript rules. The content type of the field is irrelevant for the escaping. ```javascript EWREST_company_name='Agiloft'; EWREST__1794_full_name=' agiloft.com Admin'; EWREST_website_url=' https://www.agiloft.com' EWREST_date_updated=' 21 8 06 15:18:43 PM'; EWREST_id=' 21'; ``` > 📝 You may want to consider using a JSON decorator to receive a JSON formatted stream instead, since JSON has more readily available parsers. Here is its syntax in a REST call: > 📝 > 📝 `https:///ewws/EWRead/.json?$KB=KB&$table=&$login=admin&$password=$lang=en&id=` > 📝 > 📝 In this case the return result would look like: > 📝 > 📝 ```javascript > 📝 {"success":true,"message":"","result":{...,"company_name":"Agiloft","_1794_full_name":"Agiloft System","id":21}}  > 📝 ``` # Delays Each call via the REST interface has a delay inserted after the operation has completed. The delay is set to one second by default and is configurable via the global variable [Web Services Delay (WSDelay)](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43713942). Delays are important because: - An operation on a record may invoke rules and other functions, which need to be allowed enough time and resources to complete. - Client applications could mistakenly overuse web services, resulting in a flood of requests. # Security Use the Login and Logout operations to secure sessions initiated by REST. - **Login**: Use this operation to authenticate KB credentials and return a token, which can then be used by following requests to avoid including login credentials in request URLs. Input the KB login and password as parameters, and the operation returns a token, expiration time, and authentication scheme to the client. The token can then be used in an Authorization request header, prefixed by the authentication scheme, instead of including the login and password parameters in following requests. By default, the Bearer authentication scheme is used, and the token expiration time is 15 minutes. You can adjust the expiration time by creating a token_expires_in global variable and setting the number of minutes, up to 60. - **Logout**: Use this operation to terminate a session created by the Login operation. This terminates the session associated with the token passed in the Authorization header. ### Examples These examples show the process of creating the token, placing it in the request header, and then terminating the token session. With the token in the header, you can use functions like Search without passing in a login and password in the URL. | **Usage** | **Headers** | **Example Text** | **Response** | | --- | --- | --- | --- | | Login request | | POST https://server/ewws/EWLogin? $login=user&$password=passwd& $KB=Demo&$lang=en | HTTP/1.1 200 OK
{"**access_token**":"eyJhbGciOiJIUzI1NiJ9….","refresh _token":"…","expiration_time_unit":"minute","expires _in":5,"**authentication_scheme**":"Bearer "} | | Functional request | Authorization: Bearer | GET https://server/ewws/EWSearch? $KB=Demo&$table=body&$lang=en& field=id&field=text&field=body&query=... | | | Refresh token | Authorization: Bearer | POST https://server/ewws/EWLogin?$KB=Demo&$lang=en&refresh_token=xYZsk... | HTTP/1.1 200 OK {"**access_token**":"jkShbGciOiJIUzI1NiJ9….","refresh _token":"…","expiration_time_unit":"minute","expires _in":5,"**authentication_scheme**":"Bearer "} | | Logout request | Authorization: Bearer | GET https://server/ewws/EWLogout | HTTP/1.1 200 OK | # Data Encoding The following conventions are in place to encode aspects of a typical API call. #### Choice fields Choice fields are encoded directly with their text values as seen in the GUI. ```javascript ...&country=USA&...  ``` > 📝 For ad hoc queries in the [Select](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714549) call, choice values should be addressed via the ID values obtained from [GetChoiceLineId](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714380). #### Multi-choice fields Multi-choice fields are encoded as multiple key/value pairs. ```javascript ... &contactMethod=phone&contactMethod=email&...  ``` #### Date, date-time and time fields Date, date-time and time fields can be encoded with any of 3,275 formats currently supported. The system evaluates the possible formats sequentially and stops when parsing if one of the formats succeeds. Please refer to the following document to see the list of supported date-time formats: [datetime.txt](https://agiloft-public.atlassian.net/wiki/download/attachments/44031080/datetime.txt?version=1&modificationDate=1514667213093&cacheVersion=1&api=v2) #### Elapsed time fields These can be encoded as "days:hours:minutes:seconds" e.g "0:1:35:15"6 #### Linked field relationships If the linked field allows independent values, they can be assigned to the columns in the main table: ```javascript ...&company_name=Agiloft&... ``` To create a link based on the values of imported columns, you must use Query By Example, expressed with a colon ':' qualifier. Example values have to be provided for one or more of the imported columns in either of the following ways: ``` ...&company_name=:Agiloft&... ```  Or ``` ...&company_name=Company:Agiloft&... ``` The name of the original table that contained the field is required if the link type is "[single field from multiple tables](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715017)", but may be omitted in the case of a single, original donor table. If the value contains the colon ':' symbol or the question mark '?' symbols, they have to be escaped with backward-slash "\" in the following way: ```javascript ...&company_url=Company:http\://www.example.com&... ``` For more complex queries, possibly including sub-selects, aggregative functions and columns from the donor table that are not imported into the target, you can use a SQL query, expressed with a question mark '?' qualifier. The "where" clause follows the qualifier for the query that will be run against the donor table. The columns in the query have to be referred with their database names rather then logical ones. > ℹ️ **Example** > ℹ️ > ℹ️ To look for Employee records where the Company currency is EUR, and not in the linked set, use a search similar to the following example: > ℹ️ > ℹ️ ``` > ℹ️ https://localhost:8080/ewws/EWSearch?$login=admin&$password=qwerty&$lang=en > ℹ️ &$table=contacts.employees&$KB=Demo&query=_1576_company_name0=Company?currency~='EUR' > ℹ️ ``` #### Multiple values for the linked field These are encoded as multiple key/value pairs: ```javascript ...&company_name=Company:Agiloft& company_name=Company:SaaSWizard&...  ``` #### File and image fields An example of this field is an Attached File field. The REST interface accepts files in POST requests when used with **enctype="multipart/form-data"** encoding. The name of the form field should match the name of the file or image field. Additionally a field *fieldName$overwrite* can be specified with any value to instruct the REST interface to override the current data in the file or image field, rather than add. Application clients can use [REST - Attach](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714376) operation instead with PUT HTTP method. ### Decorators REST calls allow use of three decorators: - **Asynchronous decorator:** These can be applied to EWCreate, EWUpdate and EWDelete calls to do "fire-and-forget" type of call. They should used if the results normally returned by an operation are not important to the caller e.g. a scenario when a lot of records have to be created in the backend. **Use** - **Redirect decorator**: These can be applied to all calls to have a HTTP redirect issued depending on the success of the operation and are useful when integrating with web sites. Please note the page to which redirect is performed will NOT receive any return data. These calls require two parameters to be specified: *$exiturl* and *$errorurl* - for redirecting in case of successful operation and in case of error respectively. Both parameters should be absolute URLs and URL encoded if necessary. **Use** - **JSON decorator**: produces a JSON formatted stream. If you apply JSON formatting, you can optionally include the parameter err_code_resp=1 to receive specific response codes, rather than the default behavior of receiving code 200 in response. **Use** Please note that decorators can be chained. In the case of chaining they are applied from left to right. ##### **Use** ``` /ewws/redirect/EWCreate/.async?...&$exiturl=http%3A%2F%2Fwww.google.com&$errorurl=http%3A%2F%2Fwww.google.com%2F404 /ewws/async/EWCreate/.redirect?...&$exiturl=http%3A%2F%2Fwww.google.com&$errorurl=http%3A%2F%2Fwww.google.com%2F404 /ewws/redirect/async/EWCreate?...&$exiturl=http%3A%2F%2Fwww.google.com&$errorurl=http%3A%2F%2Fwww.google.com%2F404 /ewws/async/redirect/EWCreate?...&$exiturl=http%3A%2F%2Fwww.google.com&$errorurl=http%3A%2F%2Fwww.google.com%2F404 ``` # General Error Codes | **Error Scenario** | **Type** | **Error Code** | **Error Description** | | --- | --- | --- | --- | | No permission to access the resource | AUTHORIZATION | 400 | EWWrongDataException → There is no permissions to access this resource | | Both Authentication method provided | AUTHORIZATION | 400 | EWWrongDataException → One has to specify $login and $password parameters or authentication token. | | Token has been expired | AUTHORIZATION | 400 | EWWrongDataException → Token is expired | | Authentication details not provided | AUTHORIZATION | 400 | EWWrongDataException → One has to specify $login, $password parameters or use $genhotlink/$genproject pair to pass all or some of these in encrypted form. The encrypted part MUST include $KB. The credentials ($login/$password) can either be supplied outside encrypted part or within. When supplied within the encrypted part, $password is optional. The encrypted part may contain other parameters, these will override the values supplied in plain text. | | Invalid authorization scheme | AUTHORIZATION | 401 | EWAuthException → Wrong Authorization data | | Token has been blocked | AUTHORIZATION | 401 | EWAuthException → Token is blocked | | User has been blocked | AUTHORIZATION | 401 | EWAuthException → User is blocked | | Login account has been disabled | AUTHORIZATION | 403 | EWPermissionException → Warning: Invalid login attempt. Too many invalid attempts will lock down the account until the password is reset. | | Login account has been locked | AUTHORIZATION | 403 | EWPermissionException → Authentication failed. | | Username and password is invalid | AUTHORIZATION | 403 | EWPermissionException → Invalid login/password combination /****** for knowledgebase | | Token has been revoked or session is no longer active | AUTHORIZATION | 500 | EWUnexpectedException → No active session found for current token | | Invalid KB name passed | VALIDATION | 400 | EWWrongDataException → Unable to identify KB with name | | EWWrongDataException → Cannot find specified knowledgebase: | | Required generic request parameters not passed | VALIDATION | 400 | EWWrongDataException → One has to specify $table, $KB, $lang parameters or use $genhotlink/$genproject pair to pass all or some of these in encrypted form. The encrypted part MUST include $KB. | | Invalid combination of Access token and KB name passed | VALIDATION | 400 | EWWrongDataException → Wrong combination of access token and KB name. No access to data in KB | | Id not provided | VALIDATION | 400 | EWWrongDataException → One has to specify id value. | | Content type is not application/x-www-form-urlencoded | VALIDATION | 400 | WrongDataException → The client is not authorized to request an access token using this method.: unauthorized_client | | KB provided is not found | VALIDATION | 400 | EWWrongDataException → Project has not been found | | Table provided is not found | VALIDATION | 400 | EWWrongDataException → Table has not been found | | Missing field parameter in the request | VALIDATION | 400 | EWWrongDataException → No value for 'field' parameter specified. | | Column not found for attachment | VALIDATION | 400 | EWWrongDataException → Field has not been found in table | | Invalid column type for attachment | VALIDATION | 400 | EWWrongDataException → Field in table is not of SW_BLOB or SW_IMAGE_TYPE domain but | | Attachment doesn’t exist for requested data | VALIDATION | 400 | EWWrongDataException → Blob field in table is empty for key | | Linked field value with invalid prefix | VALIDATION | 400 | EWWrongDataException → Linked Field does not allow extra values | | IP has been blacklisted or not whitelisted | VALIDATION | 403 | EWPermissionException → not allowed, please check logs | | Provided HTTP method is not valid | VALIDATION | 405 | HTTP method is not supported by this URL | | Error while retrieving table metadata | VALIDATION | 500 | EWUnexpectedException → No value for 'fileName' parameter specified. | | Duplicate value is passed in a unique field | VALIDATION | 500 | EWUnexpectedException → Duplicate key error while creating RecordFacade, values: id = '571' !Offending Column Name::id | | String value provided for Long parameter | VALIDATION | 500 | Exception has occurred: For input string: "" | #### Related articles > Macro (contentbylabel)