API reference

The public endpoints store owners and developers use: token API, store key API, install check, audit and the device-code approval flow.

View as markdown llms.txt

Two hosts, three kinds of credentials. Every answer is JSON unless noted. Errors are { "ok": false, "error": "<one plain sentence>" }.

Credential	Where you get it	Used for
API token `agt_...`	the device-code approval with `client: "mcp"`	read stores, visits and rules on `https://tryostia.com/api/v1`
Store key	shown once when a store is added	server-side store API on `https://api.tryostia.com/api/store`
Session	signing in on the site	the browser app (`/app`, `/api/me`)

API tokens are read-only unless created with write access. Keep tokens and keys in environment variables or a secret store, never in code you commit.

Token API

Base: https://tryostia.com. Header: Authorization: Bearer agt_.... 60 requests a minute per IP.

Method and path	Answer
`GET /api/v1/stores`	`{ stores: [{ id, domain, platform }] }`
`GET /api/v1/stores/{id}/overview`	visits for the last 30 days and the 30 before: `totals` (`last7`, `prev7`, `last30`, `prev30`, `daily`), `vendors[]` with `agents[]`, and `pages[]`
`GET /api/v1/stores/{id}/rules`	`{ rules: [{ id, vendor, name, action, testing, updatedAt }] }`
`PUT /api/v1/stores/{id}/rules`	body `{ rules: { "<agent id>": "allow" or "block" } }`, write tokens only
`GET /api/v1/stores/{id}/report`	weekly report settings `{ enabled, recipients }`
`GET /api/v1/stores/{id}/install`	`{ siteId, domain, platform, seen, lastSeenAt }`

Agent IDs are listed on block/allow rules.

curl -H "Authorization: Bearer $TOKEN" https://tryostia.com/api/v1/stores

Store key API

Base: https://api.tryostia.com. Header: Authorization: Bearer <store key>. Ranges go up to 93 days.

Method and path	Answer
`GET /api/store/summary?from=&to=`	visits, orders, revenue and contact attempts for the range
`GET /api/store/export.csv?table=daily or assistants or orders&from=&to=`	CSV
`GET /api/store/destinations`	webhooks, Slack and GA4 destinations
`POST /api/store/destinations`	add one: `{ kind: "webhook" or "slack", url }` or `{ kind: "ga4", measurement_id, api_secret, region? }`. A webhook's `signingSecret` is in this answer only
`PATCH /api/store/destinations/{id}`	`{ active?, events?, summary? }`
`DELETE /api/store/destinations/{id}`	204
`POST /api/store/destinations/{id}/test`	sends a test event
`GET /api/store/destinations/{id}/deliveries`	the newest 50 deliveries
`POST /v1/attribution/orders`	report an order from your own backend: `{ order_id, total, currency, operator, agent_class, visitor_type, agent_code, arm }`. 204 new, 200 duplicate

No credential

Method and path	Answer
`GET https://tryostia.com/api/install-check?url=`	`{ ok, seen }`: has this store sent a visit in the last 7 days. 10 a minute per IP
`GET https://tryostia.com/api/audit?url=`	the free audit as JSON: `score`, `grade`, `summary`, `sections`, `fixes`. Can take up to a minute
`GET https://tryostia.com/audit?url=`	the same audit as a page

Device-code approval

Lets your own tool add a store or get an API token, with the owner approving in the browser. No password or cookie passes through your tool.

POST https://tryostia.com/api/cli/start with { "client": "cli", "url": "https://shop.example.com" } (or { "client": "mcp", "scope": "read" }). The answer has device_code, user_code, verification_uri_complete, interval (seconds) and expires_in (600).
Show the owner verification_uri_complete. They sign in and approve the code.
POST https://tryostia.com/api/cli/poll with { "device_code": "..." } every interval seconds. The answer is { status: "pending" } until it is approved (with store, snippet and, for a new store, key; or token and scope for MCP), denied or expired. The approved answer is given once.

Session endpoints (browser)

GET /api/me, GET|POST /api/me/stores, GET|PUT /api/app/stores/{id}/... and GET|POST|DELETE /api/tokens are used by the site itself with the sign-in cookie. POSTs must come from the site's own origin.