# API reference

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

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](#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](/docs/rules).

```sh
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.

1. `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).
2. Show the owner `verification_uri_complete`. They sign in and approve the code.
3. `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.

Source: https://tryostia.com/docs/api