Tools reference
The complete surface, in one table. Every tool is read-only and free to call. Explanations of what each is for are in the tool guide.
All tools
| Tool | Parameters | Answers |
|---|---|---|
get_setup_health | — | Can the gift widget appear on this store? |
get_campaigns | status? | What offers am I running? |
get_campaign_details | campaignId | How is this one campaign configured? |
get_analytics | days? includeToday? ianaTimezone? | Revenue, orders, conversion, AOV |
check_gift_product | handles | Can this product be given as a gift? |
get_widget_types | — | Which widget types does this store have? |
get_widget_settings | type | How is one widget configured to look? |
get_translations | locale? | What wording do shoppers see? |
get_app_settings | — | The store-wide switches |
get_plan_status | — | Plan, quota, usage |
Parameters marked ? are optional; the rest are required.
The same data over REST
Free Gift serves this data on two surfaces that share one set of handlers. Whatever a tool returns, its matching endpoint returns — a change to either lands on both.
| Tool | REST endpoint |
|---|---|
get_setup_health | GET /setup-health |
get_campaigns | GET /campaigns |
get_campaign_details | GET /campaigns/{id} |
get_analytics | GET /analytics |
check_gift_product | GET /products |
get_widget_types | GET /widgets |
get_widget_settings | GET /widgets/{type} |
get_translations | GET /translations |
get_app_settings | GET /settings |
get_plan_status | GET /plan |
The Store API lives at /store-api/v1, takes its own key beginning aov_sk_, and is
meant for scripts and integrations rather than AI clients. Keys are not interchangeable between the
two — see Authentication.
Limits
| Requests | 60 per minute, per connection |
| Result size | About 16,000 characters per call |
| Campaign list | 100 campaigns |
| Product lookup | 50 handles per call |
| Long strings | Trimmed at 160 characters |
A result that hits the size limit is cut off with a note saying so, and suggesting a narrower request. That note is real information: an assistant that ignores it will summarise a partial answer as though it were complete. Asking for one campaign, one widget type, or one language brings the result back under the limit.
What is deliberately absent
- No write tools. Not restricted — not implemented. Nothing an assistant calls can change a campaign, a widget, a setting, or a plan.
- No customer data. No names, emails, addresses, or individual orders anywhere in the surface.
- No internal identifiers. The store's own record ids and access token are stripped before anything leaves the server.
- No pricing.
get_plan_statusreports your store's plan and usage, never a price list.