canonical: https://jentic.com/apis/amazonaws.com/aws-comprehend

# AWS Amazon Comprehend

Jentic publishes the only available OpenAPI specification for Amazon Comprehend, keeping it validated and agent-ready. Amazon Comprehend is a managed natural language processing service that extracts insights from unstructured text. It detects entities, key phrases, sentiment, targeted sentiment, dominant language, syntax, and personally identifiable information, and supports custom classification and entity recognition models trained on your data. Both real-time analysis and large-scale asynchronous batch jobs are supported, along with topic modeling, document classification, and PII redaction.

## For AI agents

Run NLP on text and documents - detect entities, sentiment, language, PII, and key phrases, plus train and run custom classifiers and entity recognizers.

## Scope

Does not handle OCR, machine translation, speech transcription, or general LLM chat - use Amazon Comprehend for NLP analysis of already-extracted text only.

## Capabilities

- Detect entities, key phrases, dominant language, syntax, and sentiment in real time
- Identify and redact personally identifiable information with ContainsPiiEntities and DetectPiiEntities
- Run targeted sentiment analysis to attribute sentiment to specific entities
- Train custom document classifiers and custom entity recognizers on labeled data
- Run asynchronous topic modeling jobs over document collections in S3
- Classify documents and detect entities at scale using batch and async APIs
- Manage endpoints, model versions, and dataset flywheels for ongoing retraining

## Use cases

### Customer Feedback Sentiment Analysis

Product teams need to understand whether customer reviews, support tickets, and survey responses are positive, negative, or mixed. Amazon Comprehend's DetectSentiment and BatchDetectSentiment return sentiment with confidence scores in real time, and StartSentimentDetectionJob handles archives of millions of documents asynchronously. A basic integration takes under a day.

Example prompt: Call BatchDetectSentiment with a list of 10 review texts and return the dominant sentiment and confidence scores per review.

### PII Redaction in Customer Support

Compliance teams need to remove names, emails, phone numbers, and account IDs from logs and transcripts before they enter analytics or training pipelines. Amazon Comprehend's DetectPiiEntities and ContainsPiiEntities identify PII spans with type labels (EMAIL, SSN, PHONE, etc.), and StartPiiEntitiesDetectionJob redacts at scale across S3 inputs.

Example prompt: Call DetectPiiEntities on a customer transcript and return all spans with offsets, types, and confidence so the caller can mask them.

### Custom Document Classification

Operations teams routing tickets, claims, or emails need a classifier tuned to their categories. Amazon Comprehend trains a custom classifier from labeled examples in S3, deploys it to a real-time endpoint, and serves ClassifyDocument calls. Training is asynchronous and typically completes in under an hour for small datasets.

Example prompt: Call CreateDocumentClassifier with an S3 path of labeled CSV training data, poll DescribeDocumentClassifier until the status is TRAINED, then create an endpoint and invoke ClassifyDocument.

### Topic Modeling over a Document Corpus

Research and content teams need to discover themes across thousands of documents without labeled data. Amazon Comprehend's StartTopicsDetectionJob runs LDA-based topic modeling on a corpus in S3 and writes topic-term and document-topic distributions back to S3. Jobs typically run in a few hours depending on corpus size.

Example prompt: Start a topics detection job with an InputDataConfig pointing at an S3 prefix and 20 topics, then poll DescribeTopicsDetectionJob until status is COMPLETED.

### Agent-Powered Text Triage

An AI agent triaging inbound communications can chain Comprehend operations: detect language, redact PII, classify the message, then extract entities. Through Jentic, the agent calls each operation by intent without managing SigV4 signing or boto3 sessions, and can deploy a custom classifier endpoint on demand.

Example prompt: For an input message: call DetectDominantLanguage, then DetectPiiEntities, then ClassifyDocument against a deployed endpoint, and return a structured triage result.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /#X-Amz-Target=Comprehend_20171127.DetectSentiment | Detect sentiment in a single document |
| POST | /#X-Amz-Target=Comprehend_20171127.BatchDetectEntities | Detect entities in up to 25 documents |
| POST | /#X-Amz-Target=Comprehend_20171127.DetectPiiEntities | Detect PII spans in a document |
| POST | /#X-Amz-Target=Comprehend_20171127.ClassifyDocument | Classify a document using a custom classifier endpoint |
| POST | /#X-Amz-Target=Comprehend_20171127.CreateDocumentClassifier | Train a custom document classifier |
| POST | /#X-Amz-Target=Comprehend_20171127.StartTopicsDetectionJob | Run topic modeling over an S3 corpus |
| POST | /#X-Amz-Target=Comprehend_20171127.CreateEndpoint | Create a real-time inference endpoint |

## Key resources

- **Detection** — Real-time detection of entities, key phrases, sentiment, syntax, language, and PII via Detect* and BatchDetect* operations.
- **AsynchronousJob** — Long-running detection jobs over S3 input via StartEntitiesDetectionJob, StartSentimentDetectionJob, StartPiiEntitiesDetectionJob, and StartTopicsDetectionJob.
- **DocumentClassifier** — Train, version, and serve custom document classifiers via CreateDocumentClassifier, DescribeDocumentClassifier, and ClassifyDocument.
- **EntityRecognizer** — Train and run custom entity recognizers via CreateEntityRecognizer, DescribeEntityRecognizer, and StartEntitiesDetectionJob with a custom recognizer ARN.
- **Endpoint** — Manage real-time inference endpoints via CreateEndpoint, UpdateEndpoint, and DeleteEndpoint.
- **Flywheel** — Continuously retrain custom models with CreateFlywheel and StartFlywheelIteration.

## Why Jentic

- **Setup:** Wiring Amazon Comprehend by hand means signing every request with AWS Signature v4 HMAC, targeting the right regional host like comprehend.{region}.amazonaws.com, and dispatching each operation through the X-Amz-Target header instead of a REST path. Through Jentic you install once, import Amazon Comprehend from the API Directory, store the AWS access key and secret once, and your agent calls it.
- **Permission scoping:** Comprehend routes operations through the X-Amz-Target header and carries the input text and job configuration in the request body, not the URL path, so scoping is by operation. You limit the agent to the operations it needs, such as DetectSentiment or DetectPiiEntities, so training and cost operations like CreateDocumentClassifier or CreateEndpoint are not included unless you add them.
- **Credential handling:** Your AWS access key and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time when the request is signed. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'detect entities and sentiment in text' or 'redact PII from a document', and Jentic returns the matching Comprehend operation with its input schema, so the agent calls DetectSentiment or DetectPiiEntities without browsing the AWS service reference.

## Related APIs

- **Google Cloud Natural Language API** — GCP managed NLP for sentiment, entities, and syntax.
- **OpenAI API** — LLM-based extraction and classification with prompt-driven flexibility.
- **Amazon Kinesis Analytics** — SQL and Apache Flink analytics on streaming AWS data.
- **Amazon Textract** — Extracts text from scanned documents and forms before NLP analysis.

## FAQ

### Why is there no official OpenAPI spec for Amazon Comprehend?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Amazon Comprehend via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Amazon Comprehend API use?

AWS Signature v4 (HMAC) signing with an IAM principal that has comprehend:* permissions. Jentic stores the AWS credentials in its vault and signs each request, so the agent only sees the operation result.

### Can I redact PII automatically with the Amazon Comprehend API?

Yes. Use DetectPiiEntities to get spans, types, and offsets for each PII mention, or StartPiiEntitiesDetectionJob with Mode=ONLY_REDACTION to write redacted documents back to S3 in bulk.

### What languages does the Amazon Comprehend API support?

DetectDominantLanguage covers 100+ languages. Sentiment, key phrases, entities, and syntax support a smaller set including English, Spanish, French, German, Italian, Portuguese, Japanese, Korean, Hindi, Arabic, and simplified Chinese - check the spec's LanguageCode enum for each operation.

### What are the rate limits for the Amazon Comprehend API?

Per-account, per-region TPS limits apply per operation; Detect* synchronous calls are higher TPS than custom classifier endpoints, which are limited by provisioned inference units. Plan for ThrottlingException with exponential backoff or use BatchDetect* and async jobs for high volume.

### How do I run sentiment analysis with the Amazon Comprehend API through Jentic?

Search Jentic for 'detect the sentiment of a piece of text', load the DetectSentiment schema, and execute it with Text and LanguageCode. For large batches, use BatchDetectSentiment (up to 25 documents per call) or StartSentimentDetectionJob for S3 inputs.

### Can I limit what my agent is allowed to do with the Amazon Comprehend API?

Yes. Because Amazon Comprehend routes every operation through the X-Amz-Target header rather than a URL path, your self-hosted Jentic One instance scopes access by operation, and your own rules decide which ones the agent may call. You can allow read-style analysis operations like DetectSentiment and DetectPiiEntities while excluding training and cost operations such as CreateDocumentClassifier and CreateEndpoint. The AWS access key and secret are injected only at execution time under those rules, so the agent can invoke only the Comprehend operations you have permitted.