Confirm site migration candidate

POST/v1/api/sites/{site_id}/migrations/candidates/{candidate_id}/confirm

Confirm the candidate as a migration project; needs the preview's token.

Answers 409 while the candidate's confirmable is false, with its confirm_blocked_reason as the detail.

Scope: sites:write
Token: OAuth access token only
Role: Editor, owner or admin
MCP tool: confirm_migration_candidate · preview: MCP write tools are in preview; What scopes, tokens and roles mean →

Request

curl -X POST "https://api.crawle.io/v1/api/sites/11111111-1111-1111-1111-111111111111/migrations/candidates/1/confirm" \
  -H "Authorization: Bearer $CRAWLE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Crawle-Confirmation: $CONFIRMATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch("https://api.crawle.io/v1/api/sites/11111111-1111-1111-1111-111111111111/migrations/candidates/1/confirm", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CRAWLE_ACCESS_TOKEN}`,
    "Idempotency-Key": crypto.randomUUID(),
    "X-Crawle-Confirmation": confirmationToken, // from the preview response
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await response.json();

import os
import uuid

import requests

response = requests.request(
    "POST",
    "https://api.crawle.io/v1/api/sites/11111111-1111-1111-1111-111111111111/migrations/candidates/1/confirm",
    headers={
        "Authorization": f"Bearer {os.environ['CRAWLE_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Crawle-Confirmation": confirmation_token,  # from the preview response
    },
    json={},
)
data = response.json()

$CRAWLE_ACCESS_TOKEN: is an OAuth access token from your integration's sign-in.
$CONFIRMATION_TOKEN: is the confirmation_token the preview step returned.
Idempotency-Key: is a new unique value for each new request.

Response 200JSON

{
  "avg_path_similarity": 1.5,
  "client_id": "example",
  "committed": true,
  "completed_at": "2026-01-01T09:00:00Z",
  "confidence": 1.5,
  "confirmed_at": "2026-01-01T09:00:00Z",
  "crawler_candidate_id": 1,
  "created_at": "2026-01-01T09:00:00Z",
  "details": {},
  "effect_results": {},
  "evidence_status": "current",
  "grace_days": 1,
  "grace_ends_at": "2026-01-01T09:00:00Z",
  "grace_started_at": "2026-01-01T09:00:00Z",
  "id": "example",
  "migration_type": "example",
  "receipt_id": "example",
  "redirect_count": 1,
  "redirect_coverage": 1.5,
  "redirect_url_denominator": 1,
  "rejected_at": "2026-01-01T09:00:00Z",
  "replayed": false,
  "source_domain": "example.com",
  "source_website_id": "example",
  "status": "example",
  "target_domain": "example.com",
  "target_verified": true,
  "target_website_id": "example",
  "updated_at": "2026-01-01T09:00:00Z"
}

Example generated from the API contract.

Parameters

site_idpath · string (uuid)required
candidate_idpath · integerrequired
X-Crawle-Confirmationheader · stringrequired: One-use confirmation_token returned by the matching preview route.1–256 characters
Idempotency-Keyheader · stringrequired: 1–180 characters

Request body

grace_daysinteger: 1–90 · default 30
target_website_idstring (uuid) or null

Response 200

avg_path_similaritynumberrequired
client_idstringrequired
completed_atstring (date-time) or nullrequired
confidencenumberrequired
confirmed_atstring (date-time) or nullrequired
crawler_candidate_idinteger or nullrequired
created_atstring (date-time)required
detailsobject or nullrequired
effect_resultsobjectrequired
evidence_statusenum or nullrequired: one of "current", "stale"
grace_ends_atstring (date-time) or nullrequired
grace_started_atstring (date-time) or nullrequired
idstringrequired
migration_typestringrequired
receipt_idstringrequired
redirect_countintegerrequired
redirect_coveragenumber or nullrequired
redirect_url_denominatorinteger or nullrequired
rejected_atstring (date-time) or nullrequired
source_domainstringrequired
source_website_idstringrequired
statusstringrequired
target_domainstringrequired
target_verifiedboolean or nullrequired
target_website_idstring or nullrequired
updated_atstring (date-time)required
committedboolean: default true
grace_daysinteger or null: 1–90
replayedboolean: default false

Errors

401
When
Missing, invalid, or expired token.
403
When
The token has none of the accepted scopes (sites:write).
403
When
Called with an API key. This endpoint needs an OAuth access token.
403
When
The person's workspace role is below editor.
422
When
The request did not match the schema. detail lists each problem.
429
When
Rate limited. Wait for Retry-After seconds.

Confirm site migration candidate: errors
Status	When
401	Missing, invalid, or expired token.
403	The token has none of the accepted scopes (`sites:write`).
403	Called with an API key. This endpoint needs an OAuth access token.
403	The person's workspace role is below editor.
422	The request did not match the schema. `detail` lists each problem.
429	Rate limited. Wait for `Retry-After` seconds.

All errors and what to do →

Generated from the API contract at 7e7039b0b, synced October 30, 2026.