canonical: https://jentic.com/apis/icarusapi.keatext.ai/keatext

# Icarusapi Keatext Keatext Partner API

Keatext is a customer and employee feedback analytics platform that turns open-ended survey responses, support tickets, and review text into themes, indicators, and AI-generated recommendations. The Partner API exposes the dataset model used to ingest feedback records, the analytics resources that surface statements, topics, and indicators, and the document-level views used by Keatext's reporting UI. It is suited to teams embedding Keatext analysis into their own BI stack or piping in feedback from CRM, survey, or contact-centre platforms.

## For AI agents

Ingest feedback records into Keatext datasets, then query analytics resources for statements, topics, indicators, and per-document summaries.

## Scope

Does not handle survey distribution, response collection UIs, or external sentiment models - use for ingesting feedback into Keatext datasets and reading the resulting analytics only.

## Capabilities

- Authenticate to the Keatext API via `/auth/login`
- Manage feedback datasets via /datasets and `/datasets/{datasetId}`
- Configure dataset fields via `/datasets/{datasetId}/fields` and `/fields/{fieldKey}`
- Push and read records on a dataset via `/datasets/{datasetId}/records`
- Query analytics statements and topics via `/analytics/statements` and `/analytics/topics`
- Query analytics indicators and per-document analytics via `/analytics/indicators` and `/analytics/documents`
- Manage organisation context via /organizations

## Use cases

### Feedback Ingestion

Stream customer or employee feedback records from a CRM, survey, or ticketing platform into Keatext for AI-driven theme analysis. POST records to `/datasets/{datasetId}/records` after configuring the relevant fields with `/datasets/{datasetId}/fields.` Once ingested, the records flow into Keatext's analytics so themes, sentiment, and indicators stay current.

Example prompt: POST a batch of survey responses to `/datasets/{datasetId}/records` with the comment text, rating, and submission date for each record.

### Theme and Topic Reporting

Pull the AI-generated topics, statements, and indicators that Keatext surfaces over a dataset to feed into a BI dashboard or executive summary. The `/analytics/topics`, `/analytics/statements`, and `/analytics/indicators` endpoints return the structured outputs Keatext computes, which makes it possible to embed Keatext analysis natively in tools that already serve the rest of the organisation.

Example prompt: GET `/analytics/topics` for the customer-feedback dataset and post the top five topics with their statement counts to a weekly summary.

### Per-Document Analysis Lookup

Look up Keatext's analysis of an individual document - for example, the themes and statements extracted from a single support ticket. The `/analytics/documents` endpoint lists analyses across the dataset and `/analytics/documents/{documentId}` returns the per-document detail, which is useful when surfacing Keatext output inside a CRM or helpdesk record view.

Example prompt: GET `/analytics/documents/{documentId}` for the linked support ticket and surface the top three statements in the ticket sidebar.

### AI Agent Voice-of-Customer Reader

An AI agent uses Jentic to read Keatext analytics and produce voice-of-customer briefings or alerts when new themes appear. The agent searches by intent, loads the analytics topics schema, and calls the API on a schedule, never holding the raw bearer token. Typical agent integration is under one hour because the analytics surface is concentrated under /analytics.

Example prompt: Search Jentic for 'list Keatext analytics topics', load the `/analytics/topics` schema, fetch the topics for the dataset, and summarise the top five for the weekly report.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/auth/login` | Authenticate against the API |
| GET | `/datasets` | List datasets |
| GET | `/datasets/{datasetId}/records` | List records on a dataset |
| GET | `/datasets/{datasetId}/fields` | List dataset fields |
| GET | `/analytics/statements` | List analytics statements |
| GET | `/analytics/topics` | List analytics topics |
| GET | `/analytics/indicators` | List analytics indicators |
| GET | `/analytics/documents` | List per-document analyses |

## Key resources

- **Datasets** — Manage feedback datasets and their fields
- **Records** — Push and read feedback records on a dataset
- **Analytics** — Read statements, topics, indicators, and per-document analyses
- **Authentication** — Authenticate against the API
- **Organizations** — Manage organisation context

## Why Jentic

- **Setup:** Wiring the Keatext Partner API by hand means logging in for a bearer token and mapping its dataset ingestion and analytics routes yourself. Through Jentic you install once, import the Keatext Partner API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Keatext puts the dataset id in the URL path (`/datasets/{datasetId}/...`), so a rule can pin your agent to one dataset: it can read that dataset's records, fields, and analytics. You choose the operations it may call, so anything beyond those reads is not included unless you add it.
- **Credential handling:** Your Keatext 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 'read a Keatext dataset's records' or 'get sentiment topics', and Jentic returns the matching Keatext operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Qualtrics API** — Qualtrics is a full experience-management platform; Keatext focuses on AI-driven theme extraction over open-text feedback.
- **SurveyMonkey API** — SurveyMonkey collects survey responses; Keatext analyses the open-text answers for themes and indicators.
- **Typeform API** — Typeform collects conversational survey responses that feed naturally into Keatext analysis.

## FAQ

### What authentication does the Keatext Partner API use?

The Keatext API uses a session token obtained from `/auth/login` and passed as a bearer token on subsequent calls. Through Jentic, the Keatext credentials are stored in your Jentic One instance and the agent calls Keatext via a scoped Jentic credential rather than the raw token.

### Can I push feedback records into a Keatext dataset?

Yes. POST records to `/datasets/{datasetId}/records` after configuring the dataset fields under `/datasets/{datasetId}/fields.` Records flow into Keatext's analytics pipeline and surface in the topics, statements, and indicators endpoints.

### How do I read analytics topics through Jentic?

Search Jentic for 'list Keatext analytics topics', load the `/analytics/topics` schema, and execute. Install the SDK with pip install jentic and use the async search, load, execute pattern from Python.

### Can I look up the analysis of a single document?

Yes. GET `/analytics/documents` lists per-document analyses across the dataset, and `/analytics/documents/{documentId}` returns the analysis for one document. Pair the document ID with the original record ID to surface insights inside a CRM or helpdesk view.

### What are the rate limits for the Keatext Partner API?

The published spec does not declare per-endpoint rate limits. Keatext applies plan-level account limits documented in the partner portal - start with conservative batching when ingesting records and back off on 429 responses.

### How do I configure new fields on an existing dataset?

POST a field definition to `/datasets/{datasetId}/fields`, then read `/datasets/{datasetId}/fields/{fieldKey}` to confirm. New fields can be referenced when posting records and will be exposed as filters and dimensions in the analytics endpoints.

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

Yes. Jentic One is self-hosted, so your own rules decide which Keatext operations and credentials the agent may use. Because Keatext carries the dataset id in the URL path (`/datasets/{datasetId}/...`), a rule can pin your agent to a single dataset and let it read only that dataset's records, fields, and analytics such as `/analytics/topics` and `/analytics/statements.` You choose the operations it may call, so anything beyond those reads, including record ingestion via POST `/datasets/{datasetId}/records`, is excluded unless you add it.