Intuition APIs V3 — Developer Guide

Applies to: Sprinklr Intuition APIs (/api/v3/intuition)

1. Overview

Sprinklr Intuition APIs run machine-learning predictions and classifications against text or publicly accessible resources. The APIs support single-item and batch requests for text classification, location insights, product insights, intent detection, and visual detection.

A single prediction request is an object containing an engineKey and the input required by that engine. A batch request is an array of the same request objects.

1.1 Supported operations

Operation	Method	Path
Text prediction	`POST`	`/api/v3/intuition/text/predict`
Batch text prediction	`POST`	`/api/v3/intuition/text/batch-predict`
Location Insights prediction	`POST`	`/api/v3/intuition/location-insights/predict`
Batch Location Insights prediction	`POST`	`/api/v3/intuition/location-insights/batch-predict`
Product Insights prediction	`POST`	`/api/v3/intuition/product-insights/predict`
Batch Product Insights prediction	`POST`	`/api/v3/intuition/product-insights/batch-predict`
Intent prediction	`POST`	`/api/v3/intuition/intent/predict`
Batch Intent prediction	`POST`	`/api/v3/intuition/intent/batch-predict`
Visual prediction	`POST`	`/api/v3/intuition/visual/predict`
Batch Visual prediction	`POST`	`/api/v3/intuition/visual/batch-predict`

1.2 Single and batch request model

Single endpoints accept one request object. Batch endpoints accept an array of request objects. Each request identifies the model or task through engineKey and supplies text, resourceURL, or other engine-specific input.

2. Base URL

All documented endpoints use the following base URL:

https://api3.sprinklr.com/api/v3

The Intuition resource is:

https://api3.sprinklr.com/api/v3/intuition

3. Authentication and common headers

Include a valid API V3 bearer token. The selected engineKey must identify an available Intuition engine.

Header	Value	Description	Required on
`Authorization`	`Bearer <accessToken>`	Authenticates the caller.	All requests
`Content-Type`	`application/json`	Indicates a JSON request body.	All documented `POST` requests
`Accept`	`application/json`	Requests a JSON response.	Recommended

Do not publish, commit, or log real access tokens.

4. Common request model

4.1 Single-request fields

Parameter	Sub-parameter	Type	Required	Description
Root object	`text`	String	No	Input text to classify or analyze. Required for text-based engines.
Root object	`language`	String	No	Language of the input text. Defaults to `en`.
Root object	`engineKey`	String	Yes	Engine key identifying the machine-learning model or task.
Root object	`resourceURL`	String	No	Publicly accessible resource URL. Required for engines that use a URL instead of inline content.
Root object	`details`	Object<String, String>	No	Additional key-value metadata passed to the engine.
`details`	Dynamic key-value pair	String	No	Engine-specific metadata.

4.2 Batch-request fields

Parameter	Sub-parameter	Type	Required	Description
Root	N/A	Array	Yes	Collection of prediction request objects.
`[]`	`text`	String	No	Input text to classify or analyze. Required for text-based engines.
`[]`	`language`	String	No	Language of the input text. Defaults to `en`.
`[]`	`engineKey`	String	Yes	Engine key identifying the machine-learning model or task.
`[]`	`resourceURL`	String	No	Publicly accessible resource URL. Required for URL-based engines.
`[]`	`details`	Object<String, String>	No	Additional key-value metadata passed to the engine.

5. Text Prediction APIs

5.1 Predict text

POST /api/v3/intuition/text/predict

Submits text or another supported resource for machine-learning prediction or classification.

Request body

Uses the common single-request fields.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/text/predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "engineKey": "sentiment-en",
    "text": "I love this product!"
  }'

Example response

HTTP/1.1 204 No Content

The source document records 204 No Content for this operation and provides no response body or response-parameter schema.

5.2 Batch predict text

POST /api/v3/intuition/text/batch-predict

Runs text predictions for multiple request objects in one API call. Each array item follows the Text Predict request model.

Request body

Uses the common batch-request fields.

Example request: batch sentiment prediction

curl --location 'https://api3.sprinklr.com/api/v3/intuition/text/batch-predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    { "engineKey": "sentiment-en", "text": "Great service!" },
    { "engineKey": "sentiment-en", "text": "Terrible experience." }
  ]'

Example request: mixed engine keys

[
  {
    "engineKey": "sentiment-en",
    "text": "Love it",
    "language": "en"
  },
  {
    "engineKey": "topic-classifier",
    "text": "Shipping delay",
    "details": {
      "channel": "twitter"
    }
  }
]

Response parameters

Parameter	Type	Required	Description	Sub-parameters
`data`	Array	Yes	Array of text-prediction result objects.	`data[].input`, `data[].response`
`data[].input`	Object	Yes	Echo of the corresponding request element.	Request-specific fields
`data[].response`	Object	Yes	Text-prediction response.	`classDetails`
`data[].response.classDetails`	Array	No	Detected classification details.	`label`, `confidence`, `additional`
`label`	String	No	Detected category label.	None
`confidence`	Number	No	Prediction confidence between 0 and 1.	None
`additional`	Object<String, String>	No	Engine-specific metadata.	Dynamic key-value pairs

Example response

{
  "data": [
    {
      "input": {
        "engineKey": "sentiment-en",
        "text": "Great service!"
      },
      "response": {
        "classDetails": [
          { "label": "Positive", "confidence": 0.91 }
        ]
      }
    },
    {
      "input": {
        "engineKey": "sentiment-en",
        "text": "Terrible experience."
      },
      "response": {
        "classDetails": [
          { "label": "Negative", "confidence": 0.88 }
        ]
      }
    }
  ]
}

HTTP status codes

Status	Condition	Description
`200`	Success	Returns an array of text-prediction result objects.
`400`	Invalid request	Null body, null array element, validation failure, or invalid `engineKey`.
`500`	Server error	Internal classification or downstream-service failure.

Behavior notes

Each request element is validated independently.
A null element at any array index returns HTTP 400.
Results are correlated with inputs through server-assigned internal IDs.

6. Location Insights APIs

6.1 Predict location insights

POST /api/v3/intuition/location-insights/predict

Analyzes unstructured text and returns detected location categories, subjects, sentiments, and phrase-level details.

Path parameters

None.

Query parameters

None.

Request body

Uses the common single-request fields.

Example request: minimal

curl --location 'https://api3.sprinklr.com/api/v3/intuition/location-insights/predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "engineKey": "location-insights-en",
    "text": "The store in downtown Chicago was amazing."
  }'

Example request: language specified

{
  "engineKey": "location-insights-en",
  "text": "Visited the Paris flagship store.",
  "language": "en"
}

Response parameters

Parameter	Type	Required	Description	Sub-parameters
`data`	Object	Yes	Single location-insight result.	`input`, `response`
`data.input`	Object	Yes	Echo of the request input. The server assigns an internal ID.	`text`, `language`, `engineKey`, `resourceURL`, `details`
`data.response`	Array<Object>	No	Detected location-insight phrase details.	`category`, `subject`, `sentiment`, `additional`
`category`	Object	No	Detected location-category phrase.	`name`, `start`, `end`, `phrase`, `confidence`
`subject`	Object	No	Detected location-subject phrase.	`name`, `start`, `end`, `phrase`, `confidence`
`sentiment`	Object	No	Detected sentiment phrase.	`name`, `start`, `end`, `phrase`, `confidence`
`additional`	Object<String, String>	No	Engine-specific metadata.	Dynamic key-value pairs
`name`	String	No	Category name for the detected phrase.	None
`start`	Integer	No	Starting character position.	None
`end`	Integer	No	Ending character position.	None
`phrase`	String	No	Detected phrase text.	None
`confidence`	Number	No	Prediction confidence between 0 and 1.	None

Example response

{
  "data": {
    "input": {
      "engineKey": "location-insights-en",
      "text": "The store in downtown Chicago was amazing.",
      "language": "en"
    },
    "response": [
      {
        "category": {
          "name": "Location Experience",
          "start": 4,
          "end": 29,
          "phrase": "store in downtown Chicago",
          "confidence": 0.91
        },
        "sentiment": {
          "name": "Positive",
          "start": 34,
          "end": 41,
          "phrase": "amazing",
          "confidence": 0.95
        }
      }
    ]
  }
}

HTTP status codes

Status	Condition	Description
`200`	Success	Returns one location-insight result object.
`400`	Invalid request	Null body, null list element, validation failure, or invalid `engineKey`.
`500`	Server error	Internal classification or downstream-service failure.

6.2 Batch predict location insights

POST /api/v3/intuition/location-insights/batch-predict

Runs Location Insights predictions for multiple request objects in one API call.

Request body

Uses the common batch-request fields.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/location-insights/batch-predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    { "engineKey": "location-insights-en", "text": "Great store in NYC." },
    { "engineKey": "location-insights-en", "text": "Poor service in London." }
  ]'

Response parameters

The batch response uses the same phrase-detail objects as the single response, but data is an array.

Parameter	Type	Required	Description	Sub-parameters
`data`	Array	Yes	Array of location-insight result objects.	`data[].input`, `data[].response`
`data[].input`	Object	Yes	Echo of the request input.	Common request fields
`data[].response`	Array<Object>	No	Detected phrase details.	`category`, `subject`, `sentiment`, `additional`
`category`	Object	No	Location-category phrase.	`name`, `start`, `end`, `phrase`, `confidence`
`subject`	Object	No	Location-subject phrase.	`name`, `start`, `end`, `phrase`, `confidence`
`sentiment`	Object	No	Sentiment phrase.	`name`, `start`, `end`, `phrase`, `confidence`

Example response

{
  "data": [
    {
      "input": {
        "engineKey": "location-insights-en",
        "text": "Great store in NYC."
      },
      "response": [
        {
          "category": {
            "name": "Location Experience",
            "phrase": "store in NYC"
          },
          "sentiment": {
            "name": "Positive",
            "phrase": "Great"
          }
        }
      ]
    },
    {
      "input": {
        "engineKey": "location-insights-en",
        "text": "Poor service in London."
      },
      "response": [
        {
          "subject": {
            "name": "Service",
            "phrase": "service"
          },
          "sentiment": {
            "name": "Negative",
            "phrase": "Poor"
          }
        }
      ]
    }
  ]
}

HTTP status codes

Status	Condition	Description
`200`	Success	Returns an array of location-insight results.
`400`	Invalid request	Null body, null list element, validation failure, or invalid `engineKey`.
`500`	Server error	Internal classification or downstream-service failure.

7. Product Insights APIs

7.1 Predict product insights

POST /api/v3/intuition/product-insights/predict

Identifies product categories, brands, sentiment, and phrase-level insight details, including hierarchical product categorization.

Request body

Uses the common single-request fields.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/product-insights/predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "engineKey": "product-insights-en",
    "text": "The new iPhone camera is incredible but battery life is poor."
  }'

Response parameters

Parameter	Type	Required	Description	Sub-parameters
`data`	Object	Yes	Single product-insight result.	`input`, `response`
`input`	Object	Yes	Echo of the request input.	Common request fields
`response`	Array	Yes	Prediction output.	`category`, `brand`, `sentiment`, `additional`
`category`	Object	No	Product-category phrase with hierarchy.	`name`, `start`, `end`, `phrase`, `confidence`, `l1`, `l2`, `l3`
`brand`	Object	No	Detected brand phrase.	`name`, `start`, `end`, `phrase`, `confidence`
`sentiment`	Object	No	Detected sentiment phrase.	`name`, `start`, `end`, `phrase`, `confidence`
`additional`	Object	No	Engine-specific metadata.	Dynamic key-value pairs
`l1`	String	No	Level-1 product category.	None
`l2`	String	No	Level-2 product category.	None
`l3`	String	No	Level-3 product category.	None

Example response

{
  "data": {
    "input": {
      "engineKey": "product-insights-en"
    },
    "response": [
      {
        "category": {
          "name": "Smartphones",
          "l1": "Electronics"
        },
        "brand": {
          "name": "Apple"
        },
        "sentiment": {
          "name": "Mixed"
        }
      }
    ]
  }
}

HTTP status codes

Status	Condition	Description
`200`	Success	Returns a product-insight result object.
`400`	Invalid request	Null request body or invalid `engineKey`.
`500`	Server error	Internal classification or downstream-service failure.

7.2 Batch predict product insights

POST /api/v3/intuition/product-insights/batch-predict

Runs Product Insights predictions for multiple text inputs in one API call.

Request body

Uses the common batch-request fields.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/product-insights/batch-predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    { "engineKey": "product-insights-en", "text": "Love the Nike shoes." },
    { "engineKey": "product-insights-en", "text": "Samsung TV has great picture." }
  ]'

Example response

HTTP/1.1 200 Success

The source document specifies a successful HTTP 200 response but does not provide the response body or a response-parameter table for this operation.

8. Intent Prediction APIs

8.1 Predict intent

POST /api/v3/intuition/intent/predict

Identifies user intent, categorization details, and phrase-level insights using the selected intent-classification engine.

Request body

Uses the common single-request fields.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/intent/predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "engineKey": "intent-classifier",
    "text": "I want to cancel my subscription"
  }'

Example response

HTTP/1.1 200 Success

The source document specifies a successful HTTP 200 response but does not provide the response body or a response-parameter table for this operation.

8.2 Batch predict intent

POST /api/v3/intuition/intent/batch-predict

Runs intent predictions for multiple text inputs in one request.

Request body

Uses the common batch-request fields.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/intent/batch-predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    {
      "engineKey": "intent-classifier",
      "text": "I want to cancel my subscription"
    },
    {
      "engineKey": "intent-classifier",
      "text": "How do I update my billing information?"
    }
  ]'

Example response

HTTP/1.1 200 Success

The source document specifies a successful HTTP 200 response but does not provide the response body or a response-parameter table for this operation.

9. Visual Prediction APIs

9.1 Predict visual content

POST /api/v3/intuition/visual/predict

Runs image-based prediction using a public resource URL and an engine key. The operation is described as returning detected visual entities, confidence scores, and bounding-box information.

Request body

Uses the common single-request fields. resourceURL is required for image or visual engines that operate on a resource URL.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/visual/predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "engineKey": "logo-detection",
    "resourceURL": "https://example.com/banner.jpg",
    "language": "en"
  }'

Example response

HTTP/1.1 200 Success

The source document specifies a successful HTTP 200 response but does not provide the response body or response-parameter table.

9.2 Batch predict visual content

POST /api/v3/intuition/visual/batch-predict

Runs visual predictions for multiple image inputs in one request.

Request body

Uses the common batch-request fields. resourceURL is required for visual engines that operate on images.

Example request

curl --location 'https://api3.sprinklr.com/api/v3/intuition/visual/batch-predict' \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    {
      "engineKey": "logo-detection",
      "resourceURL": "https://example.com/img1.jpg"
    },
    {
      "engineKey": "logo-detection",
      "resourceURL": "https://example.com/img2.jpg"
    }
  ]'

Example response

HTTP/1.1 200 Success

The source document specifies a successful HTTP 200 response but does not provide the response body or response-parameter table.

10. Response formats

10.1 Single-result envelope

The documented Location Insights and Product Insights single operations use a data object containing the echoed input and prediction response.

{
  "data": {
    "input": {},
    "response": []
  }
}

10.2 Batch-result envelope

The documented Text and Location Insights batch operations return a data array.

{
  "data": [
    {
      "input": {},
      "response": {}
    }
  ]
}

The exact shape of response is engine-specific. Text prediction uses classDetails; Location Insights uses phrase-detail objects; Product Insights uses category, brand, and sentiment objects.

11. HTTP status codes

The following codes are explicitly documented for the APIs that include status-code tables.

HTTP code	Scenario	Description
`200 OK`	Success	Returns the documented prediction result or result array.
`204 No Content`	Text Predict source example	The request succeeds without a response body.
`400 Bad Request`	Invalid request	Null body or list element, validation failure, or invalid `engineKey`, depending on the operation.
`500 Internal Server Error`	Server error	Internal classification or downstream-service failure.

The source does not provide an error payload schema. Do not add one without confirming it against the service contract or OpenAPI specification.

12. Behavior and implementation notes

Use a supported engineKey for the prediction task.
Supply text for text-based engines.
Supply a publicly accessible resourceURL for URL-based visual engines.
Batch payloads must be arrays of request objects.
For Batch Text Predict, each array element is validated independently, and a null element returns HTTP 400.
Batch Text Predict results are correlated with inputs through server-assigned internal IDs.
confidence values documented in Text and Location Insights responses range from 0 to 1.
Character offsets are represented by start and end in phrase-level results.
Product categories may include the l1, l2, and l3 hierarchy fields.

13. Use cases

13.1 Classify sentiment or topics in text

Use Text Predict for one input or Batch Text Predict for multiple inputs. Select an engine such as sentiment-en or another available text-classification engine.

13.2 Extract location-level insights

Use Location Insights to identify location-related categories, subjects, sentiments, phrases, positions, and confidence values.

13.3 Extract product and brand insights

Use Product Insights to identify product categories, category hierarchy, brands, and sentiment from customer text.

13.4 Detect customer intent

Use Intent Predict to classify the purpose of a customer statement, such as cancellation or billing-information requests.

13.5 Detect visual entities

Use Visual Predict with a publicly accessible image URL and an available visual engine such as logo-detection.

13.6 Process multiple inputs

Use the corresponding batch endpoint when you need to submit multiple text or image inputs in one request.

14. Publishing checklist

Confirm that every engineKey used in an example is available in the target environment.
Confirm the 204 No Content behavior documented for Text Predict against the service contract.
Add missing response bodies and response schemas for Product Insights Batch, Intent, and Visual APIs only after validating them against the OpenAPI specification or an observed production-safe response.
Confirm whether the production base URL requires an environment segment for the target deployment.
Keep access tokens and other credentials out of published examples.
Replace example resource URLs with safe, publicly accessible samples where needed.
Validate all cURL examples before publication.

All payloads in this guide are illustrative. Credentials and identifiers are placeholders and must not be committed or logged.