Pearl AI API: A Complete Guide to Integrating Pearl AI Into Your Applications
Most teams do not struggle to find an AI model. They struggle to get one working inside the product, portal or workflow their customers already use. That gap is exactly what the Pearl AI API is built to close. Pearl AI, from Pearl Organisation, is a hosted AI service exposed as a plain REST API, so a developer can send a conversation and receive an answer with a few lines of code.
This guide walks through the Pearl AI API from end to end. You will learn what it is, how Pearl AI API integration works, which Pearl AI API features matter in production, and how to integrate Pearl AI into applications with working Node.js, Python and cURL examples. It also covers the Pearl AI Chat API and Pearl AI chatbot API patterns, errors and limits, security habits, pricing, and the use cases where the API earns its place.
A quick note on the name: “Pearl” is used by several unrelated companies, including expert-verified answer services and AI tools for other industries. In this guide, Pearl AI and the Pearl AI API refer only to the service from Pearl Organisation at products.pearlorganisation.com. When you search for Pearl AI API documentation, always check the domain before you copy a key or an endpoint.
Pearl AI API at a Glance
Item | What to know |
Provider | Pearl Organisation, an IT and digital business transformation company serving clients in 150+ countries |
What it is | A hosted AI service called over HTTPS, in the familiar chat-completions request shape |
Models | pearl-4-mini (fast, low cost, the default) and pearl-4 (higher accuracy and reasoning) |
Authentication | Bearer API key that starts with pai_, shown once when you create it |
Rate limit | 60 requests a minute per API key |
Starting price | $50 a month plus usage credits, with a free playground for testing |
Documentation |
What Is the Pearl AI API?
The Pearl AI API is a production-grade AI service that you call over HTTPS. You send a list of messages, and Pearl AI returns a reply together with a short usage summary that shows the credits the request consumed. Because the request follows the chat-completions format used by most AI chat services, a developer who has connected to one of them before will recognise it at once.
Pearl Organisation states that Pearl AI is the same completions engine that powers its own Pearl AI Chat product and the internal tools used across its team. That matters for buyers. You are not adopting a thin wrapper that appeared last month; you are building on infrastructure its maker already depends on every day.
Pearl AI, Pearl AI Chat and the Pearl AI Chat API: How They Fit Together
Pearl Products groups three products under one account and one sign-in: Pearl AI, Pearl AI Chat and Pearl Workstation Agent. Pearl AI is the API and playground. Pearl AI Chat is a ready-made chat agent that you add to a website, app, CRM or ERP with one script tag. Pearl Workstation Agent is a desktop application for workforce visibility, and it is not part of this guide.
The two routes to a chatbot are worth separating clearly. The no-code route is the Pearl AI Chat widget, which you train on your own content and install in minutes. The developer route is the Pearl AI Chat API: the same chat-completions engine, called directly through the chat endpoint or through an assistant’s own endpoint. In this guide, the Pearl AI chatbot API means that second route, where your team builds its own conversational experience on top of the API.
Pearl AI API Features That Matter in Production
A feature list only helps if each item solves a real integration problem. These are the Pearl AI API features that most affect how you design, ship and run an application.
Two Models on One Key
Pearl AI offers pearl-4-mini for fast, low-cost, high-volume calls and pearl-4 for production accuracy and reasoning. Both share the same request format, so switching between them is a one-line change to the model field. A sensible pattern is to default to the mini model for routine replies and send only the harder questions to pearl-4.
Assistants With Their Own Knowledge, Tools and Variables
An assistant is a saved set of instructions for one job, such as replying to support tickets or summarising leads. Each assistant has its own endpoint, its own knowledge (notes, exact questions and answers, up to five documents and pages from your website) and its own tools or MCP servers. Variables written as {{customer_name}} are filled in from each request, so one assistant can personalise thousands of replies.
Streaming, JSON Output, Threads and Background Jobs
Four optional settings cover the harder application needs. Streaming sends the answer word by word so users see progress straight away. JSON output, with an optional schema, returns data your code can read without parsing prose. Threads let Pearl keep the conversation for you. Background jobs handle long tasks and report back later.
Signed Webhooks
Pearl can send a message to your own server after each assistant answer and when a background answer is ready or has failed. Each delivery carries a signature you verify with your signing secret, so your server can trust where the event came from.
Keys, Limits and Security
You can create as many API keys as you need. Each key can be limited to chosen assistants and IP addresses, given an end date, and tracked for its own usage. Keys are stored only as a hash, traffic uses TLS 1.3, and two-step sign-in by WhatsApp or email is available on every account.
Observability and Spending Controls
Every request from the chat page, an API key or an assistant lands in one searchable activity log that you can export as CSV. On the billing side, you can set a monthly spending cap, receive low-balance alerts and turn on auto top-up, which keeps usage predictable for finance teams.
Pearl AI API for Developers: Why Teams Adopt It
Adoption usually comes down to friction. Here is where the Pearl AI API for developers removes it.
• A familiar request shape. Pearl Organisation states that any standard chat-completions client library works when you change the base URL, which shortens the learning curve.
• Self-serve access. You sign up with an email and password, confirm a six-digit code, and create a key. There is no sales call, and you do not need to be an existing Pearl Organisation client.
• A free playground. You can test Pearl AI for five minutes of active use without creating an account, so you can judge answer quality on your own questions first.
• Built-in tooling. Each assistant has a Code button with ready-to-copy Node.js, Python and cURL examples, plus a Postman collection, and a Try it panel that shows the matching API request.
• Human support. The documentation states there is no bot-only tier on any plan, so an engineer can help when an integration stalls.
Pearl AI API Documentation: Where to Start
The official Pearl AI API documentation lives at products.pearlorganisation.com/docs. It is written in plain language, so it works for developers and for the non-technical stakeholders who approve the project. For Pearl AI API integration, the sections below are the ones to read, in this order.
• Authentication: how API keys differ from email and password sign-in, and how to create a key.
• Your first request: the endpoint, header and a working example in cURL, Node.js and Python.
• Request options: model, temperature, response format, streaming, threads and background mode.
• Endpoints and models: the five stable paths and the two model tiers.
• Assistants, tools and knowledge: how to build a reusable assistant and test it before release.
• Advanced options and webhooks: JSON answers, streaming, threads, background jobs and signature checks.
• Errors and limits: every status code with what to do about it.
Keep the live system status page bookmarked as well. It shows the current state of each product, a day-by-day uptime history and a log of past incidents, which is useful when you need to tell a support team whether a problem is yours or the platform’s.
Integrate Pearl AI Into Applications: A Step-by-Step Walkthrough
This walkthrough shows how to integrate Pearl AI into applications, from a free test to a working server call. The same steps apply whether your front end is a web app, a mobile app, a CRM or an ERP, because the key and the call always live on your server.
Step 1: Test Pearl AI in the Playground
Open the playground from the products site and type a question from your own domain. Within a few seconds, you will see a reply, and you can judge tone, accuracy and speed before committing. The playground needs no sign-up or payment and lasts five minutes of active use.
Step 2: Create Your Account
Choose Get Started, enter an email address you check regularly, confirm the six-digit code that arrives, and set a password. One account covers every Pearl product. While you are there, switch on two-step verification from the Security tab; it adds a one-time code by WhatsApp or email, and each code expires after five minutes.
Step 3: Create an API Key
Sign in, open Subscriptions, then Pearl AI, and choose Create key. Creating a key needs a one-time code and sends a security email. The key starts with pai_ and is shown only once, so copy it into your secrets manager immediately. Limit it to the assistants and IP addresses it needs, and set an end date if the integration is temporary.
Step 4: Send Your First Request
The chat endpoint is a single POST. Here is the request in cURL, taken from the Pearl AI API documentation:
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{ "role": "system", "content": "You are a concise, helpful assistant." },
{ "role": "user", "content": "Summarize what Pearl AI does in one sentence." }
]
}'
The same call from Node.js and Python looks like this. Run both on a server, never in a visitor’s browser.
// Node.js
const response = await fetch("https://products.pearlorganisation.in/api/v1/chat/completions", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
messages: [
{ role: "system", content: "You are a concise, helpful assistant." },
{ role: "user", content: "Summarize what Pearl AI does in one sentence." }
]
})
});
const data = await response.json();
console.log(data.choices[0].message.content);
# Python
import requests
response = requests.post(
headers={"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"},
json={"messages": [
{"role": "system", "content": "You are a concise, helpful assistant."},
{"role": "user", "content": "Summarize what Pearl AI does in one sentence."},
]},
)
print(response.json()["choices"][0]["message"]["content"])
Step 5: Read the Response and Track Credits
A successful reply contains the answer at choices[0].message.content, plus a usage summary showing the credits that request used and the credits you have left. Log both. Watching credit use from the first day gives you a real cost per conversation before traffic grows.
Step 6: Keep the Key on Your Server
Your API key acts like a password for your account’s AI access, and anyone who holds it can spend your credits. Never place it in browser JavaScript, a mobile app or a public repository. Instead, let your own server receive the user’s message, call Pearl AI, and return the answer. The diagram below shows the pattern.
Reference architecture for Pearl AI API integration: the key stays on your server, and signed webhooks flow back to you.
Building With the Pearl AI Chat API and Pearl AI Chatbot API
Plain chat completions are enough for simple tasks. For a branded support bot or an in-product helper, assistants give you a better foundation, because they bundle instructions, knowledge and tools behind one endpoint.
Create and Call an Assistant
Open Pearl AI, then Configure, then Assistants, and choose New assistant. Give it a name and instructions, and write a variable wherever something changes between requests. After you save, the Code button shows an example with the assistant’s own address. The assistant ID starts with asst_ and goes in the URL, while your key starts with pai_ and goes in the header. Mixing them up is the most common first error.
-H "Authorization: Bearer pai_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [ { "role": "user", "content": "Hello" } ],
"variables": { "customer_name": "Asha", "plan": "Pro" }
}'
Pearl fills the values from variables into the assistant’s instructions before the reply is written. If a required variable is missing, the request is refused with a message that names it, which makes mistakes easy to catch in testing.
Keep Conversations With Threads
Normally your app sends the whole conversation with each request. With a thread, Pearl remembers it for you. Send thread_id as new with the first message, store the thr_ ID in the response, and from then on send only the newest message. Pearl uses the last 40 messages of the thread for each answer, and you can read or delete a thread through the API.
Stream Answers Into Your Chat Interface
For a live chat window, set stream to true. The reply arrives as server-sent events in the standard chat-completions streaming format, with each piece of text in choices[0].delta.content and a final data: [DONE] line. Streaming makes even long answers feel quick, because users read while the model writes.
Widget or API: Which Route Should You Choose?
Question | Pearl AI Chat widget | Pearl AI API |
Who builds the interface? | Pearl supplies it; you paste one script tag | Your developers build it |
Best for | Website support, lead capture, quick launch | Custom apps, workflows, back-office automation |
Control over design | Tone, logo and accent colour | Complete |
Human takeover | Built in | You design it |
Starting price | $100 a month plus usage | $50 a month plus usage |
Many teams use both: the widget for the public website and the API for internal tools and product features. One account and one set of credits-based controls keeps that mix simple.
Advanced Pearl AI Integration Patterns
Return Structured JSON for Your Code
When another system consumes the answer, ask for JSON. Use a json_object response format for any JSON, or supply a schema to receive exactly the fields you need. The answer appears as text and as a parsed object ready to use. A support team can classify tickets this way without parsing sentences.
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "ticket",
"strict": true,
"schema": {
"type": "object",
"properties": {
"intent": { "type": "string", "enum": ["cancel", "refund", "question", "other"] },
"order_id": { "type": "string" },
"urgent": { "type": "boolean" }
},
"required": ["intent", "order_id", "urgent"],
"additionalProperties": false
}
}
}
If the schema itself cannot be used, the API returns a 422 with a message describing what to change.
Run Long Tasks in the Background
For slow jobs, add async set to true on an assistant call. Pearl replies immediately with status 202 and a job_ ID, then writes the answer in the background, usually within a minute. Collect it with GET /v1/jobs/{job_id}, where status moves from queued to running to done or failed, or let Pearl push the result to your server through a webhook. Background answers combine with threads and JSON output, but not with streaming.
Verify Webhook Signatures
Each webhook is a POST with a Pearl-Event, Pearl-Delivery and Pearl-Signature header. The signature is an HMAC-SHA256 of the timestamp, a dot and the raw body, made with your signing secret. Compare it yourself and reject anything older than five minutes. Treat a repeated Pearl-Delivery ID as a retry and handle it once.
// Node.js (Express)
const crypto = require("crypto");
app.post("/pearl-events", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Pearl-Signature") || "";
const t = (header.match(/t=(\d+)/) || [])[1] || "";
const v1 = (header.match(/v1=([a-f0-9]+)/) || [])[1] || "";
const expected = crypto.createHmac("sha256", process.env.PEARL_WEBHOOK_SECRET)
.update(t + "." + req.body).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
const ok = v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
if (!fresh || !ok) return res.status(401).end();
const event = JSON.parse(req.body); // event.type, event.response
res.status(200).end(); // answer within 10 seconds
});
Respond with any 2xx status within ten seconds. If your server fails to answer, Pearl retries after one minute, five minutes, thirty minutes, two hours and six hours, then stops. The Webhook panel lists recent events with their result and the next attempt.
Give Assistants Tools and MCP Servers
Tools let an assistant look things up and take actions in your own systems while it answers, for example checking an order’s status or creating a booking. You can add your own web address as a tool or connect an MCP server. For tools that change something, switch on Ask before acting, so the assistant requests the user’s confirmation first. Every tool call is logged, and the answer lists the tools it used.
Pearl AI API Integration Best Practices
• Protect keys like passwords. Store them in a secrets manager, scope them to specific assistants and IP addresses, and rotate them if you suspect exposure.
• Route through your server. Browser and mobile code should call your backend, never Pearl AI directly.
• Start with the mini model. Use pearl-4-mini by default and reserve pearl-4 for questions that need deeper reasoning.
• Write narrow assistants. One assistant per job keeps instructions short, answers focused and credit use lower.
• Use test sets. Save representative questions and re-run them after every instructions change to catch regressions.
• Plan for retries. Handle 429 and 5xx responses with exponential backoff, and make webhook handlers idempotent.
• Show friendly messages. When credits run out, tell users the feature is temporarily unavailable rather than showing a technical error.
• Cap spending. Set a monthly cap, low-balance alerts and auto top-up before you launch, not after the first surprise.
Common Pearl AI API Integration Mistakes and How to Avoid Them
Most failed first attempts come from a handful of avoidable slips. Check this list before you open a support request.
• Sending the assistant ID as the key. The asst_ ID belongs in the URL and the pai_ key belongs in the Authorisation header. The API replies that the key is missing or invalid.
• Calling from the browser. Placing the key in front-end code exposes it. Move the call to a server route and return only the answer.
• Ignoring key limits. A key restricted by IP address will return a 401 from any other network, including your laptop on a different connection.
• Forgetting variables. If an assistant’s instructions contain {{plan}} and your request omits it, the call is refused with a message naming the variable.
• Combining async with streaming. Background answers work with threads and JSON output, but not with streaming. Pick one delivery style per request.
• Treating webhooks as exactly-once. Deliveries can be retried, so store the Pearl-Delivery ID and skip repeats.
Test Before You Launch
Use the Try it panel on each assistant to run the same instructions, variables, knowledge and tools your app will use. Each answer shows which knowledge and tools it drew on, its size and its cost, and Show as API request gives you the matching call to paste into your code. Then save ten to twenty real customer questions as a test set and re-run it after every change. That small habit catches most regressions before your users do.
Errors, Rate Limits and Credits
Each API key can make up to 60 requests a minute. Going over returns a clear error you can retry, never a silent failure. Usage is billed from a prepaid credit balance that you can top up from $5 to $2,000, and every new plan includes credits worth 10% of its price. If credits reach zero, requests are declined until you add more.
Code | Meaning | What to do |
401 | API key missing, revoked, expired or sent from a disallowed IP | Check the header, the key status and the key IP limits |
402 | Credit balance has run out | Top up in Subscriptions, then retry |
422 | Invalid request, such as an unknown model or missing variable | Read the message, fix the request and resend |
429 | More than 60 requests a minute on one key | Wait briefly and retry with backoff |
404 | Assistant, thread or job not found on your account | Check the ID and the account that created it |
5xx | Temporary problem on the platform | Retry shortly and check the status page |
Pearl AI Integration Use Cases
These patterns show where Pearl AI integration tends to pay off. They are illustrative designs built from the documented features, not customer results.
• Support ticket triage. Classify incoming tickets into intent, order ID and urgency with a JSON schema, then route them in your helpdesk.
• Personalised customer replies. Use variables such as customer name and plan so one assistant drafts replies that fit each account.
• In-product help. Embed an assistant trained on your documentation inside a CRM, ERP or customer portal, with threads to keep context.
• Order and booking lookups. Connect tools so the assistant checks status and asks before it changes anything.
• Reports and summaries. Run long summarisation jobs in the background and receive the result by webhook.
• Internal knowledge helpers. Give staff an assistant that answers from policy documents and your own website pages.
Pearl AI API Compared With Other Routes
Choosing an AI route is a trade-off between speed, control and effort. Building directly on a general model provider gives maximum flexibility, but your team must assemble assistants, knowledge, version history, webhooks and billing controls itself. The Pearl AI API packages those pieces behind one key, which suits teams that want to ship a working feature quickly and keep a small surface to maintain.
If you only need a customer-facing chatbot on a website, the Pearl AI Chat widget may be faster still, because it needs no code beyond a script tag. And if you land on another product that shares the Pearl name, such as an expert-verified answers service, remember that its endpoints, keys and pricing are unrelated to this one. The base address, key prefix and documentation domain are the quickest ways to confirm which service you are reading about.
Pearl AI API Pricing
Pearl AI starts at $50 a month plus usage, with the first assistant included. The 12-month plan costs $480, which is 20% less than paying monthly, and includes two assistants. Extra assistants cost $20 each, up to 50 more, and stay active until your plan’s current end date. Plans renew automatically, there is no minimum term on monthly billing, and you can turn auto-renew off at any time.
Usage credits are separate for each product and are never shared. Because every response shows the credits used and the credits left, you can estimate cost per conversation during testing and set a spending cap before launch.
About Pearl Organisation
Pearl Organisation has built software since 2017 from its base in Dehradun, India, and today serves more than 11,600 businesses across 150+ countries with over 21,000 projects delivered. That history shaped the Pearl AI API. Pearl Organisation states that Pearl Products run on the same production systems it uses in its own operations, and it has now made them available for other teams to build on.
For teams that want help beyond the API, Pearl Organisation also offers AI integration and agent development and API development and management services, so the same partner can design the architecture, connect your CRM or ERP and support the rollout.
Frequently Asked Questions About the Pearl AI API
What is the Pearl AI API? The Pearl AI API is a hosted AI service from Pearl Organisation that you call over REST. You send messages and receive an AI reply, with a usage summary showing credits consumed.
Where can I find the Pearl AI API documentation? The Pearl AI API documentation is at products.pearlorganisation.com/docs. It covers authentication, your first request, endpoints, assistants, webhooks, credits and errors.
How do I integrate Pearl AI into applications? Create an account, generate an API key, and send a POST request to the chat completions endpoint from your server with the key in the Authorisation header. Then add assistants, streaming, or webhooks as your needs grow.
Is there a Pearl AI Chat API? Yes. The chat-completions endpoints, including each assistant’s own endpoint, are the engine behind Pearl AI Chat. If you prefer no code, the Pearl AI Chat widget installs with one script tag.
Can I build a chatbot with the Pearl AI chatbot API? Yes. Create an assistant with instructions, knowledge and tools, call its endpoint with streaming and threads, and build your own chat interface on top.
Which models does the Pearl AI API support? Two models share one key: pearl-4-mini, the fast, low-cost default, and pearl-4, which offers higher accuracy and reasoning.
Is the Pearl AI API secure? Pearl Organisation states that it uses TLS 1.3, encryption at rest and hashed API keys, with per-account isolation. Keys can be limited by assistant, IP address and end date, and webhooks are signed.
How much does the Pearl AI API cost? Plans start at $50 a month plus usage credits, or $480 for 12 months. Extra assistants cost $20 each, and you can top up credits from $5 to $2,000.
Conclusion: Start Small, Then Scale Your Pearl AI Integration
The Pearl AI API gives developers a direct, self-serve route to production AI: two models, reusable assistants, streaming, JSON output, threads, background jobs and signed webhooks, all behind one key and one billing view. The path is short. Try the playground, create a key, make your first server-side call, then add an assistant and a webhook when the use case demands it.
Ready to build? Open the Pearl AI API documentation, test in the playground, or explore the full range of Pearl Products at products.pearlorganisation.com. If you want an experienced team to plan or deliver the integration, contact Pearl Organisation through pearlorganisation.com.
150+
250+
21,000+
11,600+