AI Agent API
A read-only ticket API for AI support agents
The AI Agent API is a read-only REST API: your AI support agent finds a customer's TicketFlow ticket by email, order number or phone. The chatbot or support assistant you already run reads the ticket's stage and latest notes, and never writes anything back.
+€9/month • Requires TicketFlow (free on every plan) • Free trial by invitation
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
How an AI support agent uses it
- 1
An admin creates a named token in the panel. It's shown once and stored only as a hash.
- 2
Your agent checks the connection with GET /whoami.
- 3
When a customer gets in touch, the agent looks up their ticket with GET /tickets/search, by email, order_id or full phone number.
- 4
It reads the stage, status and latest notes, then replies wherever it's already talking to the customer. Nothing is written back to TicketFlow.
Endpoints
Base URL: https://{your-store}.retailpilot.io/api/v1/agent — every endpoint is a GET.
/whoami Token identity: name, abilities, and the website ids it is scoped to (null means all of them). Useful as a connection check.
/ticket-statuses Your glossary: statuses (open/closed) and the list of your stages with their descriptions, so the model understands what each custom stage means.
/tickets/search Look 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": "Wrong size in the order",
"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": "Wrong size in the order",
"order_number": "1042",
"status": "open",
"stage": "In Progress",
"customer_name": "Maria P.",
"notes": [
{
"summary": "The customer asked to swap for size M. Store-credit coupon sent...",
"author": "George",
"at": "2026-07-24T09:12:44+00:00"
}
],
"notes_total": 4,
"updated_at": "2026-07-24T09:12:44+00:00"
} Stage names come back exactly as you named them in TicketFlow, Greek names included; /ticket-statuses gives your agent the description you wrote for each stage.
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; TicketFlow can't be switched off while the API is on.
Pricing
The AI Agent API is +€9/month on any RetailPilot plan. 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.
- Does it return the customer's email or phone?
- No. The payload carries the customer's name only, never their email or phone number.
- How does my agent call it?
- From your server, with a bearer token in the Authorization header. No CORS headers are sent, so call it from your backend, not from a browser.
- How do I create a token?
- From the panel, as an admin. Each token has a name, is shown once and is stored only as a hash (SHA-256). You can deactivate or delete it at any time.
- 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; above that you get a 429 whose body carries retry_after in seconds. A coarser limit of 120 requests per minute also applies per IP.
- 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.
- How much does it cost?
- +€9/month on any RetailPilot plan. It requires TicketFlow, which is free on every plan.
Connect your AI agent to your tickets
14-day free trial, no credit card required. Cancel anytime.