API Docs
This page has two parts: publicly readable addresses (no key required; search engines and AI retrievers read them directly) and the skill channel for connecting AI Agents (requires a site token, for Agents such as WorkBuddy to read and write to this site).
1. Public addresses: no key required
| Address | Purpose | Parameters | Verified status |
|---|---|---|---|
| /sitemap.xml | Index of all public pages on the site | None | 200 |
| /robots.txt | Crawling rules | None | 200 |
| /llms.txt | Site description and public address directory for AI retrievers | None | 200 |
| /api/geo/v1/capabilities | Declares the readable fields and public address list of this site | None | 200 |
| /capi/geo/list | Lists public content (products / categories / pages / articles) | type, page, pageSize, updated_since | 200 |
| /capi/geo/product/info | Public knowledge view of a single product | handle | 200 |
| /capi/geo/entity/info | Public view of entity knowledge such as pages | entity_type, entity_id | 200 |
All return { code, message, data }; code 200 indicates success. Only public content is returned: products that are live, and pages and articles that are published.
2. Connecting an AI Agent (skill channel)
In short: API address + site token; enter these two values into the Agent and it works.The token is equivalent to admin permissions on this site. Put it only in the request header; do not put it in the URL and do not commit it to a code repository.
1. Get the two values
- Log in to the admin panel and open the "AI Connection" page in the left navigation.
- The page has two lines: API address (fixed on this site as /api/skill; the full address is https://your-domain/api/skill) and access token (starts with sk_).
- Click the copy button on the right; you can also click "Copy integration instructions" to hand the address, authentication, and API discovery method to the Agent in one go.
Resetting the token invalidates the old token immediately. Agents already in use must be updated accordingly, otherwise all calls will return 401.
2. How authentication works
All skill APIs recognize only one request header: X-Site-Token: your token.Putting the token in URL parameters is not supported—URLs end up in access logs, Referer headers, and browser history, which effectively exposes admin permissions.
A minimal call (replace the domain and token with your own):
curl -s https://your-domain/api/skill/capabilities \
-H "X-Site-Token: sk_your-token"
3. First ask "what can you do", then call specific APIs
Do not start by guessing API names. Two self-service APIs are always available, and the Agent uses them to discover capabilities on its own:
- GET /api/skill/capabilities — full capability list: API paths, methods, read/write types, parameter descriptions, plus this site's authentication method and version number.
- GET /api/skill/base/init — basic site information: site type (B2B / B2C), current theme, available themes, language, and currency.
The remaining APIs are organized by module. Common ones include: /api/skill/product/list (products), /api/skill/plugin/list (plugins), /api/skill/i18n/list (multilingual entries), /api/skill/analytics/traffic-get (traffic), /api/skill/b2c-order/list (orders, B2C sites).
4. Permission matrix: all enabled by default, can be tightened per module
The admin panel's "API Permissions" has two modes: Allow all (default, same behavior as when activated) and Restrict by module (per-module toggles for read / write / dangerous operations).
| Category | Meaning | Recommendation |
|---|---|---|
| Read-only | Query products, content, traffic, plugin status | Enabled by default |
| Write | Add or modify products, content, storefront design | Enable when the Agent handles operations on your behalf |
| Dangerous | Delete, site-wide overwrite, publishing operations | Enable only when clearly needed |
The two read-only APIs "capabilities" and "base/init" are always allowed and are not affected by the permission table—otherwise the Agent could not even find out "why it cannot connect". Changes take effect immediately after saving; no configuration change is needed on the Agent side. Blocked APIs return 403 with the reason.
5. Test record (2026-10-19, tested once on each of two customer sites)
Each site's own real token was used to call each API one by one. Results are as follows (unembellished, exactly what was returned at the time):
| API | B2B site | B2C site |
|---|---|---|
| GET /api/skill/capabilities | 200 / 46,063 B | 200 / 45,842 B |
| GET /api/skill/base/init | 200 / 644 B | 200 / 664 B |
| GET /api/skill/product/list?limit=2 | 200 / 25,534 B | 200 / 5,417 B |
| GET /api/skill/analytics/traffic-get | 200 / 3,424 B | 200 / 2,913 B |
| GET /api/skill/plugin/list | 200 / 15,673 B | 200 / 14,681 B |
| GET /api/skill/i18n/list | 200 / 5,275 B | 200 / 5,275 B |
| Same as above, without token | 401 / 68 B | 401 / 68 B |
Conclusion: the channel works on both sites, authentication is in effect, and requests without a token are rejected (returning "Unauthorized: X-Site-Token missing or mismatched"). The size differences reflect data volume differences, not failures.
6. Error codes and handling
| Status | Meaning | How to handle |
|---|---|---|
| 401 | Token missing or mismatched | Check whether the request header name is X-Site-Token; check whether the token has been reset |
| 403 | Blocked by the permission matrix | Check the reason in the response; enable the corresponding module under "API Permissions" in the admin panel |
| 404 | Path does not exist | Use capabilities to verify the API name first; do not piece it together from memory |
| 503 | Site token not configured on the server | Open the "AI Connection" page in the admin panel once; the system will generate it automatically |
7. Three security baselines
- Do not put the token in a URL, and do not paste it into a chat window or commit it to a code repository—it is equivalent to an admin login session.
- Grant only the necessary permissions: for daily operations, read-only + write is sufficient; enable dangerous categories temporarily only when needed.
- Reset the token when changing personnel or handing over; the old token becomes invalid immediately, which is more reliable than revoking individually.
3. Minimum steps to connect WorkBuddy
- In the admin panel, go to "AI Connection" → copy the API address and access token (or copy the entire integration instructions directly).
- In WorkBuddy's connector / skill configuration, enter the site address and use X-Site-Token for authentication.
- Have the Agent call capabilities first for self-description, then call specific APIs according to the list.