AimableDocs
DocsAPI Reference

Sensitivity

Sensitivity Analysis with the Aimable Platform API

The sensitivity domain in the Aimable Platform API enables developers to detect potentially sensitive content in text—such as personal information, emotionally charged language, or context that may require special handling. This is particularly useful in applications like customer support automation, content moderation, chatbot interactions, and compliance monitoring. By identifying sensitive text early, systems can route messages to human agents, apply data masking, or trigger additional review workflows.

Key Concepts

  • Sensitivity Score: A quantitative measure (typically between 0 and 1) indicating how sensitive a given text is. Higher scores suggest greater sensitivity.
  • Text Input: Plain text strings submitted for analysis. These can be user messages, support tickets, or any unstructured text.
  • Batch Processing: Analyze multiple texts in a single request to improve efficiency and reduce latency.

Authentication is required for all endpoints using the X-API-Key header. Unauthorized or malformed requests return standard HTTP error codes.

How to Use the Endpoints

1. Analyze a Single Text

Use the /v1/sensitivity endpoint to get a sensitivity score for one piece of text.

Example Request:

curl -X POST "https://api.aimable.com/api-proxy/v1/sensitivity" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I think I shared my credit card number by mistake in the last message."
  }'

Sample Response (200 OK):

{
  "score": 0.96,
  "text": "I think I shared my credit card number by mistake in the last message.",
  "timestamp": "2024-04-05T12:34:56Z"
}

This high score indicates strongly sensitive content—likely due to mention of a credit card—triggering potential data protection actions.

2. Analyze Multiple Texts in Batch

For higher throughput, use /v1/sensitivity/batch to analyze up to hundreds of texts at once.

Example Request:

curl -X POST "https://api.aimable.com/api-proxy/v1/sensitivity/batch" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "My phone number is 555-1234.",
      "Just checking in—how was your weekend?",
      "I feel really frustrated with this service."
    ]
  }'

Sample Response (200 OK):

{
  "results": [
    {
      "text": "My phone number is 555-1234.",
      "score": 0.88
    },
    {
      "text": "Just checking in—how was your weekend?",
      "score": 0.12
    },
    {
      "text": "I feel really frustrated with this service.",
      "score": 0.75
    }
  ],
  "processed_at": "2024-04-05T12:37:22Z"
}

Batching helps efficiently screen large volumes of user input, such as in daily log analysis or social media monitoring.

Common Workflows

Workflow: Real-Time Chat Moderation

  1. User sends a message in a support chat.
  2. Frontend or backend sends the message to /v1/sensitivity immediately. 
    { "text": "This is the worst product ever." }
  3. Receive sensitivity score:
    • If score > 0.7, flag for agent review or escalate.
    • If score < 0.3, allow automated response.
  4. Take action based on result—notify a human agent, log the event, or proceed normally.

Workflow: Daily Content Audit

  1. Collect 1,000 user-submitted comments from your database.
  2. Split into batches of 100 and send each to /v1/sensitivity/batch.
  3. Aggregate results to identify:
    • High-sensitivity outliers
    • Trends over time
    • Topics needing policy updates

Authentication & Error Handling

All requests require authentication via the X-API-Key header. Replace your_api_key_here with your actual key.

Common Errors

| Status | Meaning | |-------|--------| | 401 Unauthorized | Missing or invalid X-API-Key. | | 403 Forbidden | The key exists but lacks permissions for this action. | | 422 Unprocessable Entity | Invalid input, such as missing text or non-array texts. The detail field explains what went wrong. |

Example 422 Response:

{
  "detail": [
    {
      "loc": ["body", "text"],
      "msg": "Field required",
      "type": "value_error.missing",
      "input": {}
    }
  ]
}

Always validate your JSON structure before sending.

By integrating the sensitivity endpoints, you can proactively manage risk, enhance user safety, and maintain compliance—all with minimal latency and simple integration.

Related Endpoints