# 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"
}
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.coherent.global/spark-apis/transforms-api/transform-documents-apis.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.