Docs / Deployments

Official CrawlDrift Deployment API

Use the canonical provider-neutral endpoint to report deployment metadata and optionally request a linked FULL crawl.

Request

Send the Project ID in the URL. At least one of version, buildNumber or commitSha is required.

POST /v1/projects/{projectId}/deployments
Authorization: Bearer cd_deploy_...
Idempotency-Key: <provider-run-or-deployment-id>
Content-Type: application/json

Example payload

{
  "version": "v1.8.0",
  "buildNumber": "248",
  "commitSha": "a72c91f8f67d",
  "environment": "production",
  "externalDeploymentId": "github:deployment:1845932",
  "deployedAt": "2026-08-04T15:40:00Z",
  "triggerCrawl": true
}

Authentication

Use a Project-scoped Deployment key with the deployment:write scope. The key Project must match the Project ID in the URL; a mismatch returns a non-disclosing authorization error.

Supply the key only as a Bearer token. Never put it in a query string, URL path or request body.

Accepted response

A 202 Accepted response means the deployment command was durably accepted. It does not mean the linked crawl completed.

{
  "data": {
    "deploymentId": "dep_01K...",
    "projectId": "prj_01K...",
    "version": "v1.8.0",
    "buildNumber": "248",
    "commitSha": "a72c91f8f67d",
    "environment": "production",
    "deployedAt": "2026-08-04T15:40:00Z",
    "crawl": {
      "requested": true,
      "status": "SCHEDULED",
      "rolloutDelaySeconds": 180
    }
  }
}

Idempotency

Use the Idempotency-Key header or externalDeploymentId field. Uniqueness is scoped by Project ID plus the selected idempotency value.

A repeated submission returns the original deployment result and does not create another crawl.

Shared API contract

Fields, limits and linked crawl behavior

All official clients and compatibility examples submit the same provider-neutral Deployment API contract.

Field	Required	Limit	Purpose
version	One identity field*	100 characters	Release version
buildNumber	One identity field*	100 characters	CI build number
commitSha	One identity field*	100 characters	Commit identity
environment	Optional	50 characters	Deployment environment
externalDeploymentId	Optional	200 characters	Provider deployment identity and idempotency
deployedAt	Optional	Timestamp string	Deployment time
note	Optional	1000 characters	Deployment note
triggerCrawl	Optional	Boolean	Request a linked FULL crawl
rolloutDelaySeconds	Optional	0–3600 seconds	Wait before requesting the linked crawl

* At least one of version, buildNumber or commitSha must be present.

Rollout delay

The request value takes precedence, followed by the Project deployment default, then the platform default. The recommended platform default is 180 seconds; the client does not wait locally.

Collision and quota

An active FULL crawl is not cancelled or replaced. The linked crawl waits for it to finish. Deployment-triggered crawls consume normal crawl-page quota; without quota, the deployment remains recorded and the crawl is BLOCKED_BY_QUOTA.

Retries and timeout

Official clients use a recommended 10-second timeout and may retry network failures, connection resets, and HTTP 502, 503 or 504 with bounded exponential backoff and jitter. Reuse the same idempotency key.

Do not automatically retry most 400, 401, 403, 404, 409 semantic conflict or 422 responses. A timeout does not prove rejection.

Key security

A Deployment key can create deployment records only for its Project. It cannot read Project, Incident or Crawl data, change settings or billing, manage users, start arbitrary crawls or access another Project.

Keys are shown in full once, stored as a cryptographic hash, revocable, replaceable and excluded from logs and diagnostics.

Request limits and target safety

Recommended per-key limits are 10 requests per minute burst and 100 requests per hour sustained; exact limits may be adjusted based on usage.

The API accepts metadata, not callback or arbitrary target URLs. The Project's verified canonical domain remains the crawl target.