> ## Documentation Index > Fetch the complete documentation index at: https://docs.sorraia.app/llms.txt > Use this file to discover all available pages before exploring further. # Read this site's domain-verification status > The verification state of the one site the key belongs to, plus the instructions for every method. Authenticates with a **site key**, not an API key. `instructions` — and therefore the verification token inside it — is present ONLY while `verified` is `false`. Once a site is verified the token authorises nothing further and is not returned, so a plugin that polls for status never receives a secret it does not need. `method` is the method that last proved (or was chosen to prove) ownership: `dns_txt`, `meta_tag`, `wp_plugin`, or `null` if none has been picked. `instructions.wp_plugin.paths` lists the exact URLs this API will probe on the site, so a merchant behind a firewall can allowlist them. ## OpenAPI ````yaml /api/openapi.yaml get /site-verification openapi: 3.1.0 info: title: Sorraia API version: 1.0.0 description: > The Sorraia public API (v1). Read and manage your forms, submissions, calendars, bookings, shop widgets, and orders programmatically. Authenticate with an API key created in the Sorraia dashboard (Settings → Integrations, under Programmatic API access). Pass it as a Bearer token: `Authorization: Bearer sor_live_...`. Keys are scoped — a key only reaches the endpoints its scopes allow (e.g. `read:forms`, `write:submissions`). API access is included with every paid Sorraia plan. A key whose account is on the Free plan receives `402` with `code: plan_feature_gated` (`feature: apiAccess`) on every endpoint that takes an API key, except `DELETE /webhooks/{id}` — unsubscribing always works. Upgrading lifts it on the next request; keys are never revoked. The site-key endpoints (`/site-catalog`, `/site-verification` and `/site-verification/attempt`) are not affected. All responses are JSON. List endpoints return a `{ data, pagination }` envelope; single-resource endpoints return the object directly. Requests are rate-limited per API key; see the `X-RateLimit-*` response headers. contact: name: Sorraia Support url: https://sorraia.app license: name: Proprietary url: https://sorraia.app/terms servers: - url: https://api.sorraia.app/v1 description: Production security: - bearerAuth: [] tags: - name: forms description: Create, read, update, and archive forms. - name: submissions description: Read and programmatically ingest form submissions. - name: calendars description: Read calendar widgets. - name: bookings description: Read calendar bookings. - name: ecommerce description: Read shop widgets. - name: orders description: Read shop orders. - name: site-catalog description: > List one site's embeddable widgets. Authenticated by a per-site key rather than an API key — built for site-builder plugins (WordPress and friends) that need a widget picker, not a data feed. - name: site-verification description: > Prove ownership of a site's domain from inside the merchant's own WordPress admin. Authenticated by a per-site key rather than an API key. Reading the token is a read; the attempt endpoint asks Sorraia to fetch that token back from the hostname being claimed — the key never asserts verification itself. - name: webhooks description: Manage event subscriptions (REST Hooks) for integrations. paths: /site-verification: get: tags: - site-verification summary: Read this site's domain-verification status description: > The verification state of the one site the key belongs to, plus the instructions for every method. Authenticates with a **site key**, not an API key. `instructions` — and therefore the verification token inside it — is present ONLY while `verified` is `false`. Once a site is verified the token authorises nothing further and is not returned, so a plugin that polls for status never receives a secret it does not need. `method` is the method that last proved (or was chosen to prove) ownership: `dns_txt`, `meta_tag`, `wp_plugin`, or `null` if none has been picked. `instructions.wp_plugin.paths` lists the exact URLs this API will probe on the site, so a merchant behind a firewall can allowlist them. operationId: getSiteVerification responses: '200': description: The site's verification status. content: application/json: schema: $ref: '#/components/schemas/SiteVerification' '401': description: No `X-Sorraia-Site-Key` header was sent. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: > The site key is unknown, has been regenerated, or the site is archived. Returned instead of 401 so the response cannot be used to probe which keys exist. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' security: - siteKeyAuth: [] components: schemas: SiteVerification: type: object required: - domain - verified - method - methods properties: domain: type: string description: The registered hostname, e.g. `example.com`. verified: type: boolean description: Whether ownership of the hostname is currently proven. method: type: - string - 'null' enum: - dns_txt - meta_tag - wp_plugin - null description: > How ownership was last proven, or the method chosen at registration. `null` if none has been picked. verifiedAt: type: - string - 'null' format: date-time description: When ownership was last proven. Cleared if verification lapses. lastCheckedAt: type: - string - 'null' format: date-time description: > When Sorraia last looked, whether or not the check passed. Distinct from `verifiedAt`, which only moves on success. methods: type: array items: type: string description: Every verification method this API supports. instructions: $ref: '#/components/schemas/SiteVerificationInstructions' Error: type: object description: > Standard error envelope. `code` is a stable machine-readable string (e.g. invalid_api_key, insufficient_scope, not_found, rate_limited, domain_required, forbidden_field, plan_feature_gated, plan_limit_reached). Some errors carry extra context fields (candidates, required, fields, invalid, retryAfter, feature, resource, cap, used, domainId). required: - error additionalProperties: true properties: error: type: string description: Human-readable message. code: type: string description: Stable machine-readable error code. SiteVerificationInstructions: type: object description: > How to prove ownership, for each method. **Present only while the site is unverified** — it carries the verification token. required: - token - dns_txt - meta_tag - wp_plugin properties: token: type: string description: > The site's verification token — 32 base64url characters. Treat it as a proof-of-control nonce rather than a bearer credential: with `meta_tag` and `wp_plugin` it is published on the merchant's own site by design. dns_txt: type: object properties: type: type: string description: Always `TXT`. host: type: string description: >- The record host — the registered hostname itself, with no underscore prefix. value: type: string description: The record value, `sorraia-verify=`. Must match exactly. meta_tag: type: object properties: url: type: string description: The page Sorraia will fetch. html: type: string description: The tag to place in that page's . wp_plugin: type: object properties: paths: type: array items: type: string description: > The exact URLs Sorraia will probe, in order. Allowlist these if a firewall is in the way. pluginSlug: type: string description: The WordPress plugin slug (`sorraia`). note: type: string description: Human-readable prerequisites and limitations. responses: RateLimited: description: The per-API-key request budget for the current window is exhausted. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: An unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' headers: RateLimitLimit: description: The per-API-key request budget for the current 1-hour window. schema: type: integer RateLimitRemaining: description: Requests remaining in the current window after this request. schema: type: integer RateLimitReset: description: Unix timestamp (seconds) at which the rate-limit window resets. schema: type: integer RetryAfter: description: Seconds to wait before retrying. Present on 429 responses. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: sor_live_* description: > A Sorraia API key created in the dashboard (Settings → Integrations, under Programmatic API access). Pass it as `Authorization: Bearer sor_live_...`. API access is included with every paid plan; a key whose account is on the Free plan receives `402` `plan_feature_gated`. siteKeyAuth: type: apiKey in: header name: X-Sorraia-Site-Key description: > A per-site key (`sor_site_...`), shown on the site's Embed card in the dashboard (Site → Embed) and regenerable there. It authorises three operations for the single site it belongs to — `GET /site-catalog`, `GET /site-verification` and `POST /site-verification/attempt` — and nothing else. It is NOT an API key: it carries no scopes, reads no customer data, and `Authorization: Bearer` will not accept it. It is not purely read-only: the attempt endpoint can mark the site's domain verified. It does so only by asking Sorraia to fetch the site's verification token back from the registered hostname — the key proves account access, never hostname control, so it cannot claim a domain it cannot serve the token from. ````