---
title: "Update project defaults"
method: PATCH
path: "/projects/{project_id}/defaults"
tags: ["projects"]
---

# Update project defaults

`PATCH /projects/{project_id}/defaults`

## Request

- Base URL: `https://eu.bisibility.com/api/v1`
- URL: `https://eu.bisibility.com/api/v1/projects/{project_id}/defaults`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `/api/auth/oauth2/authorize`, token URL `/api/auth/oauth2/token`, scopes: `api:write`)

Preview first, then confirm the exact source/revision/token with a stable command key. Lost responses replay the same committed receipt. Omitted review refuses before writes; changed source or expired quotes require a new preview. Existing targets/history are not retargeted.

## Path parameters

- `project_id` string, required: Public project ID; membership and token scope are enforced.

## Query parameters

- `preview_only` boolean

## Headers

- `Bisibility-API-Version` 'v1'
- `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp'

## Request body

- ProjectDefaultsPatch
  - `review` ProjectDefaultsReview
    - `expected_source_hash` string, required
    - `expected_revision` string, required
    - `preview_token` string, required
    - `idempotency_key` string, required
    - `confirmed` true, required
  - `city` string, nullable: Optional city name resolved within country when location_key is omitted. Deprecated legacy market input: send location_key instead. Still accepted for compatibility; no removal version is scheduled.
  - `country` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates': Optional country selector when location_key is omitted. Provide together with device. Deprecated legacy market input: send location_key instead. Still accepted for compatibility; no removal version is scheduled.
  - `cron_expression` string, nullable
  - `device` 'desktop' | 'mobile': Optional device selector. Provide with country when location_key is omitted; with location_key it overrides the current default device.
  - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron'
  - `jitter_minutes` integer: Whole-minute random delay from 0 to 120. Set 0 to disable jitter.
  - `location_key` string: Primary location reference: canonical country, region, or city key, optionally qualified with @language. Updates the default market from a canonical location key. Country and city are resolved from the location catalog; device defaults to the current default device when omitted.
  - `serp_depth` 10 | 20 | 50 | 100: Default number of SERP results scanned per rank check. Omitted keeps the stored depth.
  - `serp_stop_on_match` boolean: Set false to fetch the full configured depth for competitor snapshots.
  - `timezone` string: IANA time zone that anchors monthly and custom cron wall-clock schedules. Daily and weekly use a stable keyword-specific interval phase that timezone does not move.

## Response `200`

JSON response

- union
  - ProjectDefaults
    - `city` string, nullable, required
    - `country` string, required: Persisted default country for new keywords.
    - `cron_expression` string, nullable, required
    - `device` 'desktop' | 'mobile', required: Persisted default device for new keywords and moved default-market keywords.
    - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron', required
    - `jitter_minutes` integer, required: Whole-minute random delay from 0 to 120. Set 0 to disable jitter.
    - `last_checked_at` string, date-time, nullable, required
    - `location_key` string, required: Persisted canonical location key for the default market.
    - `next_check_at` string, date-time, nullable, required
    - `project_id` string, required
    - `serp_depth` 10 | 20 | 50 | 100, required
    - `serp_stop_on_match` boolean, required: Stops a SERP crawl after the tracked domain is found.
    - `source` 'derived' | 'explicit' | 'fallback', required: How the effective default market was selected.
    - `timezone` string, required: IANA time zone that anchors monthly and custom cron wall-clock schedules. Daily and weekly use a stable keyword-specific interval phase that timezone does not move.
    - `updated_at` string, date-time, nullable
  - ProjectDefaultsPreview
    - `request` object, required
      - `kind` 'patch', required
      - `values` object, required
        - `review` ProjectDefaultsReview
          - `expected_source_hash` string, required
          - `expected_revision` string, required
          - `preview_token` string, required
          - `idempotency_key` string, required
          - `confirmed` true, required
        - `city` string, nullable: Optional city name resolved within country when location_key is omitted. Deprecated legacy market input: send location_key instead. Still accepted for compatibility; no removal version is scheduled.
        - `country` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates': Optional country selector when location_key is omitted. Provide together with device. Deprecated legacy market input: send location_key instead. Still accepted for compatibility; no removal version is scheduled.
        - `cron_expression` string, nullable
        - `device` 'desktop' | 'mobile': Optional device selector. Provide with country when location_key is omitted; with location_key it overrides the current default device.
        - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron'
        - `jitter_minutes` integer: Whole-minute random delay from 0 to 120. Set 0 to disable jitter.
        - `location_key` string: Primary location reference: canonical country, region, or city key, optionally qualified with @language. Updates the default market from a canonical location key. Country and city are resolved from the location catalog; device defaults to the current default device when omitted.
        - `serp_depth` 10 | 20 | 50 | 100: Default number of SERP results scanned per rank check. Omitted keeps the stored depth.
        - `serp_stop_on_match` boolean: Set false to fetch the full configured depth for competitor snapshots.
        - `timezone` string: IANA time zone that anchors monthly and custom cron wall-clock schedules. Daily and weekly use a stable keyword-specific interval phase that timezone does not move.
        - `project_id` string, required
    - `draft` object, required
      - `review` ProjectDefaultsReview
        - `expected_source_hash` string, required
        - `expected_revision` string, required
        - `preview_token` string, required
        - `idempotency_key` string, required
        - `confirmed` true, required
      - `city` string, nullable: Optional city name resolved within country when location_key is omitted. Deprecated legacy market input: send location_key instead. Still accepted for compatibility; no removal version is scheduled.
      - `country` 'United States' | 'United Kingdom' | 'Canada' | 'Australia' | 'Germany' | 'France' | 'Spain' | 'Italy' | 'Netherlands' | 'Sweden' | 'Poland' | 'Ireland' | 'Portugal' | 'Belgium' | 'Switzerland' | 'Austria' | 'Denmark' | 'Norway' | 'Finland' | 'Brazil' | 'Mexico' | 'India' | 'Japan' | 'Singapore' | 'New Zealand' | 'South Africa' | 'United Arab Emirates', required: Optional country selector when location_key is omitted. Provide together with device. Deprecated legacy market input: send location_key instead. Still accepted for compatibility; no removal version is scheduled.
      - `cron_expression` string, nullable
      - `device` 'desktop' | 'mobile', required: Optional device selector. Provide with country when location_key is omitted; with location_key it overrides the current default device.
      - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron', required
      - `jitter_minutes` integer, required: Whole-minute random delay from 0 to 120. Set 0 to disable jitter.
      - `location_key` string, required: Primary location reference: canonical country, region, or city key, optionally qualified with @language. Updates the default market from a canonical location key. Country and city are resolved from the location catalog; device defaults to the current default device when omitted.
      - `serp_depth` 10 | 20 | 50 | 100, required: Default number of SERP results scanned per rank check. Omitted keeps the stored depth.
      - `serp_stop_on_match` boolean, required: Set false to fetch the full configured depth for competitor snapshots.
      - `timezone` string, required: IANA time zone that anchors monthly and custom cron wall-clock schedules. Daily and weekly use a stable keyword-specific interval phase that timezone does not move.
      - `project_id` string, required
    - `expected_source_hash` string, required
    - `expected_revision` string, required
    - `preview_token` string, required
    - `expires_at` string, date-time, required
    - `resolved` object, required
      - `location_key` string, required
      - `label` string, required
      - `language_code` string, required
      - `device` 'desktop' | 'mobile', required
    - `impact` object, required
      - `existing_target_retargets` 0, required
      - `new_targets` 0, required
      - `inherited_depth_targets` integer, required
      - `recurring_estimate` 'unchanged' | 'unknown', required
      - `scope_changed` boolean, required
      - `cadence_changed` boolean, required
    - `policy_ready` boolean, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Quote, source or command changed; Unsupported API version
- `428`: Current preview and explicit confirmation required
- `429`: Rate limited

## Changes

- **2026-10-19** `a6e1ec0dec82`: 2 breaking, 7 info
  - added the new path request parameter `project_id`
  - removed the media type `application/json` for the response with the status `409`
  - the endpoint scheme security `AppOAuth` was added to the API
  - media type `application/json` was changed to a more specific media type `application/problem+json` for the response status `400`
  - …5 more

[Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/projects/:project_id/defaults/patch.md)

---

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