Create site

POST/v1/api/sites

Step 2 of 2. First call the preview, then send its confirmation_token here. Preview create site →

Create a site using OAuth user consent and editor permissions.

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

Request

curl -X POST "https://api.crawle.io/v1/api/sites" \
  -H "Authorization: Bearer $CRAWLE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Crawle-Confirmation: $CONFIRMATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

const response = await fetch("https://api.crawle.io/v1/api/sites", {
  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({
    "domain": "example.com"
  }),
});
const data = await response.json();

import os
import uuid

import requests

response = requests.request(
    "POST",
    "https://api.crawle.io/v1/api/sites",
    headers={
        "Authorization": f"Bearer {os.environ['CRAWLE_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Crawle-Confirmation": confirmation_token,  # from the preview response
    },
    json={
      "domain": "example.com"
    },
)
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 201: a JSON object. Its fields are not described in the API contract yet, so no example is shown.

Parameters

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

domainstringrequired: 3–255 characters
client_group_idstring (uuid) or null
crawl_regionstring or null
custom_headersobject or null
custom_robots_txtstring or null
custom_user_agentstring or null
project_namestring or null: up to 255 characters
robots_policystring or null
scope_modestring or null
sitemap_urlstring or null: up to 2048 characters
tag_idsarray of string (uuid) or null
url_budgetinteger: 0–500000 · default 0
user_agentstring or null

Response 201

Returns a JSON object. Its fields are not described in the API contract yet.

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.

Create site: 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.