{"openapi":"3.1.0","info":{"title":"UsherStats API","version":"1","description":"Human-only web analytics, crawler and AI-bot insight, and bot protection. No cookies. Every response that is not 2xx is application/problem+json. Scopes: analytics:read, sites:read, sites:write, bot:read, bot:write, search:read, search:write, members:read, members:write, tokens:read, tokens:write, billing:read, billing:write, export:read, account:admin. Docs: https://docs.usherstats.com","contact":{"email":"support@usherstats.com"}},"servers":[{"url":"https://api.usherstats.com"}],"tags":[{"name":"auth"},{"name":"me"},{"name":"members"},{"name":"tokens"},{"name":"sites"},{"name":"analytics"},{"name":"goals"},{"name":"bot"},{"name":"search"},{"name":"internal"},{"name":"export"},{"name":"billing"},{"name":"meta"},{"name":"mcp"}],"paths":{"/v1/auth/signup":{"post":{"operationId":"postV1AuthSignup","tags":["auth"],"summary":"Create an account: a user, a workspace they own, and a verification email. Answers the same whether or not the email is taken.","description":"No credentials needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":10,"maxLength":1024,"description":"At least 10 characters; refused if it appears in a known breach"},"workspaceName":{"type":"string","minLength":1,"maxLength":80}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/verify":{"post":{"operationId":"postV1AuthVerify","tags":["auth"],"summary":"Confirm an email address with the token from the verification link (single use, 24 hours) and the password the account was signed up with. Starts no session; sign in afterwards. Five wrong passwords an hour per account.","description":"No credentials needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["token","password"],"properties":{"token":{"type":"string"},"password":{"type":"string","minLength":1,"maxLength":1024}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["verified"],"properties":{"verified":{"type":"boolean"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/verify/resend":{"post":{"operationId":"postV1AuthVerifyResend","tags":["auth"],"summary":"Send a new verification link to an unconfirmed account. Always 202.","description":"No credentials needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/login":{"post":{"operationId":"postV1AuthLogin","tags":["auth"],"summary":"Sign in with email and password. Sets the us_session cookie, or, with two-factor sign-in on, returns a challenge for /v1/auth/login/2fa. Repeated failures from one address slow that address down (the answer stays 401).","description":"No credentials needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1,"maxLength":1024}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["user","memberships"],"properties":{"user":{"type":"object","additionalProperties":false,"required":["id","email"],"properties":{"id":{"type":"string"},"email":{"type":"string"}}},"memberships":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["workspaceId","name","role","plan"],"properties":{"workspaceId":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]},"plan":{"type":"string"}}}}}},{"type":"object","additionalProperties":false,"required":["twoFactorRequired","challenge"],"properties":{"twoFactorRequired":{"type":"boolean","enum":[true]},"challenge":{"type":"string"}}}]}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/login/2fa":{"post":{"operationId":"postV1AuthLogin2fa","tags":["auth"],"summary":"Second sign-in step: the challenge from /v1/auth/login and the current authenticator code. Five guesses, five minutes.","description":"No credentials needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["challenge","code"],"properties":{"challenge":{"type":"string"},"code":{"type":"string","pattern":"^\\d{6}$"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["user","memberships"],"properties":{"user":{"type":"object","additionalProperties":false,"required":["id","email"],"properties":{"id":{"type":"string"},"email":{"type":"string"}}},"memberships":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["workspaceId","name","role","plan"],"properties":{"workspaceId":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]},"plan":{"type":"string"}}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/logout":{"post":{"operationId":"postV1AuthLogout","tags":["auth"],"summary":"End this session and clear the cookie.","description":"No credentials needed.","security":[],"responses":{"204":{"description":"Done; no body"},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/password/reset-request":{"post":{"operationId":"postV1AuthPasswordResetRequest","tags":["auth"],"summary":"Email a password-reset link (single use, 1 hour). Always 202.","description":"No credentials needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/password/reset":{"post":{"operationId":"postV1AuthPasswordReset","tags":["auth"],"summary":"Choose a new password with the token from the reset link. Signs out every session, revokes every API token you made, and clears sign-in throttling.","description":"No credentials needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["token","password"],"properties":{"token":{"type":"string"},"password":{"type":"string","minLength":10,"maxLength":1024}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reset"],"properties":{"reset":{"type":"boolean"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/password/change":{"post":{"operationId":"postV1AuthPasswordChange","tags":["auth"],"summary":"Change your password (needs the current one). Keeps this session and ends the others. Wrong current passwords are throttled after 3, and the fifth signs this session out.","description":"For a signed-in person (us_session cookie); API tokens are refused.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string","minLength":1,"maxLength":1024},"newPassword":{"type":"string","minLength":10,"maxLength":1024}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["changed"],"properties":{"changed":{"type":"boolean"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed for this caller","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/sessions":{"get":{"operationId":"getV1AuthSessions","tags":["auth"],"summary":"Your live sessions; `current` marks this one.","description":"For a signed-in person (us_session cookie); API tokens are refused.","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["sessions"],"properties":{"sessions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","createdAt","lastSeenAt","expiresAt","ip","userAgent","current"],"properties":{"id":{"type":"string"},"createdAt":{"type":"string"},"lastSeenAt":{"type":["string","null"]},"expiresAt":{"type":"string"},"ip":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"current":{"type":"boolean"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed for this caller","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/sessions/{id}":{"delete":{"operationId":"deleteV1AuthSessionsById","tags":["auth"],"summary":"Sign out one of your sessions.","description":"For a signed-in person (us_session cookie); API tokens are refused.","security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed for this caller","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/2fa/enroll":{"post":{"operationId":"postV1Auth2faEnroll","tags":["auth"],"summary":"Start two-factor sign-in: returns a TOTP secret and otpauth:// URI for an authenticator app. Not on until confirmed.","description":"For a signed-in person (us_session cookie); API tokens are refused.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["password"],"properties":{"password":{"type":"string","minLength":1,"maxLength":1024}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["secret","otpauthUri"],"properties":{"secret":{"type":"string"},"otpauthUri":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed for this caller","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/2fa/confirm":{"post":{"operationId":"postV1Auth2faConfirm","tags":["auth"],"summary":"Turn two-factor sign-in on with a current code from the enrolled authenticator.","description":"For a signed-in person (us_session cookie); API tokens are refused.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code"],"properties":{"code":{"type":"string","pattern":"^\\d{6}$"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed for this caller","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/2fa/disable":{"post":{"operationId":"postV1Auth2faDisable","tags":["auth"],"summary":"Turn two-factor sign-in off (needs your password and a current code).","description":"For a signed-in person (us_session cookie); API tokens are refused.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["password","code"],"properties":{"password":{"type":"string","minLength":1,"maxLength":1024},"code":{"type":"string","pattern":"^\\d{6}$"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed for this caller","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/me":{"get":{"operationId":"getV1Me","tags":["me"],"summary":"The caller: actor, workspace, role, scopes and site restriction (the AuthContext); for a person also their account and workspaces, for a token its name and expiry. A person selects a workspace with the X-Workspace header or ?workspace=.","description":"A signed-in person or an API token.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["actor","workspaceId","role","scopes","siteIds"],"properties":{"actor":{"type":"object","additionalProperties":false,"required":["type","id"],"properties":{"type":{"type":"string","enum":["user","token"]},"id":{"type":"string"}}},"workspaceId":{"type":["string","null"]},"role":{"type":["string","null"],"enum":["owner","admin","member","viewer",null]},"scopes":{"type":"array","items":{"type":"string"}},"siteIds":{"type":["array","null"],"items":{"type":"string"}},"user":{"type":"object","additionalProperties":false,"required":["id","email","emailVerified","twoFactor","createdAt"],"properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"twoFactor":{"type":"boolean"},"createdAt":{"type":"string"}}},"memberships":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["workspaceId","name","role","plan"],"properties":{"workspaceId":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]},"plan":{"type":"string"}}}},"token":{"type":"object","additionalProperties":false,"required":["id","name","expiresAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"expiresAt":{"type":["string","null"]}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/workspace":{"get":{"operationId":"getV1Workspace","tags":["members"],"summary":"The workspace: name, plan, the plan's limits (null = unlimited) and current usage (for a site-restricted token, its own sites and no member count).","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `members:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","name","plan","status","createdAt","limits","usage"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"limits":{"type":"object","additionalProperties":false,"required":["sites","members","proxyHostnames"],"properties":{"sites":{"type":["integer","null"]},"members":{"type":["integer","null"]},"proxyHostnames":{"type":["integer","null"]}}},"usage":{"type":"object","additionalProperties":false,"required":["sites","members"],"properties":{"sites":{"type":"integer"},"members":{"type":["integer","null"]}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the members:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["members:read"]},"patch":{"operationId":"patchV1Workspace","tags":["members"],"summary":"Rename the workspace.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `members:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","name","plan","status","createdAt","limits","usage"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"limits":{"type":"object","additionalProperties":false,"required":["sites","members","proxyHostnames"],"properties":{"sites":{"type":["integer","null"]},"members":{"type":["integer","null"]},"proxyHostnames":{"type":["integer","null"]}}},"usage":{"type":"object","additionalProperties":false,"required":["sites","members"],"properties":{"sites":{"type":"integer"},"members":{"type":["integer","null"]}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the members:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["members:write"]}},"/v1/members":{"get":{"operationId":"getV1Members","tags":["members"],"summary":"Members of the workspace and pending invitations.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `members:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["members","invites"],"properties":{"members":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["userId","email","role","twoFactor","joinedAt"],"properties":{"userId":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]},"twoFactor":{"type":"boolean"},"joinedAt":{"type":"string"}}}},"invites":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","email","role","createdAt","expiresAt"],"properties":{"id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the members:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["members:read"]}},"/v1/members/invites":{"post":{"operationId":"postV1MembersInvites","tags":["members"],"summary":"Invite someone by email (as admin, member or viewer). Counts against the plan's member limit while pending; expires in 7 days.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `members:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","role"],"properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","member","viewer"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["invite"],"properties":{"invite":{"type":"object","additionalProperties":false,"required":["id","email","role","createdAt","expiresAt"],"properties":{"id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the members:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["members:write"]}},"/v1/members/invites/{id}":{"delete":{"operationId":"deleteV1MembersInvitesById","tags":["members"],"summary":"Withdraw a pending invitation.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `members:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the members:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["members:write"]}},"/v1/invites/accept":{"post":{"operationId":"postV1InvitesAccept","tags":["members"],"summary":"Accept an invitation with the token from its link. You must be signed in with the invited email address.","description":"For a signed-in person (us_session cookie); API tokens are refused.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["workspaceId","role"],"properties":{"workspaceId":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not allowed for this caller","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/members/{userId}":{"patch":{"operationId":"patchV1MembersByUserId","tags":["members"],"summary":"Change a member's role. Only an owner makes or changes owners; the last owner cannot be demoted. Tokens the person made that exceed the new role are revoked.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `members:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["role"],"properties":{"role":{"type":"string","enum":["owner","admin","member","viewer"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["userId","email","role","twoFactor","joinedAt"],"properties":{"userId":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","viewer"]},"twoFactor":{"type":"boolean"},"joinedAt":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the members:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["members:write"]},"delete":{"operationId":"deleteV1MembersByUserId","tags":["members"],"summary":"Remove a member (members:write), or leave the workspace (your own user id, no scope needed). Revokes every token the person made here. The last owner cannot leave.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `members:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the members:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["members:write"]}},"/v1/tokens":{"get":{"operationId":"getV1Tokens","tags":["tokens"],"summary":"The workspace's live API tokens (by display prefix; the full token is never shown again).","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `tokens:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["tokens"],"properties":{"tokens":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","prefix","scopes","siteIds","createdBy","createdAt","expiresAt","lastUsedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"siteIds":{"type":["array","null"],"items":{"type":"string"}},"createdBy":{"type":"string"},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the tokens:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["tokens:read"]},"post":{"operationId":"postV1Tokens","tags":["tokens"],"summary":"Create an API token with the given scopes, optionally restricted to some sites and given an expiry. The token is in the response once; store it then.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `tokens:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","scopes"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"type":"array","maxItems":15,"items":{"type":"string","enum":["analytics:read","sites:read","sites:write","bot:read","bot:write","search:read","search:write","members:read","members:write","tokens:read","tokens:write","billing:read","billing:write","export:read","account:admin"]}},"siteIds":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"Omit for every site in the workspace"},"expiresAt":{"type":"string","format":"date-time","description":"Omit for no expiry"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","name","prefix","scopes","siteIds","createdBy","createdAt","expiresAt","lastUsedAt","token","shownOnce"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"siteIds":{"type":["array","null"],"items":{"type":"string"}},"createdBy":{"type":"string"},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]},"token":{"type":"string"},"shownOnce":{"type":"boolean"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the tokens:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["tokens:write"]}},"/v1/tokens/{id}":{"delete":{"operationId":"deleteV1TokensById","tags":["tokens"],"summary":"Revoke an API token, and every token it made (and theirs). They stop working at once. Only a caller holding every scope of the token can revoke it.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `tokens:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the tokens:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["tokens:write"]}},"/v1/sites":{"get":{"operationId":"getV1Sites","tags":["sites"],"summary":"Sites of the workspace (for a site-restricted token, only its sites).","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["sites"],"properties":{"sites":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","timezone","createdAt","hostnames","settings","lastSeenAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"},"createdAt":{"type":"string"},"hostnames":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}}},"settings":{"type":"object","additionalProperties":false,"properties":{"internalNetworks":{"type":"array","items":{"type":"string"}},"botWindows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"country":{"type":"string"},"network":{"type":"string"},"note":{"type":"string"}}}},"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","type","match"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}},"experiments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}},"bot":{"type":"object","additionalProperties":false,"required":["mode","bots","rules"],"properties":{"mode":{"type":"string"},"bots":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}}}}}},"lastSeenAt":{"type":["string","null"]}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]},"post":{"operationId":"postV1Sites","tags":["sites"],"summary":"Create a site with its hostnames. Returns the site and its first public key (pk_...). Counts against the plan's site limit.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"timezone":{"type":"string","description":"IANA time zone; days in reports start at midnight here"},"hostnames":{"type":"array","maxItems":50,"items":{"type":"string","format":"hostname"}}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","publicKey"],"properties":{"site":{"type":"object","additionalProperties":false,"required":["id","name","timezone","createdAt","hostnames","settings","lastSeenAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"},"createdAt":{"type":"string"},"hostnames":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}}},"settings":{"type":"object","additionalProperties":false,"properties":{"internalNetworks":{"type":"array","items":{"type":"string"}},"botWindows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"country":{"type":"string"},"network":{"type":"string"},"note":{"type":"string"}}}},"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","type","match"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}},"experiments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}},"bot":{"type":"object","additionalProperties":false,"required":["mode","bots","rules"],"properties":{"mode":{"type":"string"},"bots":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}}}}}},"lastSeenAt":{"type":["string","null"]}}},"publicKey":{"type":"object","additionalProperties":false,"required":["id","kind","value","prefix","createdAt","shownOnce"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["public","secret"]},"value":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string"},"shownOnce":{"type":"boolean"}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}":{"get":{"operationId":"getV1SitesById","tags":["sites"],"summary":"One site, with its hostnames and settings.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site"],"properties":{"site":{"type":"object","additionalProperties":false,"required":["id","name","timezone","createdAt","hostnames","settings","lastSeenAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"},"createdAt":{"type":"string"},"hostnames":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}}},"settings":{"type":"object","additionalProperties":false,"properties":{"internalNetworks":{"type":"array","items":{"type":"string"}},"botWindows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"country":{"type":"string"},"network":{"type":"string"},"note":{"type":"string"}}}},"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","type","match"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}},"experiments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}},"bot":{"type":"object","additionalProperties":false,"required":["mode","bots","rules"],"properties":{"mode":{"type":"string"},"bots":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}}}}}},"lastSeenAt":{"type":["string","null"]}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]},"patch":{"operationId":"patchV1SitesById","tags":["sites"],"summary":"Rename a site or change its time zone.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"timezone":{"type":"string","description":"IANA time zone; days in reports start at midnight here"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site"],"properties":{"site":{"type":"object","additionalProperties":false,"required":["id","name","timezone","createdAt","hostnames","settings","lastSeenAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"},"createdAt":{"type":"string"},"hostnames":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}}},"settings":{"type":"object","additionalProperties":false,"properties":{"internalNetworks":{"type":"array","items":{"type":"string"}},"botWindows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"country":{"type":"string"},"network":{"type":"string"},"note":{"type":"string"}}}},"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","type","match"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}},"experiments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}},"bot":{"type":"object","additionalProperties":false,"required":["mode","bots","rules"],"properties":{"mode":{"type":"string"},"bots":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}}}}}},"lastSeenAt":{"type":["string","null"]}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]},"delete":{"operationId":"deleteV1SitesById","tags":["sites"],"summary":"Delete a site. Its keys stop working at once and its proxy-mode hostnames are removed at Cloudflare; collected data stays in the archive.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/hostnames":{"post":{"operationId":"postV1SitesByIdHostnames","tags":["sites"],"summary":"Add a hostname the site is served on (collect accepts the public key only from these). With proxy: true and an origin, the hostname is served through UsherStats proxy mode: the answer lists the DNS records to set (a CNAME to the proxy; TXT records let it go live before the DNS moves). Proxy hostnames past the plan's allowance are billed on paid plans and refused (402) on Free.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["hostname"],"properties":{"hostname":{"type":"string","format":"hostname"},"proxy":{"type":"boolean","description":"Serve this hostname through proxy mode"},"origin":{"type":"string","minLength":1,"maxLength":300,"description":"Proxy mode: where requests are forwarded, such as https://origin.example.com"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["hostname"],"properties":{"hostname":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}},"proxy":{"type":"object","additionalProperties":false,"required":["id","hostname","status","sslStatus","active","cnameTarget","records","errors"],"properties":{"id":{"type":"string"},"hostname":{"type":"string"},"status":{"type":"string"},"sslStatus":{"type":"string"},"active":{"type":"boolean"},"cnameTarget":{"type":"string"},"records":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["type","name","value","purpose"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}}}},"errors":{"type":"array","items":{"type":"string"}}}}}}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["hostname","message"],"properties":{"hostname":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}},"message":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/hostnames/{hostname}":{"get":{"operationId":"getV1SitesByIdHostnamesByHostname","tags":["sites"],"summary":"One hostname of the site; for a proxy-mode hostname, its live status at Cloudflare and the DNS records it still needs.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"hostname","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["hostname","proxy"],"properties":{"hostname":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}},"proxy":{"oneOf":[{"type":"object","additionalProperties":false,"required":["id","hostname","status","sslStatus","active","cnameTarget","records","errors"],"properties":{"id":{"type":"string"},"hostname":{"type":"string"},"status":{"type":"string"},"sslStatus":{"type":"string"},"active":{"type":"boolean"},"cnameTarget":{"type":"string"},"records":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["type","name","value","purpose"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}}}},"errors":{"type":"array","items":{"type":"string"}}}},{"type":"null"}]}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]},"delete":{"operationId":"deleteV1SitesByIdHostnamesByHostname","tags":["sites"],"summary":"Remove a hostname from the site; a proxy-mode hostname is removed at Cloudflare too.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"hostname","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/hostnames/{hostname}/verify":{"post":{"operationId":"postV1SitesByIdHostnamesByHostnameVerify","tags":["sites"],"summary":"Check that you control a hostname: publish the TXT record shown on the hostname (_usherstats.<hostname> = usherstats-verify=<token>), then call this. A verified hostname is one the challenge page may send visitors back to and one delegated Search Console access may read. For a proxy-mode hostname this asks Cloudflare whether its validation passed (the CNAME is in place); one that another workspace held before (the add answered 202) needs the TXT record, and is set up at Cloudflare once it is found.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"hostname","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["hostname","verified","message"],"properties":{"hostname":{"type":"object","additionalProperties":false,"required":["hostname","proxy","verifiedAt","verification","createdAt"],"properties":{"hostname":{"type":"string"},"proxy":{"type":"boolean"},"verifiedAt":{"type":["string","null"]},"verification":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string"}}},"verified":{"type":"boolean"},"message":{"type":"string"},"proxy":{"type":"object","additionalProperties":false,"required":["id","hostname","status","sslStatus","active","cnameTarget","records","errors"],"properties":{"id":{"type":"string"},"hostname":{"type":"string"},"status":{"type":"string"},"sslStatus":{"type":"string"},"active":{"type":"boolean"},"cnameTarget":{"type":"string"},"records":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["type","name","value","purpose"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}}}},"errors":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/keys":{"get":{"operationId":"getV1SitesByIdKeys","tags":["sites"],"summary":"The site's live keys: public keys in full, server secrets by prefix only.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["keys"],"properties":{"keys":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","kind","value","prefix","createdAt"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["public","secret"]},"value":{"type":["string","null"]},"prefix":{"type":"string"},"createdAt":{"type":"string"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]},"post":{"operationId":"postV1SitesByIdKeys","tags":["sites"],"summary":"Create a key: \"public\" (pk_..., for the snippet) or \"secret\" (sk_live_..., for the server SDK and proxy; shown once).","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["kind"],"properties":{"kind":{"type":"string","enum":["public","secret"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"object","additionalProperties":false,"required":["id","kind","value","prefix","createdAt","shownOnce"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["public","secret"]},"value":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string"},"shownOnce":{"type":"boolean"}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/keys/{keyId}/rotate":{"post":{"operationId":"postV1SitesByIdKeysByKeyIdRotate","tags":["sites"],"summary":"Replace a key with a new one of the same kind; the old one stops working at once.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["key","replaced"],"properties":{"key":{"type":"object","additionalProperties":false,"required":["id","kind","value","prefix","createdAt","shownOnce"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["public","secret"]},"value":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string"},"shownOnce":{"type":"boolean"}}},"replaced":{"type":"string"}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/keys/{keyId}":{"delete":{"operationId":"deleteV1SitesByIdKeysByKeyId","tags":["sites"],"summary":"Revoke a key.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/snippet":{"get":{"operationId":"getV1SitesByIdSnippet","tags":["sites"],"summary":"The install snippet (a script tag with the site's public key) and how to serve it first-party through your own domain.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["publicKey","html","proxy"],"properties":{"publicKey":{"type":"string"},"html":{"type":"string"},"proxy":{"type":"object","additionalProperties":false,"required":["path","upstream","html","forwardHeaders","addHeaders","steps"],"properties":{"path":{"type":"string"},"upstream":{"type":"string"},"html":{"type":"string"},"forwardHeaders":{"type":"array","items":{"type":"string"}},"addHeaders":{"type":"array","items":{"type":"string"}},"steps":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]}},"/v1/sites/{id}/install-status":{"get":{"operationId":"getV1SitesByIdInstallStatus","tags":["sites"],"summary":"Whether collect has received data with the site's key from one of its hostnames, and when last (collect stamps it at most once a minute).","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["installed","lastSeenAt","hostnames"],"properties":{"installed":{"type":"boolean"},"lastSeenAt":{"type":["string","null"]},"hostnames":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]}},"/v1/sites/{id}/settings":{"patch":{"operationId":"patchV1SitesByIdSettings","tags":["sites"],"summary":"Replace any of the settings lists (internalNetworks, botWindows, goals, experiments); lists not named are kept.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"internalNetworks":{"type":"array","maxItems":100,"items":{"type":"string","description":"CIDR, IPv4 or IPv6"}},"botWindows":{"type":"array","maxItems":200,"items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"network":{"type":"string","minLength":1,"maxLength":100,"description":"Network (AS organisation) name"},"note":{"type":"string","minLength":1,"maxLength":200}}}},"goals":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["name","type","match"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string","minLength":1,"maxLength":200,"description":"Event name, or a path (a trailing * matches a prefix)"}}}},"experiments":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":80},"variants":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":40},"description":"At least two"},"status":{"type":"string","enum":["draft","running","stopped"]}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["settings"],"properties":{"settings":{"type":"object","additionalProperties":false,"properties":{"internalNetworks":{"type":"array","items":{"type":"string"}},"botWindows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"country":{"type":"string"},"network":{"type":"string"},"note":{"type":"string"}}}},"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","type","match"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}},"experiments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}},"bot":{"type":"object","additionalProperties":false,"required":["mode","bots","rules"],"properties":{"mode":{"type":"string"},"bots":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}}}}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/stats/catalogue":{"get":{"operationId":"getV1StatsCatalogue","tags":["analytics"],"summary":"The query catalogue: each metric set with its lanes, dimensions, filters and the counts it can sort by. A spec for /v1/sites/{id}/stats names things from these lists and nothing else.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["metrics","maxDays","aeDays"],"properties":{"metrics":{"type":"object"},"maxDays":{"type":"integer"},"aeDays":{"type":"integer"}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/stats":{"get":{"operationId":"getV1SitesByIdStats","tags":["analytics"],"summary":"One query spec, given as query parameters (metrics, by, lane, days or from and to, compare, whole, sort, and where.<filter>=value), answered by the query service. A range older than 90 days is read from the site’s daily rollups.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","spec","window","rows","sources"],"properties":{"site":{"type":"string"},"spec":{"type":"object"},"window":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":["string","null"]}}},"rows":{"type":"array","items":{"type":"object"}},"sources":{"type":"object","additionalProperties":false,"required":["rollups","ae"],"properties":{"rollups":{"type":["object","null"]},"ae":{"type":["object","null"]}}},"metrics":{"type":"object"},"previous":{"type":"object"}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/stats/query":{"post":{"operationId":"postV1SitesByIdStatsQuery","tags":["analytics"],"summary":"One query spec as a JSON body, answered by the query service: the same spec as GET /v1/sites/{id}/stats, and the way an agent asks (a tool takes no query string).","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A query spec: metrics, by, lane, days or from/to, compare, whole, where, sort. GET /v1/stats/catalogue lists the names each accepts.","properties":{"metrics":{"type":"string","enum":["pageviews","sessions","requests","events"]},"by":{"type":"string"},"lane":{"type":"string","enum":["human","bot","internal"]},"days":{"type":"integer","minimum":1,"maximum":1096},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"compare":{"type":"boolean"},"whole":{"type":"boolean"},"where":{"type":"object","additionalProperties":{"type":"string"}},"sort":{"type":"string"}},"required":["metrics","by"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","spec","window","rows","sources"],"properties":{"site":{"type":"string"},"spec":{"type":"object"},"window":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":["string","null"]}}},"rows":{"type":"array","items":{"type":"object"}},"sources":{"type":"object","additionalProperties":false,"required":["rollups","ae"],"properties":{"rollups":{"type":["object","null"]},"ae":{"type":["object","null"]}}},"metrics":{"type":"object"},"previous":{"type":"object"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/stats/batch":{"post":{"operationId":"postV1SitesByIdStatsBatch","tags":["analytics"],"summary":"Up to 40 named specs in one call: {\"queries\": {\"name\": spec}}. Each answer is under its name; a spec that is refused answers {\"error\": {\"status\": 400, \"title\"}} without failing the others.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["queries"],"properties":{"queries":{"type":"object","maxProperties":40,"additionalProperties":{"type":"object","description":"A query spec: metrics, by, lane, days or from/to, compare, whole, where, sort. GET /v1/stats/catalogue lists the names each accepts.","properties":{"metrics":{"type":"string","enum":["pageviews","sessions","requests","events"]},"by":{"type":"string"},"lane":{"type":"string","enum":["human","bot","internal"]},"days":{"type":"integer","minimum":1,"maximum":1096},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"compare":{"type":"boolean"},"whole":{"type":"boolean"},"where":{"type":"object","additionalProperties":{"type":"string"}},"sort":{"type":"string"}},"required":["metrics","by"]}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["results"],"properties":{"results":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","additionalProperties":false,"required":["site","spec","window","rows","sources"],"properties":{"site":{"type":"string"},"spec":{"type":"object"},"window":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":["string","null"]}}},"rows":{"type":"array","items":{"type":"object"}},"sources":{"type":"object","additionalProperties":false,"required":["rollups","ae"],"properties":{"rollups":{"type":["object","null"]},"ae":{"type":["object","null"]}}},"metrics":{"type":"object"},"previous":{"type":"object"}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"integer"},"title":{"type":"string"},"field":{"type":"string"}}}}}]}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/summary":{"get":{"operationId":"getV1SitesByIdSummary","tags":["analytics"],"summary":"The People boxes for ?days= (default 7) as figures -- sessions, pageviews, from search, average session, bounce rate, single-page visits, pages per session -- each with the previous period’s figure and the change (1 day is compared with the same weekday a week earlier).","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","days","window","comparedWith","figures"],"properties":{"site":{"type":"string"},"days":{"type":"integer"},"window":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":["string","null"]}}},"comparedWith":{"type":"object","additionalProperties":false,"required":["available","reason","since","from","to"],"properties":{"available":{"type":"boolean"},"reason":{"type":["string","null"]},"since":{"type":["string","null"]},"from":{"type":["string","null"]},"to":{"type":["string","null"]}}},"figures":{"type":"object","additionalProperties":false,"required":["sessions","pageviews","fromSearch","averageSessionSeconds","bounceRate","singlePagePct","pagesPerSession"],"properties":{"sessions":{"type":"object","additionalProperties":false,"required":["value","previous","change"],"properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"change":{"type":["object","null"],"additionalProperties":false,"required":["abs","pct","tone"],"properties":{"abs":{"type":"number"},"pct":{"type":["number","null"]},"tone":{"type":"string","enum":["good","bad","neutral","flat"]}}}}},"pageviews":{"type":"object","additionalProperties":false,"required":["value","previous","change"],"properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"change":{"type":["object","null"],"additionalProperties":false,"required":["abs","pct","tone"],"properties":{"abs":{"type":"number"},"pct":{"type":["number","null"]},"tone":{"type":"string","enum":["good","bad","neutral","flat"]}}}}},"fromSearch":{"type":"object","additionalProperties":false,"required":["value","previous","change"],"properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"change":{"type":["object","null"],"additionalProperties":false,"required":["abs","pct","tone"],"properties":{"abs":{"type":"number"},"pct":{"type":["number","null"]},"tone":{"type":"string","enum":["good","bad","neutral","flat"]}}}}},"averageSessionSeconds":{"type":"object","additionalProperties":false,"required":["value","previous","change"],"properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"change":{"type":["object","null"],"additionalProperties":false,"required":["abs","pct","tone"],"properties":{"abs":{"type":"number"},"pct":{"type":["number","null"]},"tone":{"type":"string","enum":["good","bad","neutral","flat"]}}}}},"bounceRate":{"type":"object","additionalProperties":false,"required":["value","previous","change"],"properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"change":{"type":["object","null"],"additionalProperties":false,"required":["abs","pct","tone"],"properties":{"abs":{"type":"number"},"pct":{"type":["number","null"]},"tone":{"type":"string","enum":["good","bad","neutral","flat"]}}}}},"singlePagePct":{"type":"object","additionalProperties":false,"required":["value","previous","change"],"properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"change":{"type":["object","null"],"additionalProperties":false,"required":["abs","pct","tone"],"properties":{"abs":{"type":"number"},"pct":{"type":["number","null"]},"tone":{"type":"string","enum":["good","bad","neutral","flat"]}}}}},"pagesPerSession":{"type":"object","additionalProperties":false,"required":["value","previous","change"],"properties":{"value":{"type":["number","null"]},"previous":{"type":["number","null"]},"change":{"type":["object","null"],"additionalProperties":false,"required":["abs","pct","tone"],"properties":{"abs":{"type":"number"},"pct":{"type":["number","null"]},"tone":{"type":"string","enum":["good","bad","neutral","flat"]}}}}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/top/{dimension}":{"get":{"operationId":"getV1SitesByIdTopByDimension","tags":["analytics"],"summary":"A top-N table: source, medium, referrer, campaign, page, page_type, country, device, bot, category, kind, network, path, status, cache, decision, event. ?days= (default 7), ?lane=, ?limit= (1-100, default 10), and for People dimensions ?count=sessions (default) or pageviews -- a session is counted where it began. Crawler dimensions count requests.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"dimension","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","dimension","lane","count","window","rows"],"properties":{"site":{"type":"string"},"dimension":{"type":"string"},"lane":{"type":"string"},"count":{"type":"string"},"window":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":["string","null"]}}},"rows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"number"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/goals":{"get":{"operationId":"getV1SitesByIdGoals","tags":["goals"],"summary":"The site’s goals: an event (by name) or a page (a path; a trailing * matches a prefix), each with the id results use.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["goals"],"properties":{"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","type","match"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]},"post":{"operationId":"postV1SitesByIdGoals","tags":["goals"],"summary":"Add a goal: {\"name\", \"type\": \"event\" | \"path\", \"match\"}. A second goal with the same name is a 409.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","type","match"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["goal"],"properties":{"goal":{"type":"object","additionalProperties":false,"required":["id","name","type","match"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["event","path"]},"match":{"type":"string"}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/goals/{goal}":{"delete":{"operationId":"deleteV1SitesByIdGoalsByGoal","tags":["goals"],"summary":"Remove a goal, by its id.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"goal","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/goals/results":{"get":{"operationId":"getV1SitesByIdGoalsResults","tags":["goals"],"summary":"Each goal over ?days= (default 7): completions (events counted, or the page’s pageviews; a prefix goal sums the top pages that match), and for an event goal the People sessions that reached it, out of all People visits, from the stored journeys.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","days","sessions","goals"],"properties":{"site":{"type":"string"},"days":{"type":"integer"},"sessions":{"type":"integer"},"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","type","match","completions","partial","sessionsReached","rate"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"match":{"type":"string"},"completions":{"type":["number","null"]},"partial":{"type":"boolean"},"sessionsReached":{"type":["number","null"]},"rate":{"type":["number","null"]}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/experiments":{"get":{"operationId":"getV1SitesByIdExperiments","tags":["goals"],"summary":"The site’s A/B tests: key (the data-exp name in the page), variants and status.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["experiments"],"properties":{"experiments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:read"]},"post":{"operationId":"postV1SitesByIdExperiments","tags":["goals"],"summary":"Add an experiment: {\"key\", \"name\"?, \"variants\": [at least two], \"status\": \"draft\" | \"running\" | \"stopped\"}.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["experiment"],"properties":{"experiment":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/experiments/{key}":{"patch":{"operationId":"patchV1SitesByIdExperimentsByKey","tags":["goals"],"summary":"Change an experiment’s name, variants or status.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"variants":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":40}},"status":{"type":"string","enum":["draft","running","stopped"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["experiment"],"properties":{"experiment":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]},"delete":{"operationId":"deleteV1SitesByIdExperimentsByKey","tags":["goals"],"summary":"Remove an experiment. Its exposures stay in the data.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/experiments/{key}/results":{"get":{"operationId":"getV1SitesByIdExperimentsByKeyResults","tags":["goals"],"summary":"An A/B test over ?days= (default 7), variant by variant: People sessions shown it, how many reached ?goal= (a goal id; default the first event goal) and the rate, events sent from it, and a two-proportion p between the two largest variants. A variant under five sessions is shown without its figures.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","days","experiment","goal","variants","p"],"properties":{"site":{"type":"string"},"days":{"type":"integer"},"experiment":{"type":"object","additionalProperties":false,"required":["key","variants","status"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","running","stopped"]}}},"goal":{"type":["object","null"]},"variants":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["variant","small","sessions","conversions","rate"],"properties":{"variant":{"type":"string"},"small":{"type":"boolean"},"sessions":{"type":["number","null"]},"conversions":{"type":["number","null"]},"rate":{"type":["number","null"]},"events":{"type":"object","additionalProperties":{"type":"number"}}}}},"p":{"type":["number","null"]}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/journeys":{"get":{"operationId":"getV1SitesByIdJourneys","tags":["goals"],"summary":"The Behaviour analysis over ?days= (default 7): visits and goal rates, a Sankey of how sessions unfold (?anchor= centres it on a step), common paths with their lift on ?goal=, and every A/B test. ?zoom=page|section|element, ?who=human|internal. Groups under five sessions are never named.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `analytics:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","days","from","params","sessions","visits","tabs","goals","anchors","sankey","motifs","motifsPartial","capped","limit","experiments"],"properties":{"site":{"type":"string"},"days":{"type":"integer"},"from":{"type":"string"},"params":{"type":"object","additionalProperties":false,"required":["zoom","anchor","goal","who"],"properties":{"zoom":{"type":"string"},"anchor":{"type":"string"},"goal":{"type":"string"},"who":{"type":"string"}}},"sessions":{"type":"integer"},"visits":{"type":"integer"},"tabs":{"type":"integer"},"goals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","label","reached","inTabs"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"reached":{"type":"integer"},"inTabs":{"type":"integer"}}}},"anchors":{"type":"array","items":{"type":"string"}},"sankey":{"type":"object"},"motifs":{"type":"array","items":{"type":"object"}},"motifsPartial":{"type":"boolean"},"capped":{"type":"boolean"},"limit":{"type":"integer"},"experiments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["experiment","variants","p"],"properties":{"experiment":{"type":"string"},"variants":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["variant","small","sessions","conversions","rate"],"properties":{"variant":{"type":"string"},"small":{"type":"boolean"},"sessions":{"type":["number","null"]},"conversions":{"type":["number","null"]},"rate":{"type":["number","null"]},"events":{"type":"object","additionalProperties":{"type":"number"}}}}},"p":{"type":["number","null"]}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the analytics:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["analytics:read"]}},"/v1/sites/{id}/bot":{"get":{"operationId":"getV1SitesByIdBot","tags":["bot"],"summary":"The site’s bot protection: mode, what to do with declared bots, and the rules, as the gate reads them.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `bot:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["bot"],"properties":{"bot":{"type":"object","additionalProperties":false,"required":["mode","bots","rules"],"properties":{"mode":{"type":"string"},"bots":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the bot:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["bot:read"]},"put":{"operationId":"putV1SitesByIdBot","tags":["bot"],"summary":"Replace the site’s bot protection settings. Checked field by field (a 400 names the first it cannot accept); a rule must match on at least one thing. Start in log mode to see what the rules would do.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `bot:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"mode: off | log (decide and record, refuse nobody) | challenge | block. bots: what happens to a declared bot no rule names. rules: first match wins.","properties":{"mode":{"type":"string","enum":["off","log","challenge","block"]},"bots":{"type":"string","enum":["allow","challenge","deny"]},"rules":{"type":"array","maxItems":200,"items":{"type":"object","additionalProperties":false,"required":["action","match"],"properties":{"action":{"type":"string","enum":["allow","challenge","deny"]},"label":{"type":"string","maxLength":80},"match":{"type":"object","description":"Every field named must hold: bot, category, ai, kind, verified, asn, country, path (a prefix).","minProperties":1}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["bot"],"properties":{"bot":{"type":"object","additionalProperties":false,"required":["mode","bots","rules"],"properties":{"mode":{"type":"string"},"bots":{"type":"string"},"rules":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the bot:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["bot:write"]}},"/v1/sites/{id}/bot/decisions":{"get":{"operationId":"getV1SitesByIdBotDecisions","tags":["bot"],"summary":"What the gate decided over ?days= (default 7), for every request but the site’s own -- files and refusals included -- as action (allow, challenge, block) and reason, by crawler category and name. Also needs analytics:read.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `bot:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["site","window","decisions","totals"],"properties":{"site":{"type":"string"},"window":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":["string","null"]}}},"decisions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["action","reason","category","bot","requests"],"properties":{"action":{"type":"string"},"reason":{"type":"string"},"category":{"type":"string"},"bot":{"type":"string"},"requests":{"type":"number"}}}},"totals":{"type":"object","additionalProperties":{"type":"number"}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the bot:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["bot:read"]}},"/v1/sites/{id}/search":{"get":{"operationId":"getV1SitesByIdSearch","tags":["search"],"summary":"Which search sources are connected: the Search Console property and the account that reads it, the Bing site; and serviceAccount, the address to add to your property for delegated access.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `search:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["google","bing","serviceAccount"],"properties":{"google":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["mode","property","account"],"properties":{"mode":{"type":"string","enum":["service_account","delegated"]},"property":{"type":"string"},"account":{"type":["string","null"]}}}]},"bing":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["siteUrl"],"properties":{"siteUrl":{"type":"string"}}}]},"serviceAccount":{"type":["string","null"]}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the search:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["search:read"]}},"/v1/sites/{id}/search/google":{"put":{"operationId":"putV1SitesByIdSearchGoogle","tags":["search"],"summary":"Connect Google Search Console: \"mode\": \"service_account\" with your key file’s JSON as \"key\", or \"delegated\" after adding our service account (GET /v1/sites/{id}/search) to the property -- delegated only for a property whose host is a verified hostname of the site. \"property\" is sc-domain:example.com or https://example.com/.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `search:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["mode","property"],"properties":{"mode":{"type":"string","enum":["service_account","delegated"]},"property":{"type":"string","minLength":1,"maxLength":300,"description":"sc-domain:example.com, or a URL-prefix property such as https://example.com/"},"key":{"type":["string","object"],"description":"The service account key file (service_account mode only)"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["google","bing","serviceAccount"],"properties":{"google":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["mode","property","account"],"properties":{"mode":{"type":"string","enum":["service_account","delegated"]},"property":{"type":"string"},"account":{"type":["string","null"]}}}]},"bing":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["siteUrl"],"properties":{"siteUrl":{"type":"string"}}}]},"serviceAccount":{"type":["string","null"]}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the search:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["search:write"]},"delete":{"operationId":"deleteV1SitesByIdSearchGoogle","tags":["search"],"summary":"Disconnect Search Console: its credentials are deleted; the weeks already collected stay.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `search:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the search:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["search:write"]}},"/v1/sites/{id}/search/bing":{"put":{"operationId":"putV1SitesByIdSearchBing","tags":["search"],"summary":"Connect Bing Webmaster Tools with an API key (Settings > API access in Bing) and the site as Bing lists it, https://example.com/.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `search:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiKey","siteUrl"],"properties":{"apiKey":{"type":"string","minLength":1,"maxLength":200},"siteUrl":{"type":"string","minLength":1,"maxLength":300}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["google","bing","serviceAccount"],"properties":{"google":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["mode","property","account"],"properties":{"mode":{"type":"string","enum":["service_account","delegated"]},"property":{"type":"string"},"account":{"type":["string","null"]}}}]},"bing":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["siteUrl"],"properties":{"siteUrl":{"type":"string"}}}]},"serviceAccount":{"type":["string","null"]}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the search:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["search:write"]},"delete":{"operationId":"deleteV1SitesByIdSearchBing","tags":["search"],"summary":"Disconnect Bing: its credentials are deleted; the weeks already collected stay.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `search:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"204":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the search:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["search:write"]}},"/v1/sites/{id}/search/weeks":{"get":{"operationId":"getV1SitesByIdSearchWeeks","tags":["search"],"summary":"The weekly search figures, one row per week (starting Monday) and source, over the last ?weeks= (default 26, at most 520). A figure that could not be collected is null; a zero is a measurement.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `search:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["weeks"],"properties":{"weeks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["week","source","clicks","impressions","ctr","position","pages","queries","inboundLinks","collectedAt"],"properties":{"week":{"type":"string"},"source":{"type":"string"},"clicks":{"type":["number","null"]},"impressions":{"type":["number","null"]},"ctr":{"type":["number","null"]},"position":{"type":["number","null"]},"pages":{"type":["number","null"]},"queries":{"type":["number","null"]},"inboundLinks":{"type":["number","null"]},"collectedAt":{"type":"string"}}}}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the search:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["search:read"]}},"/v1/sites/{id}/internal-link":{"post":{"operationId":"postV1SitesByIdInternalLink","tags":["internal"],"summary":"A link that marks the browser opening it as the site’s own, so its visits count as Internal rather than People. Open it within ten minutes in that browser; it works on the site’s first-party path (/_us/), which the Worker SDK adds and the first-party proxy setup forwards. Only for a verified (or proxy-mode) hostname of the site; \"hostname\" defaults to the first such.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hostname":{"type":"string","format":"hostname"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url","hostname","expiresAt"],"properties":{"url":{"type":"string"},"hostname":{"type":"string"},"expiresAt":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/internal-link/rotate":{"post":{"operationId":"postV1SitesByIdInternalLinkRotate","tags":["internal"],"summary":"Replace the site’s internal key: every browser marked before stops counting as the site’s own, and every x-usher-internal header signed with the old key is refused. Mark the team’s browsers again afterwards.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `sites:write` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["version"],"properties":{"version":{"type":"integer"}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the sites:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["sites:write"]}},"/v1/sites/{id}/export":{"post":{"operationId":"postV1SitesByIdExport","tags":["export"],"summary":"Export a site: its settings, its store (daily rollups, journeys, search weeks), and a listing of its raw archive (optionally only \"from\"-\"to\", YYYY-MM-DD), written to storage. Answers with download links that work for an hour. Credentials (search keys, server secrets) are never exported.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `export:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["export"],"properties":{"export":{"type":"object","additionalProperties":false,"required":["id","site","createdAt","expiresAt","files","archive"],"properties":{"id":{"type":"string"},"site":{"type":"string"},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"files":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","url","bytes"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"bytes":{"type":"integer"}}}},"archive":{"type":"object","additionalProperties":false,"required":["objects","bytes","truncated"],"properties":{"objects":{"type":"integer"},"bytes":{"type":"integer"},"truncated":{"type":"boolean"}}}}}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the export:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["export:read"]}},"/v1/downloads/{token}":{"get":{"operationId":"getV1DownloadsByToken","tags":["export"],"summary":"A download link from an export: the file itself while the link is good (an hour), 410 after, and 403 once whoever made it can no longer export the site (removed, revoked, or the site deleted). The link is the credential; it names one object and cannot be changed into another.","description":"No credentials needed.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Done; no body"},"404":{"description":"No such resource in your workspace (another workspace's ids are 404 too)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/billing":{"get":{"operationId":"getV1Billing","tags":["billing"],"summary":"The plan, its status and allowances, this month's usage, overage so far (cents) and projected to the month end.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `billing:read` scope.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["plan","label","status","interval","currentPeriodEnd","cancelAtPeriodEnd","pendingPlan","pendingAt","graceUntil","hasBillingAccount","period","usage","allowances","overage","projected","serverRequestsPaused"],"properties":{"plan":{"type":"string"},"label":{"type":"string"},"status":{"type":"string"},"interval":{"type":["string","null"]},"currentPeriodEnd":{"type":["string","null"]},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":["string","null"]},"pendingAt":{"type":["string","null"]},"graceUntil":{"type":["string","null"]},"hasBillingAccount":{"type":"boolean"},"period":{"type":"string"},"usage":{"type":"object","additionalProperties":false,"required":["pageviews","serverRequests","proxyHostnames"],"properties":{"pageviews":{"type":"integer"},"serverRequests":{"type":"integer"},"proxyHostnames":{"type":"integer"}}},"allowances":{"type":"object","additionalProperties":false,"required":["pageviews","serverRequests","proxyHostnames"],"properties":{"pageviews":{"type":"integer"},"serverRequests":{"type":"integer"},"proxyHostnames":{"type":["integer","null"]}}},"overage":{"type":"object","additionalProperties":false,"required":["pageviews","serverRequests","proxyHostnames","amountCents"],"properties":{"pageviews":{"type":"integer"},"serverRequests":{"type":"integer"},"proxyHostnames":{"type":"integer"},"amountCents":{"type":"integer"}}},"projected":{"type":"object","additionalProperties":false,"required":["pageviews","serverRequests","overageCents"],"properties":{"pageviews":{"type":"integer"},"serverRequests":{"type":"integer"},"overageCents":{"type":"integer"}}},"serverRequestsPaused":{"type":"boolean"}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the billing:read scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["billing:read"]}},"/v1/billing/checkout":{"post":{"operationId":"postV1BillingCheckout","tags":["billing"],"summary":"Start a Stripe Checkout session to subscribe to a paid plan (monthly or yearly). Answers the Checkout URL; the plan changes when Stripe confirms payment.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `billing:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["plan"],"properties":{"plan":{"type":"string","enum":["starter","growth","business"]},"interval":{"type":"string","enum":["month","year"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","url"],"properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the billing:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["billing:write"]}},"/v1/billing/portal":{"post":{"operationId":"postV1BillingPortal","tags":["billing"],"summary":"Open Stripe's Customer Portal for this workspace: update the card, download invoices, cancel at period end. Answers the portal URL.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `billing:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string"}}}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the billing:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["billing:write"]}},"/v1/billing/plan":{"post":{"operationId":"postV1BillingPlan","tags":["billing"],"summary":"Change the plan of the subscription: an upgrade applies now (prorated), a downgrade at the end of the paid period, \"free\" cancels at period end; choosing a plan again before then resumes.","description":"An API token, or a signed-in person (select the workspace with the X-Workspace header or ?workspace=). Requires the `billing:write` scope. Not available to site-restricted tokens.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Any unique string (a UUID). Repeating the request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["plan"],"properties":{"plan":{"type":"string","enum":["free","starter","growth","business"]},"interval":{"type":"string","enum":["month","year"]}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["plan","effectiveAt","message"],"properties":{"plan":{"type":"string"},"effectiveAt":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"The body was refused; `title` and `field` say which field and why","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Done; no body"},"403":{"description":"Missing the billing:write scope (the title names it)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-scopes":["billing:write"]}},"/v1/billing/webhook":{"post":{"operationId":"postV1BillingWebhook","tags":["billing"],"summary":"Stripe's webhook endpoint. Only requests carrying a valid Stripe-Signature (within 5 minutes) are accepted; each event is applied once.","description":"No credentials needed.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["received","outcome"],"properties":{"received":{"type":"boolean"},"outcome":{"type":"string"}}}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getV1OpenapiJson","tags":["meta"],"summary":"This API as an OpenAPI 3.1 document, generated from the routes the Worker serves.","description":"No credentials needed.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["openapi","paths"],"properties":{"openapi":{"type":"string"},"paths":{"type":"object"}}}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/mcp":{"post":{"operationId":"postMcp","tags":["mcp"],"summary":"The Model Context Protocol endpoint (Streamable HTTP, JSON-RPC 2.0): every API route an API token can call, as MCP tools for AI agents. Protocol versions 2026-07-28 (stateless) and 2025-03-26 to 2025-11-25 (initialize).","description":"An API token only; sign-in cookies are not accepted.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":["object","array"],"description":"A JSON-RPC 2.0 response (an array of them for a 2025-03-26 batch)"}}}},"202":{"description":"Done; no body"},"401":{"description":"No credentials, or an unknown, revoked or expired token or session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Any other error, as problem+json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API token: Authorization: Bearer us_live_..."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"us_session"}},"schemas":{"Problem":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","description":"https://usherstats.com/errors/<kind>"},"title":{"type":"string","description":"What went wrong and what to do, written for the caller"},"status":{"type":"integer"},"field":{"type":"string","description":"For a 400, the field that was refused"},"retryAfter":{"type":"integer","description":"For a 429, seconds to wait (also in the Retry-After header)"}}}}}}