Overview
The Minimal AI Agent uses workflows to connect to your systems. Because workflows are fully flexible, we can work with virtually any API structure — there are no strict requirements on format, naming, or endpoints. This guide provides ideas for what to expose and technical guidelines for delivery. Before building custom endpoints, check whether your platform is already covered by our standard integrations.What Data & Actions to Expose
Below are common categories of endpoints our customers provide. Pick what’s relevant to your use case — you don’t need all of them.Order Data
Let the AI agent look up orders so it can answer questions like “Where is my order?” or “Can I still cancel?” Direct lookup endpoint — a single endpoint that accepts query parameters:| Field | Example |
|---|---|
| Order number | ORD123456 |
| Order status | shipped, processing, delivered |
| Line items | Product ID/SKU, name, quantity, price |
| Payment status | paid, pending, refunded |
| Tracking URL | https://tracking.postnl.nl/... |
| Shipping address | Street, city, postal code, country |
| Return status | true / false |
| Created at | 2025-08-01T10:00:00Z |
Product Information
The agent needs product data to answer questions about pricing, availability, and specifications.Option A: Product feed (recommended for large catalogs)
Option A: Product feed (recommended for large catalogs)
Provide a feed URL (e.g. a Channable, Google Shopping, or custom XML/JSON export). We sync this periodically so the agent always has up-to-date product knowledge.This works well for relatively static data like product descriptions, images, and categories.
Option B: Real-time product endpoint (recommended for stock & pricing)
Option B: Real-time product endpoint (recommended for stock & pricing)
For data that changes frequently (stock levels, pricing), a real-time endpoint works better:Useful fields to return: product ID, name, price, stock availability, description, variant info
Use consistent product IDs / SKUs across your order data, feeds, and product endpoints.
Other Examples
Customer profile — name, email, language, account creation date, and linked pet profiles. Useful as the starting point of every conversation. Loyalty & vouchers — outstanding balance, available discount codes, or referral credits. Customers ask about these regularly. Communication preferences — newsletter subscription, language preference, and notification settings. Allows the agent to update preferences without manual intervention. Payment information — active payment method, billing address, and outstanding payments. Useful for questions about failed payments or updating a payment method. Inventory / WMS — real-time stock levels per product or SKU, and the fulfillment status of a specific order within the pick/pack/ship process. Useful when delays are not yet visible in the order status. Marketing platform — which email campaigns or discount promotions a customer has received. Prevents confusion when a customer asks about an offer they saw in their inbox. Return portal — whether a return request has been created, the current status, and whether a return label has been sent. Particularly relevant for Just Russel given the sensitive return policy around personalized products.Actions
With workflows, the agent can perform actions on behalf of the customer. These are entirely optional — expose only what you want the agent to be able to do. Common examples:| Action | Example Endpoint |
|---|---|
| Generate a return label | POST /api/orders/{order_number}/return-label |
| Cancel an order | POST /api/orders/{order_number}/cancel |
| Update shipping address | PUT /api/orders/{order_number}/address |
| Request a refund | POST /api/orders/{order_number}/refund |
| Newsletter preferences | POST /api/customers/{id}/preferences |
Technical Requirements
Response Format
We work with any response format, but JSON is preferred. XML and CSV feeds are also supported for product data.Authentication
All endpoints must be protected. We support:| Method | Details |
|---|---|
| Bearer token | Send us a static API key; we include it as Authorization: Bearer <token> |
| Basic auth | Provide a username and password |
| API key header | Custom header (e.g. X-API-Key: <key>) |
| IP whitelisting | We can provide a static IP to whitelist (ask us) |
Environments
If you have a staging or test environment, share that alongside production so we can validate the integration without affecting live data.Rate Limits
Let us know if your API has rate limits so we can configure our workflows accordingly. For most use cases, request volume is low — each request is triggered by an individual customer conversation.Security Best Practices
Require Multiple Matching Parameters
For endpoints that return or modify sensitive customer data, we strongly recommend requiring multiple identifying parameters to match before returning a result. This prevents unauthorized access even if a single identifier is guessed or leaked. Example: require both order number AND email404 or 403.
Recommended combinations:
- Order number + email address
- Customer ID + email address
Scope Permissions
If your API supports scoped tokens or permissions, issue a token with the minimum required access:- Read-only for data retrieval endpoints
- Write access only for specific actions you want the agent to perform