AI agents
Guidance for safely connecting AI agents to the Klu POS Public API.
AI agents can use the Public API to answer read-only business questions without dashboard access.
Good agent tasks include:
- "What was revenue this week compared to last week?"
- "Which products sold the most this month?"
- "Which staff member generated the most revenue?"
- "Who gave customers the biggest discounts?"
- "Who are the top customer spenders this month?"
- "Which branches have low stock?"
- "Show sales paid by PromptPay yesterday."
- "Build a server-side dashboard from Klu POS data."
Recommended system instruction
Use a private server-side tool for Klu POS requests. Never reveal the API key to the user, never put it in browser code, and never include it in logs or final answers. Use only GET requests under /public-api/v1. Start with /me to validate the key, use /stores to discover branch IDs, apply date ranges for sales and analytics, and respect 429 retry headers.
Safe request pattern
- Call
GET /meto confirm the key and organization. - Call
GET /storesand cache branch IDs. - Use analytics endpoints for totals and trends.
- Use list endpoints for drill-down.
- Follow
pagination.nextCursoruntil enough data is collected.
Data minimization
Ask only for the data needed to answer the user. Prefer analytics endpoints when a summary is enough.
Do not request or infer hidden private data. The Public API exposes only current per-store average cost for stock valuation; it intentionally omits historical and supplier cost details, calculated profit, customer PII, staff private fields, notes, and internal file metadata.
For staff questions, prefer GET /analytics/staff for ranking and /staff/:id/shifts only for observed clock-in/out history. For customer ranking, prefer GET /analytics/customers; use GET /customers/:id only for safe profile drill-down.
Failure handling
401: stop and ask a human to check or rotate the key.403: remove the disallowed ID and use IDs returned by this key.429: wait until the retry window before calling again.404: tell the user the object was not found in the connected organization.