canonical: https://jentic.com/apis/pandorabots.com/pandorabots-aiaas

# Pandorabots AIaaS API

Pandorabots AIaaS (AI as a Service) provides API access to a chatbot hosting platform based on AIML (Artificial Intelligence Markup Language). The API supports bot creation, AIML file management, bot compilation, conversational interactions with persistent predicates, client session management, debug mode conversation, and bot listing. Developers can upload AIML files, substitute files, sets, and maps to define bot behavior, compile bots, then interact via Talk or Anonymous Talk endpoints. Authentication uses user_key query parameter with rate limits based on subscription plan.

## For AI agents

Create, manage, compile, and talk to AIML-based chatbots with persistent predicates, session management, and debug mode conversation.

## Scope

Does not provide natural language understanding, intent recognition, or generative AI - use only for AIML pattern-matching chatbots with deterministic responses. For generative AI, use LLM-based APIs like OpenAI or Claude.

## Capabilities

- Create and delete AIML chatbots with custom botnames
- Upload and manage AIML files, substitute files, sets, and maps
- Compile bots to prepare them for conversation
- Talk to bots with persistent predicates and session management
- Use Anonymous Talk API to create end-user client identities
- Debug bot responses with trace mode showing pattern matching
- List all bots under an application ID
- Retrieve bot properties and conversation history metadata

## Use cases

### Custom Chatbot Deployment from AIML

Deploy custom AIML-based chatbots by creating a bot via PUT `/bot/{app_id}/{botname}`, uploading AIML files with PUT `/bot/{app_id}/{botname}/{file-kind}/{filename}`, then compiling with GET `/bot/{app_id}/{botname}/verify.` Once compiled, talk to the bot via POST `/talk/{app_id}/{botname}` with user input. This supports conversational AI applications with hand-crafted dialog trees and pattern-matching logic.

Example prompt: PUT `/bot/{app_id}/{botname}` to create, PUT `/bot/{app_id}/{botname}/file/{filename}` to upload AIML, GET `/bot/{app_id}/{botname}/verify` to compile, POST `/talk/{app_id}/{botname}`?input=hello to converse.

### Multi-User Conversation with Persistent Predicates

Support multiple end-users talking to the same bot with isolated conversation state by using client_name to identify each user. POST `/talk/{app_id}/{botname}`?client_name=user123&input=hello maintains predicates (variables) per user across sessions. This enables personalized chatbot experiences where each user's conversation history and context are preserved.

Example prompt: POST `/talk/{app_id}/{botname}`?client_name={unique_user_id}&input={message} to maintain per-user state.

### Anonymous User Onboarding

Create anonymous end-user identities for new chatbot users with POST `/atalk/{app_id}/{botname}`?input=hello without providing client_name. Pandorabots generates a unique client_name in the format aiaas-XXX-user-nnnn and returns it in the response. Subsequent conversations use this client_name to maintain state. This supports chatbot onboarding flows where users start conversations before authenticating.

Example prompt: POST `/atalk/{app_id}/{botname}`?input=hello to generate a new client_name, store it, then use POST /talk with the client_name for future messages.

### Chatbot Debugging with Trace Mode

Debug AIML pattern matching and bot responses by using GET `/debugbot/{app_id}/{botname}`?input=hello which returns not only the bot's response but also trace data showing which AIML categories matched, predicates evaluated, and SRAI redirections. This supports bot development workflows where developers need visibility into AIML execution paths.

Example prompt: GET `/debugbot/{app_id}/{botname}`?input={test_message}&client_name={test_user} to see trace output and matched AIML patterns.

### AI Agent for AIML Bot Management

Let an AI agent manage Pandorabots chatbots - creating bots, uploading AIML files, compiling, testing conversations, and deploying. Through Jentic, the agent searches by intent (e.g., 'create pandorabots bot'), loads the schema, and executes with the user_key injected securely, enabling conversational bot management.

Example prompt: Use Jentic search 'create pandorabots bot' to find PUT `/bot/{app_id}/{botname}`, load schema, execute with user_key.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | `/bot/{app_id}/{botname}` | Create a new bot |
| PUT | `/bot/{app_id}/{botname}/file/{filename}` | Upload AIML file |
| GET | `/bot/{app_id}/{botname}/verify` | Compile the bot |
| POST | `/talk/{app_id}/{botname}` | Talk to bot with persistent state |
| POST | `/atalk/{app_id}/{botname}` | Anonymous talk to create client_name |
| GET | `/debugbot/{app_id}/{botname}` | Debug bot responses with trace |
| GET | `/bot/{app_id}` | List all bots |

## Key resources

- **Bots** — AIML-based chatbots with unique botnames under an application ID
- **AIML Files** — Pattern-matching dialog definitions in AIML XML format
- **Client Names** — End-user identifiers for persistent predicates and conversation state
- **Sessions** — Conversation groupings with session IDs for multi-turn interactions
- **Files** — Substitute files, sets, and maps used by AIML for variable substitution and lookups

## Why Jentic

- **Setup:** Wiring Pandorabots by hand means passing its user_key as a query parameter against aiaas.pandorabots.com, shaping the bot and file requests, and building your own retry and error handling. Through Jentic you install once, import the Pandorabots AIaaS API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Pandorabots puts the app id and bot name in the URL path (`/bot/{app_id}/{botname}`), so a rule can pin your agent to one bot: it can talk to that bot and nothing else. You choose the operations it may call, so uploading files or creating a bot is not included unless you add them.
- **Credential handling:** Your Pandorabots user_key is stored once, encrypted, by your own Jentic One instance and injected as a query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'talk to a Pandorabots chatbot' or 'create a bot', and Jentic returns the matching Pandorabots operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenAI API** — OpenAI provides LLM-based conversational AI with GPT models, while Pandorabots provides AIML pattern-matching chatbots with deterministic responses.
- **Dialogflow API** — Google's conversational AI platform for building chatbots and voice agents — an alternative to Pandorabots for natural-language dialogue.

## FAQ

### What authentication does the Pandorabots AIaaS API use?

The Pandorabots API uses user_key as a query parameter for authentication. The user_key is obtained from the Pandorabots dashboard after creating an application. Through Jentic, keys are stored encrypted and injected at execution time.

### What is AIML?

AIML (Artificial Intelligence Markup Language) is an XML-based language for defining chatbot dialog patterns and responses. Pandorabots hosts AIML-based bots and provides an API for uploading AIML files, compiling bots, and conversing with them.

### How do I maintain conversation state per user?

Use the client_name parameter in POST /talk to identify each end-user. Pandorabots maintains predicates (variables) per client_name, enabling personalized conversations with memory of previous interactions.

### Can I debug my bot's responses?

Yes. Use GET /debugbot with input to see trace data showing which AIML patterns matched, predicates evaluated, and SRAI redirections. This helps debug pattern-matching logic.

### Is the Pandorabots API free?

Pandorabots offers a free tier with limited API calls and bot hosting. Paid plans unlock higher rate limits, more bots, and advanced features. Check pandorabots.com for pricing.

### How do I deploy a bot?

Create a bot with PUT `/bot/{app_id}/{botname}`, upload AIML files with PUT `/bot/{app_id}/{botname}/file/{filename}`, compile with GET `/bot/{app_id}/{botname}/verify`, then talk via POST /talk.

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

Yes. Jentic One is self-hosted by you, so your own rules decide which Pandorabots operations and credentials the agent may use. Because the API puts the app id and bot name in the URL path, such as `/bot/{app_id}/{botname}`, you can pin the agent to a single bot and let it only talk to that bot through POST /talk while blocking everything else. You choose the operations it may call, so creating a bot with PUT `/bot/{app_id}/{botname}` or uploading AIML files is excluded unless you add them, and your encrypted user_key is injected only at execution time.