AI Agent API
A read-only ticket API for AI agents
The AI Agent API is a token-authenticated REST API that lets an external AI agent — the chatbot or support assistant you already run — read your TicketFlow tickets: find a customer's ticket by email, order number or phone, and read its notes and stage. It is strictly read-only: it reads, it never writes.
+€9/month • Requires TicketFlow (free on every plan)
What it is — and what it isn't
What it does
- Gives your AI agent structured ticket context through four GET endpoints
- Finds a customer's ticket by email, order number or full phone number
- Returns stage, status, customer name and the most recent notes with their authors
- Explains your own stages to the model, using the descriptions you wrote
What it doesn't do
- It writes nothing: no replying to customers, no adding notes, no stage changes, no closing tickets
- It exposes no orders, products, stock, returns or sales — tickets only
- It can't browse the queue: it always needs a specific customer identifier
- It sends no webhooks — the agent asks, it isn't notified
Endpoints
Base URL: https://{your-store}.retailpilot.io/api/v1/agent — every endpoint is a GET.
/whoamiToken identity: name, abilities, and the website ids it is scoped to (null means all of them). Useful as a connection check.
/ticket-statusesYour glossary: statuses (open/closed) and the list of your stages with their descriptions, so the model understands what each custom stage means.
/tickets/searchLook up by email, order_id or phone (optionally status=open|closed). order_id accepts the #-prefixed form, and phone ignores spaces and prefixes as long as you pass a full number. Paginated with page and per_page (default 20, max 25).
/tickets/{id}A single ticket by its opaque id: customer name, latest notes with authors, and the total note count.
Example call
Request
curl -H "Authorization: Bearer agent_xxxxxxxx" \
"https://your-store.retailpilot.io/api/v1/agent/tickets/search?order_id=1042"Response
{
"results": [
{
"id": "01J9F2K7X3QH4VB8ZC1M6PWT0A",
"subject": "Λάθος μέγεθος στην παραγγελία",
"order_number": "1042",
"status": "open",
"stage": "In Progress",
"updated_at": "2026-07-24T09:12:44+00:00"
}
],
"meta": {
"current_page": 1,
"per_page": 20,
"total": 1,
"last_page": 1
}
}Ticket detail
{
"id": "01J9F2K7X3QH4VB8ZC1M6PWT0A",
"subject": "Λάθος μέγεθος στην παραγγελία",
"order_number": "1042",
"status": "open",
"stage": "In Progress",
"customer_name": "Μαρία Π.",
"notes": [
{
"summary": "Ο πελάτης ζήτησε αλλαγή σε M. Στάλθηκε κουπόνι πίστωσης...",
"author": "Γιώργος",
"at": "2026-07-24T09:12:44+00:00"
}
],
"notes_total": 4,
"updated_at": "2026-07-24T09:12:44+00:00"
}Authentication & security
- Tokens you mint yourself
- Create named tokens from the panel (admins only). The token is shown once and stored hashed — deactivate or delete it at any time.
- Per-storefront scoping
- If you connect several WooCommerce sites, each token can be limited to specific ones — the other tickets simply don't exist for it.
- Anti-enumeration by design
- Tickets carry opaque identifiers (never sequential numbers) and search requires an exact email, order number or full 10-digit phone. Nobody can walk your customer base.
- Rate limits
- 60 requests per minute per token — exceeding it returns a 429 whose body carries retry_after in seconds. A coarser 120-requests-per-minute limit also applies per IP, so mind it if you run several tokens from one server.
- Full access log
- Every search and every ticket read is logged with timestamp, IP and result count — visible inside the panel, per token. Entries are kept for 90 days by default.
Technical limits
- Server-to-server: no CORS headers are sent, so call it from your backend, not the browser.
- Notes come back summarised: the 5 most recent, truncated to 200 characters, plus the total count.
- The payload carries the customer's name — not their email or phone.
- Tokens don't expire automatically; revocation is manual.
- Requires TicketFlow to be active. Turn it off and the API stops.
Pricing
The AI Agent API is +€9/month on any RetailPilot plan, and it's included in RetailPilot Complete (€119/month). It requires TicketFlow, which is free on every plan.
Frequently asked questions
- Can the AI agent reply to the customer through this API?
- No. The API is strictly read-only — it creates no tickets, adds no comments and changes no statuses. It gives your agent the context to answer wherever it already talks to the customer (chat, email, whichever channel you run).
- What data does the AI agent see?
- Tickets only: subject, status, stage, order number, customer name and the most recent notes with their authors. It sees no orders, products, stock, returns or sales.
- How is bulk customer-data extraction prevented?
- Search always requires a strong identifier — an exact email, an order number, or a full 10-digit phone; filtering by status alone is rejected. Tickets use opaque identifiers so nobody can iterate through them.
- What are the rate limits?
- 60 requests per minute per token. Exceeding that returns a 429 with a retry-after hint.
- Does it support webhooks or MCP?
- Not at the moment. Your agent queries whenever it needs to; there are no outbound notifications and no MCP server yet.
- Do I need TicketFlow?
- Yes. The AI Agent API reads TicketFlow data, and TicketFlow is included free with every RetailPilot plan.
Connect your AI agent to your tickets
14-day free trial, no credit card required. Cancel anytime.