> ## Documentation Index > Fetch the complete documentation index at: https://algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # Try a transformation before creating it > Try a transformation before creating it. **Required ACL:** `addObject`, `deleteIndex`, `editSettings` ## OpenAPI ````yaml specs/ingestion.yml post /1/transformations/try openapi: 3.1.0 info: title: Ingestion API summary: >- The Ingestion API lets you connect third-party services and platforms with Algolia and schedule tasks to ingest your data description: > The Ingestion API powers the no-code [data connectors](https://dashboard.algolia.com/connectors). ## Base URLs Base URLs for the Ingestion API: - `https://data.us.algolia.com` - `https://data.eu.algolia.com` Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics). **All requests must use HTTPS.** ## Authentication Add these headers to authenticate requests: - `x-algolia-application-id`. Your Algolia application ID. - `x-algolia-api-key`. An API key with the necessary permissions to make the request. The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys). ## Request format Request bodies must be JSON objects. ## Response status and errors Response bodies are JSON objects. Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses. Error responses have a `message` property with more information. ## Version The current version of the Ingestion API is version 1, indicated by the `/1/` in each endpoint's URL. version: 1.0.0 servers: - url: https://data.{region}.algolia.com variables: region: description: The region where your Algolia application is hosted. enum: - eu - us default: us security: - appId: [] apiKey: [] tags: - name: authentications x-displayName: Authentications description: >- Authentication resources describe how to connect to a source or destination. - name: destinations x-displayName: Destinations description: > Destinations are Algolia products or features where your data should be used, such as a search index or events. Algolia destinations require authentication with the `algolia` type. You can reference authentications by their ID when creating destinations. - name: observability x-displayName: Observability description: >- Check the status and details of your task runs. A run is one instance of a configured task. - name: sources x-displayName: Sources description: > Sources are third-party platforms or services from where you want to ingest your data. Sources may require authentication. To interact with such sources, you can reference an authentication resource by its ID. - name: tasks x-displayName: Tasks description: > Tasks contain information how your data should be read from a source and stored in a destination. Tasks have _triggers_ which determine when the task should run. - name: transformations x-displayName: Transformations description: > Transformations let you transform a record before it gets indexed in Algolia. paths: /1/transformations/try: post: tags: - transformations summary: Try a transformation before creating it description: Try a transformation before creating it. operationId: tryTransformation requestBody: content: application/json: schema: $ref: '#/components/schemas/TransformationTry' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TransformationTryResponse' '400': $ref: '#/components/responses/BadRequest' x-codeSamples: - lang: csharp label: C# source: |- // Initialize the client var client = new IngestionClient( new IngestionConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION") ); // Call the API var response = await client.TryTransformationAsync( new TransformationTry { Type = Enum.Parse("Code"), Input = new TransformationInput(new TransformationCode { Code = "foo" }), SampleRecord = new Dictionary { { "bar", "baz" } }, } ); // print the response Console.WriteLine(response); - lang: dart label: Dart source: |- // Initialize the client final client = IngestionClient( appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY', region: 'ALGOLIA_APPLICATION_REGION'); // Call the API final response = await client.tryTransformation( transformationTry: TransformationTry( type: TransformationType.fromJson("code"), input: TransformationCode( code: "foo", ), sampleRecord: { 'bar': "baz", }, ), ); // print the response print(response); - lang: go label: Go source: >- // Initialize the client with your application region, eg. ingestion.ALGOLIA_APPLICATION_REGION client, err := ingestion.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", ingestion.US) if err != nil { // The client can fail to initialize if you pass an invalid parameter. panic(err) } // Call the API response, err := client.TryTransformation(client.NewApiTryTransformationRequest( ingestion.NewEmptyTransformationTry(). SetType(ingestion.TransformationType("code")). SetInput(ingestion.TransformationCodeAsTransformationInput( ingestion.NewEmptyTransformationCode().SetCode("foo"))). SetSampleRecord(map[string]any{"bar": "baz"}), )) if err != nil { // handle the eventual error panic(err) } // print the response print(response) - lang: java label: Java source: >- // Initialize the client IngestionClient client = new IngestionClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION"); // Call the API TransformationTryResponse response = client.tryTransformation( new TransformationTry() .setType(TransformationType.CODE) .setInput(new TransformationCode().setCode("foo")) .setSampleRecord( new HashMap() { { put("bar", "baz"); } } ) ); // print the response System.out.println(response); - lang: javascript label: JavaScript source: >- // Initialize the client // Replace 'us' with your Algolia Application Region const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY').initIngestion({ region: 'us' }); // Call the API const response = await client.tryTransformation({ type: 'code', input: { code: 'foo' }, sampleRecord: { bar: 'baz' }, }); // print the response console.log(response); - lang: kotlin label: Kotlin source: |- // Initialize the client val client = IngestionClient( appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY", region = "ALGOLIA_APPLICATION_REGION", ) // Call the API var response = client.tryTransformation( transformationTry = TransformationTry( type = TransformationType.entries.first { it.value == "code" }, input = TransformationCode(code = "foo"), sampleRecord = buildJsonObject { put("bar", JsonPrimitive("baz")) }, ) ) // print the response println(response) - lang: php label: PHP source: >- // Initialize the client $client = IngestionClient::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY', 'ALGOLIA_APPLICATION_REGION'); // Call the API $response = $client->tryTransformation( ['type' => 'code', 'input' => ['code' => 'foo', ], 'sampleRecord' => ['bar' => 'baz', ], ], ); // print the response var_dump($response); - lang: python label: Python source: >- # Initialize the client # In an asynchronous context, you can use IngestionClient instead, which exposes the exact same methods. client = IngestionClientSync( "ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION" ) # Call the API response = client.try_transformation( transformation_try={ "type": "code", "input": { "code": "foo", }, "sampleRecord": { "bar": "baz", }, }, ) # print the response print(response) - lang: ruby label: Ruby source: >- # Initialize the client client = Algolia::IngestionClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION") # Call the API response = client.try_transformation( Algolia::Ingestion::TransformationTry.new( type: "code", input: Algolia::Ingestion::TransformationCode.new(code: "foo"), sample_record: {bar: "baz"} ) ) # print the response puts(response) - lang: scala label: Scala source: |- // Initialize the client val client = IngestionClient( appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY", region = "ALGOLIA_APPLICATION_REGION" ) // Call the API val response = Await.result( client.tryTransformation( transformationTry = TransformationTry( `type` = Some(TransformationType.withName("code")), input = Some( TransformationCode( code = "foo" ) ), sampleRecord = JObject(List(JField("bar", JString("baz")))) ) ), Duration(100, "sec") ) // print the response println(response) - lang: swift label: Swift source: >- // Initialize the client let client = try IngestionClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY", region: .us) // Call the API let response = try await client.tryTransformation(transformationTry: TransformationTry( type: TransformationType.code, input: TransformationInput.transformationCode(TransformationCode(code: "foo")), sampleRecord: ["bar": "baz"] )) // print the response print(response) - lang: cURL label: curl source: |- curl --request POST \ --url https://data.us.algolia.com/1/transformations/try \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-algolia-api-key: ALGOLIA_API_KEY' \ --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \ --data ' { "code": "lorem", "type": "code", "input": { "code": "lorem" }, "sampleRecord": {}, "authentications": [ { "type": "googleServiceAccount", "name": "lorem", "platform": "bigcommerce", "input": { "clientEmail": "service-account-name@project-id.iam.gserviceaccount.com", "privateKey": "lorem" } } ] } ' components: schemas: TransformationTry: type: object additionalProperties: false properties: sampleRecord: description: The record to apply the given code to. type: object authentications: type: array items: $ref: '#/components/schemas/AuthenticationCreate' code: $ref: '#/components/schemas/Code' input: $ref: '#/components/schemas/TransformationInput' type: $ref: '#/components/schemas/TransformationType' required: - sampleRecord TransformationTryResponse: type: object additionalProperties: false properties: payloads: type: array description: >- The array of stringified records returned by the transformation service. items: type: string error: title: transformationError type: object description: The error if the transformation failed. properties: code: description: The error status code. type: integer message: description: A descriptive message explaining the failure. type: string required: - payloads AuthenticationCreate: type: object description: Request body for creating a new authentication resource. additionalProperties: false properties: input: $ref: '#/components/schemas/AuthInput' name: $ref: '#/components/schemas/name' type: $ref: '#/components/schemas/AuthenticationType' platform: $ref: '#/components/schemas/Platform' required: - type - name - input Code: type: string deprecated: true description: >- It is deprecated. Use the `input` field with proper `type` instead to specify the transformation code. TransformationInput: description: >- The input for the transformation, which can be either code or a no-code configuration. oneOf: - $ref: '#/components/schemas/TransformationCode' - $ref: '#/components/schemas/TransformationNoCode' TransformationType: type: string description: The type of transformation, which can be either 'code' or 'noCode'. enum: - code - noCode ErrorBase: description: Error. type: object x-keep-model: true additionalProperties: true properties: message: type: string example: Invalid Application-Id or API-Key AuthInput: oneOf: - $ref: '#/components/schemas/AuthGoogleServiceAccount' - $ref: '#/components/schemas/AuthBasic' - $ref: '#/components/schemas/AuthAPIKey' - $ref: '#/components/schemas/AuthOAuth' - $ref: '#/components/schemas/AuthAlgolia' - $ref: '#/components/schemas/AuthAlgoliaInsights' - $ref: '#/components/schemas/AuthSecrets' name: type: string description: Descriptive name for the resource. AuthenticationType: type: string description: >- Type of authentication. This determines the type of credentials required in the `input` object. enum: - googleServiceAccount - basic - apiKey - oauth - algolia - algoliaInsights - secrets Platform: default: null oneOf: - type: string description: | Name of an ecommerce platform with which to authenticate. This determines which authentication type you can select. enum: - bigcommerce - commercetools - shopify - type: 'null' TransformationCode: title: Code type: object additionalProperties: false description: >- Input for a transformation that contains the source code of the transformation. properties: code: type: string description: The source code of the transformation. required: - code TransformationNoCode: title: No-code type: object additionalProperties: false description: Input for a no-code transformation that contains a series of steps. properties: steps: type: array items: $ref: '#/components/schemas/TransformationNoCodeStep' required: - steps AuthGoogleServiceAccount: title: Google type: object description: >- Credentials for authenticating with a Google service account, such as BigQuery. additionalProperties: false properties: clientEmail: type: string description: Email address of the Google service account. example: service-account-name@project-id.iam.gserviceaccount.com privateKey: type: string description: >- Private key of the Google service account. This field is `null` in the API response. required: - clientEmail - privateKey x-discriminator-fields: - clientEmail - privateKey AuthBasic: title: Basic type: object description: Credentials for authenticating with user name and password. additionalProperties: false properties: password: type: string description: Password. This field is `null` in the API response. username: type: string description: Username. required: - username - password x-discriminator-fields: - username - password AuthAPIKey: title: API key type: object description: Credentials for authenticating with an API key. additionalProperties: false properties: key: type: string description: API key. This field is `null` in the API response. required: - key x-discriminator-fields: - key AuthOAuth: title: OAuth 2.0 type: object description: Credentials for authenticating with OAuth 2.0. additionalProperties: false properties: url: type: string description: URL for the OAuth endpoint. client_id: type: string description: Client ID. client_secret: type: string description: Client secret. This field is `null` in the API response. code: type: string description: > Authorization code. Used during an `authorization_code` grant type flow, to request an access_token when creating/updating the authentication. This field is not returned in the API response. scope: type: string default: '' description: OAuth scope. required: - url x-discriminator-fields: - url - client_id - client_secret - code AuthAlgolia: title: Algolia type: object additionalProperties: false description: Credentials for authenticating with Algolia. properties: apiKey: type: string description: > Algolia API key with the ACL: `addObject`, `deleteObject`, `settings`, `editSettings`, `listIndexes`, `deleteIndex`. This field is `null` in the API response. appID: type: string description: Algolia application ID. required: - appID - apiKey AuthAlgoliaInsights: title: Algolia Insights type: object additionalProperties: false description: Credentials for authenticating with the Algolia Insights API. properties: apiKey: type: string description: | Algolia API key with the ACL: `search`. This field is `null` in the API response. appID: type: string description: Algolia application ID. required: - appID - apiKey AuthSecrets: title: Key:value type: object description: A key:value authentication for your transformations. additionalProperties: type: string TransformationNoCodeStep: type: object description: A step in a no-code transformation. responses: BadRequest: description: Bad request or request arguments. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' securitySchemes: appId: type: apiKey in: header name: x-algolia-application-id description: Your Algolia application ID. apiKey: type: apiKey in: header name: x-algolia-api-key description: > Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference. ````