# Intuition APIs V3 — Developer Guide

- **Applies to:** Sprinklr Intuition APIs (`/api/v3/intuition`)
- **V2 API reference**: [Intuition | Sprinklr Developer Portal](https://legacy-dev.sprinklr.com/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:

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

The Intuition resource is:

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

Replace {env} with your assigned environment identifier (prod0, prod2, prod11, and so on — see APIs | Sprinklr Developer Portal for the environment list).

## 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 |


## 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

```http
POST /api/v3/intuition/text/predict
```

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

#### Request body

#### Example request

```bash
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
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

```http
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](#42-batch-request-fields).

#### Example request: batch sentiment prediction

```bash
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

```json
[
  {
    "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

```json
{
  "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. |


## 6. Location Insights APIs

### 6.1 Predict location insights

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

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

#### Request body

Uses the [common single-request fields](#41-single-request-fields).

#### Example request: minimal

```bash
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

```json
{
  "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

```json
{
  "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

```http
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](#42-batch-request-fields).

#### Example request

```bash
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

```json
{
  "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

```http
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](#41-single-request-fields).

#### Example request

```bash
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

```json
{
  "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

```http
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](#42-batch-request-fields).

#### Example request

```bash
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
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

```http
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](#41-single-request-fields).

#### Example request

```bash
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
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

```http
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](#42-batch-request-fields).

#### Example request

```bash
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
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

```http
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](#41-single-request-fields). `resourceURL` is required for image or visual engines that operate on a resource URL.

#### Example request

```bash
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
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

```http
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](#42-batch-request-fields). `resourceURL` is required for visual engines that operate on images.

#### Example request

```bash
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
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.

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

### 10.2 Batch-result envelope

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

```json
{
  "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.


## 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.