canonical: https://jentic.com/apis/kimiya.ai/kimiya

# Kimiya AI API

Jentic publishes the only available OpenAPI specification for Kimiya AI API, keeping it validated and agent-ready. Kimiya AI is a chatbot platform that connects a single AI assistant to multiple messaging surfaces including WhatsApp, Shopify, and external automation tools through Zapier and N8N. The API exposes operations to send chat requests, upload and update training files, auto-reply to customer messages, manage Shopify bot configuration, and register webhook listeners. Authentication uses an X-API-KEY header.

## For AI agents

Send chat requests to a Kimiya AI bot, upload training material, auto-reply to incoming messages, and manage WhatsApp and Shopify channel bindings.

## Scope

Does not host the underlying language model, manage CRM records, or process payments - use for sending chat requests and managing bot training and channel bindings only.

## Capabilities

- Send a chat request to a Kimiya AI assistant and receive a generated reply
- Upload files to retrain the assistant's knowledge base
- Update existing training files when source content changes
- Auto-reply to incoming Shopify or WhatsApp messages on behalf of the bot
- Bind a Kimiya bot to a WhatsApp number and verify the webhook
- Read Shopify chat history and dashboard stats over a date range
- Register and unregister N8N webhook endpoints

## Use cases

### Shopify customer support assistant

A Shopify store can route incoming customer questions to Kimiya AI by calling POST `/api/Chat/Request` and returning the generated answer to the buyer. The same surface exposes GET `/api/shopify/Dashboard` so an operator can see how many chats the bot handled and where it deferred to a human.

Example prompt: POST a chat request to `/api/Chat/Request` with the buyer's question and return the generated reply to the Shopify chat widget.

### WhatsApp auto-reply

When a WhatsApp webhook delivers an inbound message, an integration can call POST `/api/Zapier/AutoReply` to have Kimiya generate and send a contextual response. POST `/api/whatsapp/webhook/{apikey}` handles inbound delivery and GET `/api/whatsapp/bindingBots` binds the bot to the number.

Example prompt: POST the inbound WhatsApp message body to `/api/Zapier/AutoReply` and confirm Kimiya returned a reply that was sent on the channel.

### Knowledge base retraining

When a product catalog or policy document changes, an automation can POST `/api/Zapier/UploadFile` with the new file or POST `/api/Zapier/UpdateFile` to replace an existing source. The bot picks up the new content for subsequent chat requests without manual retraining.

Example prompt: Detect a new policy PDF in the source folder and POST it to `/api/Zapier/UploadFile` to retrain the assistant.

### Agent integration via Jentic

An agent can use Jentic to discover the Kimiya chat operation, load its schema, and call POST `/api/Chat/Request` with a user prompt. The X-API-KEY is supplied from your Jentic One instance, so the agent process never sees the raw key.

Example prompt: Search Jentic for 'send a chat request to Kimiya AI', load POST `/api/Chat/Request`, and execute it with the user's question.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/Chat/Request` | Send a chat request to the assistant |
| POST | `/api/Zapier/UploadFile` | Upload a training file |
| POST | `/api/Zapier/UpdateFile` | Update a training file |
| POST | `/api/Zapier/AutoReply` | Auto-reply to an inbound message |
| GET | `/api/shopify/Dashboard` | Get Shopify dashboard stats |
| POST | `/api/whatsapp/webhook/{apikey}` | Receive a WhatsApp webhook |
| POST | `/api/N8N/RegisterWebhook` | Register an N8N webhook |

## Key resources

- **Chat** — Send chat requests and receive generated replies
- **Files** — Upload and update training files for the assistant
- **Messages** — Auto-reply or send messages on a connected channel
- **Shopify** — Read chat history, dashboard stats, and bot configuration for a Shopify store
- **WhatsApp** — Bind the bot to a WhatsApp number and handle the webhook
- **Webhooks** — Register and unregister N8N webhook listeners

## Why Jentic

- **Setup:** Wiring Kimiya AI by hand means learning its X-API-KEY header auth, handling the internalwebapi.kimiya.ai host, and threading its chat and channel-binding calls yourself. Through Jentic you install once, import Kimiya AI from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Kimiya AI carries the chat request and file targets in the request body rather than as a URL path resource, so scope by operation: limit the agent to the operations it needs, such as sending a chat request, and leave file updates or channel registration out unless you add them.
- **Credential handling:** Your Kimiya AI API key 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 'send a chat request to the bot' or 'upload a training file', and Jentic returns the matching Kimiya AI operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ChatBot API** — ChatBot is a hosted chatbot platform with similar multi-channel reach
- **Tidio API** — Tidio combines live chat and AI replies for e-commerce stores
- **Shopify API** — Shopify holds the orders and product catalog the Kimiya bot answers questions about
- **n8n API** — n8n orchestrates the workflows that route inbound messages to Kimiya

## FAQ

### Why is there no official OpenAPI spec for Kimiya AI API?

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

Every request carries an X-API-KEY header. Jentic stores the key in the vault and injects it on each call, so the agent process never reads the raw value.

### Can I auto-reply to WhatsApp messages with the Kimiya AI API?

Yes. POST the inbound message to `/api/Zapier/AutoReply` and Kimiya generates and sends a reply on the bound channel. Use POST `/api/whatsapp/webhook/{apikey}` to receive the inbound delivery and `/api/whatsapp/bindingBots` to bind the bot to the number first.

### What are the rate limits for the Kimiya AI API?

The OpenAPI specification does not declare explicit rate limits. Cache the bot configuration retrieved from `/api/shopify/GetBotConfig` rather than fetching it on every chat, and back off if the chat endpoint returns a 429.

### How do I send a chat request with the Kimiya AI API through Jentic?

Run pip install jentic, search Jentic for 'send a chat request to Kimiya AI', load the POST `/api/Chat/Request` operation, and execute it with the user's question. Jentic supplies the X-API-KEY header from the vault.

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

Yes. Because you run Jentic One yourself, your own rules decide which Kimiya AI operations and credentials the agent may use. Since Kimiya AI carries the chat and file targets in the request body rather than in the URL path, you scope by operation: allow only what the agent needs, such as POST `/api/Chat/Request` to send a chat request. Operations like uploading or updating training files or registering WhatsApp and N8N channels stay off limits unless you add them.