canonical: https://jentic.com/apis/lexalytics.com/lexalytics

# Lexalytics Semantria API

Jentic publishes the only available OpenAPI specification for Semantria API, keeping it validated and agent-ready. Semantria is the SaaS text analytics service from Lexalytics that runs sentiment analysis, entity extraction, theme detection, taxonomy classification, and topic queries against unstructured text. The 29-endpoint API exposes session-based authentication, document and collection queues for batched analysis, configurable blacklists and user entities, and a programmable taxonomy, so teams can deliver tuned NLP pipelines for voice-of-customer, social listening, and content classification work.

## For AI agents

Run sentiment, entity, theme, and taxonomy analysis on text with Lexalytics Semantria - queue documents and collections, manage configurations, and pull processed results.

## Scope

Does not generate text, translate languages, or transcribe audio - use for sentiment, entity, theme, and taxonomy analysis on existing text only.

## Capabilities

- Queue text documents for sentiment, entity, and theme analysis via POST /documents and retrieve processed output from GET /documents
- Submit document collections for batch analysis through POST /collections and read aggregate results at GET /collections
- Manage analysis configurations including language and feature toggles using /configs and `/configs/{configId}`
- Define a programmable taxonomy and query topics for classification through /taxonomy and /topics
- Maintain user entities and blacklist terms to tune extraction precision via /entities and /blacklist
- Operate session-scoped credentials by creating, listing, and deleting Semantria sessions on `/auth/sessions`
- Inspect account-level usage statistics, available features, and account details through /statistics, /features, and /details

## Use cases

### Voice-of-customer sentiment analysis

A CX team wants to score thousands of survey responses and reviews for sentiment, themes, and named entities. The integration creates a Semantria session via POST `/auth/sessions`, configures language and features at POST /configs, queues responses with POST /documents, and polls GET /documents for processed output. Results land in a warehouse as structured rows ready for dashboards rather than free text.

Example prompt: Queue 500 review documents via POST /documents with a configId for English sentiment analysis, then poll GET /documents until each is processed and write sentiment scores to the warehouse.

### Domain-tuned classification with custom taxonomy

A media-monitoring vendor needs to classify articles into a bespoke industry taxonomy. They define nodes through POST /taxonomy, register query topics with POST /topics, and submit articles to /collections. Semantria returns each article tagged against the custom taxonomy, allowing the team to build domain-specific dashboards without training a model from scratch.

Example prompt: POST /taxonomy with three new nodes (Renewables, Grid, Policy), then POST /collections containing 50 energy articles tagged for analysis against that taxonomy.

### Entity extraction tuning

An analytics team finds that Semantria over-tags certain terms or misses internal product names. They tune precision by adding domain-specific user entities via POST /entities and suppressing noise through POST /blacklist. After re-running representative documents, extracted entities better reflect the customer's domain without retraining.

Example prompt: POST /entities with the company's product code list, then POST /blacklist with 10 noise terms, requeue 100 documents, and verify the new entity coverage.

### AI agent text analytics via Jentic

An AI research agent needs sentiment and entity scores for a batch of news mentions. Through Jentic the agent searches for 'analyse text sentiment' or 'extract named entities', loads the matching Semantria operation, and executes with the session token held in your Jentic One instance. The agent gets structured output back without dealing with Semantria's session-based auth dance.

Example prompt: Use Jentic to search 'analyse a batch of text for sentiment', queue documents via POST /documents, and return the processed sentiment polarity per document once GET /documents shows them as processed.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/auth/sessions` | Create a Semantria session token. |
| POST | `/documents` | Queue documents for analysis. |
| GET | `/documents` | Retrieve processed documents. |
| POST | `/collections` | Queue a collection for batch analysis. |
| POST | `/configs` | Create an analysis configuration. |
| POST | `/taxonomy` | Add taxonomy nodes for classification. |
| POST | `/entities` | Add user-defined entities. |

## Key resources

- **Documents** — Queue text documents for analysis and pull processed output.
- **Collections** — Batch text into collections for aggregate sentiment and theme analysis.
- **Configurations** — Define language, features, and tuning for analysis jobs.
- **Taxonomy** — Build a programmable taxonomy of nodes for classification.
- **Topics** — Define query topics that categorise text by signal.
- **Entities** — Register custom user entities to improve extraction precision.
- **Sessions** — Manage Semantria session tokens for authenticated requests.

## Why Jentic

- **Setup:** Wiring the Semantria API by hand means first calling POST `/auth/sessions` for a token, setting it in the Authorization header, tracking configIds for each analysis, and calling api5.semantria.com yourself. Through Jentic you install once, import the Semantria API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Semantria queues text against collection endpoints like /documents, /collections, and /configs rather than a resource id in the path, so scope the agent to the operations it needs, such as submitting documents or reading results. You leave out configuration or taxonomy writes unless you add them, so it only calls the ones you allow.
- **Credential handling:** Your Semantria session token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'analyse text for sentiment' or 'classify articles against a taxonomy', and Jentic returns the matching Semantria operation with its input schema, including the configId requirement, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio API** — Voice and messaging platform that supplies the inbound text Semantria can analyse for sentiment.
- **Zendesk API** — Support ticket platform whose conversation text is a common input to Semantria sentiment analysis.
- **Snov.io API** — Email outreach platform that can use Semantria sentiment scoring on reply text to triage responses.

## FAQ

### Why is there no official OpenAPI spec for Semantria API?

Lexalytics does not publish a maintained OpenAPI specification for Semantria. Jentic generates and maintains this spec so that AI agents and developers can call Semantria 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 Semantria API use?

Semantria uses an API token in the 'Authorization' header, obtained from the Create Session endpoint at POST `/auth/sessions.` The session token scopes calls to your Semantria account. Through Jentic the token lives in your Jentic One instance and is injected on each request.

### Can I run sentiment and entity analysis on the same document with Semantria?

Yes. Configure features (sentiment, entities, themes, taxonomy) via POST /configs, then queue the document with POST /documents referencing that configId. The processed result returned from GET /documents includes all enabled feature outputs in one payload.

### What are the rate limits for the Semantria API?

Lexalytics applies per-account throughput and document quotas tied to your Semantria plan; exact numbers are not in the public spec. Track usage with GET /statistics, paginate /documents and /collections retrievals, and respect any 429 responses with backoff.

### How do I queue documents for analysis through Jentic?

Install with 'pip install jentic', search for 'analyse text for sentiment', and Jentic returns POST /documents. Load the schema, supply the document id, text, and configId, and execute. Then poll GET /documents to retrieve the processed sentiment, entities, and themes.

### Can I tune extraction with my own entities and blacklist terms?

Yes. POST /entities registers user entities (e.g., your product names) so they are reliably extracted, and POST /blacklist suppresses noise terms. Both apply at the configuration level and improve precision on domain-specific text without retraining.

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

Yes. Because you run Jentic One yourself, your own rules decide which Semantria operations and credentials the agent can use. Semantria works against collection endpoints like /documents, /collections, and /configs rather than a resource id in the path, so you can scope the agent to just the operations it needs, such as submitting documents with POST /documents or reading processed results from GET /documents. Configuration and taxonomy writes like POST /configs and POST /taxonomy stay off limits unless you explicitly allow them, and the session token is injected at execution time without entering the agent's prompt.