---
title: "Start the check that proves your human owns a site"
method: POST
path: "/v1/sites/{site}/verification"
tags: ["sites"]
---

# Start the check that proves your human owns a site

`POST /v1/sites/{site}/verification`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/sites/{site}/verification`
- Auth: HTTP bearer

Prove your human owns a site, which unlocks the verified-only crawl settings (rate faster than 250 ms, more than 2 requests at a time, user-agent presets, credentials, custom headers). It mints the site's token once and queues a check of `method`: dns_txt (a TXT record `frontshelf-verify=<token>` on the host or on _frontshelf.<host>), meta_tag (`<meta name="frontshelf-site-verification" content=…>` on the origin's /) or well_known (the bare token at /.well-known/frontshelf-verify.txt). Each method's `place_at` and `value` say exactly what your human puts where: tell them. The check runs within seconds; read the verdict with ownership_get, and `last_error` when it fails. Calling it again for a method checks again. The proof is re-checked weekly; losing it holds the crawl settings back (the config is kept) until it is restored.

## Path parameters

- `site` string, required: Site ID (site_…), origin (https://example.com), or bare domain, resolved server-side; the response carries the canonical ID.

## Request body

- object
  - `method` 'dns_txt' | 'meta_tag' | 'well_known': Which proof to check: dns_txt (the default), meta_tag or well_known.
  - `dry_run` boolean: true: check the call and say what it would do, without doing it.
  - `confirm` boolean: true: go ahead with a change that asks for confirmation.

## Response `202`

Start the check that proves your human owns a site

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `site_id` string, required
  - `origin` string, required
  - `verified` boolean, required: True while at least one proof holds: the verified-only crawl settings apply.
  - `verified_at` string, nullable, required: Since when the site is verified (ISO 8601); null when it is not.
  - `token` string, nullable, required: The site's verification token; null until a check was first started (sites_verify mints it).
  - `methods` object[], required: Every method, once a token exists (empty before): what to place where, and its verdict.
    - `method` 'dns_txt' | 'meta_tag' | 'well_known', required
    - `status` 'pending' | 'checking' | 'verified' | 'failed' | 'lost', required: `pending`: never checked; `checking`: a check is queued or running; `verified`: the last check saw the proof; `failed`: it did not (`last_error` says why); `lost`: it was verified and the weekly re-check no longer sees it.
    - `verified_at` string, nullable, required
    - `last_checked_at` string, nullable, required
    - `last_error` string, nullable, required: Why the last check failed, in words; null otherwise.
    - `place_at` string, required: Where your human puts the proof: a DNS name or a URL.
    - `value` string, required: Exactly what to put there.
  - `wordpress` object, nullable, required: The site's WordPress connection as a proof: it proves the site only when WordPress is at the root of the site's own address with an administrator connected. Read-only here: your human connects WordPress in Frontshelf's Content settings (Publishing), and the connection's own weekly re-check observes it; sites_verify never starts or checks it. Null until a connection was judged.
    - `status` 'pending' | 'checking' | 'verified' | 'failed' | 'lost', required: `verified`: the connection proves the site; `failed`: it does not (`last_error` says why); `lost`: it proved it and no longer does.
    - `verified_at` string, nullable, required
    - `last_checked_at` string, nullable, required
    - `last_error` string, nullable, required: Why the connection does not prove the site, in words; null otherwise.
  - `settings_url` string, required: The site's verification page in Frontshelf (app-relative), to hand your human.

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `402`: BILLING_REQUIRED
- `403`: ORGANIZATION_FROZEN, SCOPE_DENIED
- `404`: SITE_NOT_FOUND
- `409`: AMBIGUOUS_SITE, AGENT_STOPPED
- `503`: PLATFORM_READ_ONLY, DEPENDENCY_UNAVAILABLE

---

[API](https://skmtc.dev/frontshelf/apis/frontshelf-api.md) · [All operations](https://skmtc.dev/frontshelf/apis/frontshelf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontshelf/apis/frontshelf-api/revisions/ce3602d26c7c?raw)