> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/spark-apis/transforms-api/transform-documents-apis.md).
# Transform documents APIs
{% hint style="warning" %}
This feature is only enabled on certain environments and tenants. Please contact [Support](/support/support.md) for more information about this feature.
{% endhint %}
## Authorization
* `Bearer {token}` accessible from [Authorization - Bearer token](/spark-apis/authorization-bearer-token.md) or systematically via [Broken mention](broken://pages/Dx1VW4Wsqbw72hKR5spG).
* The request headers should include a key for `Authorization` with the value `Bearer {token}`.
## Upload transform document file
Returns: `transform` object.
{% code overflow="wrap" %}
```shellscript
POST /{tenant}/api/v4/transforms/{transform_folder}
```
{% endcode %}
Add a new transform document to the specified folder based upon the transform filename. The document will be checked against the [#validate-transform](#validate-transform "mention") endpoint. If the transform already exists a new version of the transform will be created.
### Path parameters
### Request body
`Content-Type: multipart/form-data`
| Key | Value |
| ------ | ----------------------------------------------------------------- |
| `file` | Transform document. The filename must end with `_transform.json`. |
### Sample request
```sh
curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/myfolder' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/C:/myfolder/mytransform_transform.json"'
```
### Sample response
`HTTP 200 OK` `Content-Type: application/json`
```json
{
"object": "transform",
"response_timestamp": "2024-11-15T03:46:33.5680069Z",
"process_time": 898,
"id": "2cadfd08-058d-41a5-8926-c92a3f548bdd",
"status": "added",
"outputs": {
"name": "mytransform",
"transform_uri": "myfolderg/mytransform"
}
}
```
## Add transform with document content
Returns: `transform` object.
{% code overflow="wrap" %}
```shellscript
POST /{tenant}/api/v4/transforms/{transform_folder}/{transform}
```
{% endcode %}
Add a new transform to the specified folder with the transform name using the content transform document that is included in the request body. The document will be checked against the [#validate-transform](#validate-transform "mention") endpoint. If the transform already exists a new version of the transform will be created.
### Path parameters
### Request body
`Content-Type: application/json`
| Key | Value |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transform_content` | The entire contents of the /pages/jdk9qVK7TzdDNVR1UzHD in a single string.
Ensure the content is properly escaped. Content within transform definitions such as input\_body\_transform or output\_body\_transform may need to be double escaped, e.g. " becoming ".
|
### Sample request
```sh
curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformname' \
--header 'Content-Type: application/json' \
--header 'Authorization: {token}' \
--data '{
"transform_content": "{\"transform_type\": \"JSONtransforms_v2.0.1\", \"target_api_version\": \"v3\", \"input_body_transform\":\"{\\\"add_1\\\":add.a,\\\"add_2\\\":add.b,\\\"multiply_1\\\":multiply.a, \\\"multiply_2\\\":multiply.b}\", \"output_body_transform\":\"{\\\"add\\\":{\\\"result\\\":response_data.outputs.add},\\\"multiply\\\":{\\\"result\\\":response_data.outputs.multiply},\\\"meta\\\":{\\\"id\\\":response_meta.call_id}}\"}"
}'
```
### Sample response
`HTTP 200 OK` `Content-Type: application/json`
```json
{
"object": "transform",
"response_timestamp": "2024-11-15T03:46:33.5680069Z",
"process_time": 898,
"id": "2cadfd08-058d-41a5-8926-c92a3f548bdd",
"status": "added",
"outputs": {
"name": "mytransform",
"transform_uri": "myfolder/mytransform"
}
}
```
## Validate transform
Returns: `transform` object.
{% code overflow="wrap" %}
```shellscript
POST /{tenant}/api/v4/transforms/validation
```
{% endcode %}
This API performs the following validations:
* The transform is valid JSON.
* `transform_type` is present and valid.
* Other checks are specific to the [Transform types](/spark-apis/transforms-api/transform-types.md) being used.
### Path parameters
### Request body
`Content-Type: application/json`
| Key | Value |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transform_content` | /pages/jdk9qVK7TzdDNVR1UzHD in a single string.
Ensure the content is properly escaped. Content within transform definitions such as input\_body\_transform or output\_body\_transform may need to be double escaped, e.g. " becoming ".
|
### Sample request
```sh
curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/validation' \
--header 'Content-Type: application/json' \
--header 'Authorization: {token}' \
--data '{
"transform_content": "{\"transform_type\": \"JSONtransforms_v2.0.1\", \"target_api_version\": \"v3\", \"input_body_transform\":\"{\\\"add_1\\\":add.a,\\\"add_2\\\":add.b,\\\"multiply_1\\\":multiply.a, \\\"multiply_2\\\":multiply.b}\", \"output_body_transform\":\"{\\\"add\\\":{\\\"result\\\":response_data.outputs.add},\\\"multiply\\\":{\\\"result\\\":response_data.outputs.multiply},\\\"meta\\\":{\\\"id\\\":response_meta.call_id}}\"}"
}'
```
### Sample response
`HTTP 200 OK` `Content-Type: application/json`
```json
{
"object": "transform",
"response_timestamp": "2024-11-15T04:20:11.2557602Z",
"process_time": 0,
"id": null,
"status": "complete",
"outputs": {
"isValid": false,
"error": [
{
"code": "TRANSFORM_DEFINITION_ERROR",
"type": "invalid_input",
"message": "'JSONtransforms_v2.0.1' is not a valid transform_type. Valid entries are (JSONtransforms_v1.0.1)."
}
]
}
}
```
## List transforms
Returns: List of transforms.
{% code overflow="wrap" %}
```shellscript
POST /{tenant}/api/v4/transforms/list/{folder}
```
{% endcode %}
### Path parameters
### Request body
`Content-Type: application/json`
| Key | Value |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page` | Page number of the list to get. |
| `pageSize` | Number of records per page. |
| `sort` | String defining the sort order.
Example: -updated
|
| `search` | Array of search filter objects. Search filter objects can include:
field Name of the field to filter.
value Value of the field to filter.
operator Applies to numeric properties.
Example 1: {"field": "name", "name": "myfoldername"
Example 2: {"field": "isstarred", "isstarred", "true"}
|
### Sample request
```sh
curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/list/myfolder' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"page": 1,
"pageSize":15,
"sort": "-updatedAt,-name"
}'
```
### Sample response
`HTTP 200 OK` `Content-Type: application/json`
```sh
{
"count": 2,
"page": 1,
"pageSize": 15,
"result": [
{
"id": "122392a3-0ce1-44d0-869a-33551034d1c3",
"name": "mytransform1",
"transform_type": "JSONtransforms_v1.0.1",
"updatedAt": "2024-11-15T04:12:23.056031Z",
"modifiedBy": "myuser@mycompany.com",
"createdBy": "myuser@mycompany.com",
"createdAt": "2024-11-15T04:12:23.05603Z"
},
{
"id": "a481ec59-fd75-40b0-9e6c-4edbc06dc3bc",
"name": "mytransform2",
"transform_type": "JSONtransforms_v1.0.1",
"updatedAt": "2024-11-15T04:05:13.055016Z",
"modifiedBy": "myuser@mycompany.com",
"createdBy": "myuser@mycompany.com",
"createdAt": "2024-11-15T04:05:13.055015Z"
}
]
}
```
## Get transform document
Returns: `transform` object.
{% code overflow="wrap" %}
```shellscript
GET /{tenant}/api/v4/transforms/{transform_folder}/{transform}
```
{% endcode %}
### Path parameters
### Sample request
```sh
curl --location 'https://excel.myenvironment.coherent.global/coherent/api/v4/transforms/myfolder/mytransform' \
--header 'Authorization: Bearer {token}'
```
### Sample response
`HTTP 200 OK` `Content-Type: application/json`
```json
{
"object": "transform",
"response_timestamp": "2024-11-15T04:29:17.0825837Z",
"process_time": 73,
"id": "212a2adc-dd5a-417d-a623-5a45d5ba2fa7",
"status": "success",
"outputs": {
"transform_document": "{\n \"transform_type\": \"JSONtransforms_v1.0.1\",\n \"target_api_version\": \"v3\",\n \"input_body_transform\": \"{\\r\\n 'add_1':add.a,\\r\\n 'add_2':add.b,\\r\\n 'multiply_1':multiply.a,\\r\\n 'multiply_2':multiply.b\\r\\n}\",\n \"output_body_transform\": \"{\\r\\n 'add':{'result':response_data.outputs.add},\\r\\n 'multiply':{'result':response_data.outputs.multiply},\\r\\n 'meta':{'id':response_meta.call_id}\\r\\n}\"\n}",
"updatedAt": "2024-11-11T05:46:33.46664Z"
}
}
```
## Delete transform
Returns: `transform` object.
{% code overflow="wrap" %}
```shellscript
DELETE /{tenant}/api/v4/transforms/{transform_folder}/{transform}
```
{% endcode %}
### Path parameters
### Sample request
```sh
curl --location --request DELETE 'https://excel.myenvironment.coherent.global/coherent/api/v4/transforms/myfolder/mytransform' \
--header 'Authorization: Bearer {token}'
```
### Sample response
`HTTP 200 OK` `Content-Type: application/json`
```json
{
"object": "transform",
"response_timestamp": "2024-11-15T04:35:50.1175746Z",
"process_time": 130,
"id": null,
"status": "deleted",
"outputs": {
"name": "mytransform",
"transform_uri": "myfolder/mytransform"
}
}
```