---
title: "Update workspace preferences"
method: PATCH
path: "/v1/workspace"
tags: ["Account"]
---

# Update workspace preferences

`PATCH /v1/workspace`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/workspace`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `account:manage`)

credits.low fires when the balance drops below low_balance_credits. The default is 250. Send null to restore the default. marketing_opt_in stores the product-updates choice. lifecycle_suppressed stops follow-up emails. Send at least one of these fields.

Scope: `account:manage`. Acts on the account; keys bound to a customer are refused.

## Headers

- `Idempotency-Key` string
- `RecruitMCP-Version` '2026-10-13'

## Request body

- object
  - `low_balance_credits` integer, nullable: Whole credits. Null restores the default.
  - `marketing_opt_in` boolean: Product updates and tips. Omit to leave the stored choice.
  - `lifecycle_suppressed` boolean: Stop follow-up emails for this workspace. Omit to leave the stored flag.

## Response `200`

The workspace, with the change applied.

- Workspace
  - `id` string, required: ws_… when the request acts on the account. cus_… when RecruitMCP-Customer or a bound key selects a customer.
  - `object` 'workspace', required
  - `name` string
  - `email` string, nullable
  - `first_name` string, nullable: Owner first name from signup, or null. Not taken from the workspace name.
  - `account_id` string, required: Always the billing account, ws_…. Credits, keys, and webhooks stay on this id even when id is a customer.
  - `customer` Customer: A sub-workspace for one of your own customers: its own seen register, lists, suppressions, and cap. Credits come from your account.
    - `id` string, required
    - `object` 'customer', required
    - `name` string, required
    - `external_id` string, nullable: Your id for this tenant.
    - `metadata` object
    - `daily_cap_credits` integer, nullable: Credits this customer may spend per UTC day.
    - `status` 'active' | 'disabled', required
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `balance_credits` integer, nullable, required: Account balance. A customer-bound key gets that customer's remaining daily cap, or null when the customer has no cap.
  - `low_balance_credits` integer, required: credits.low fires when the balance drops below this. Default 250.
  - `plan` 'free' | 'starter' | 'growth' | 'scale' | 'payg', required: Current plan of the account. free without a subscription, payg with developer billing on. A canceled subscription is free.
  - `marketing_opt_in` boolean, required: True when this workspace asked for product updates and tips.
  - `marketing_consent_at` string, date-time, nullable, required: When the product-updates choice was stored.
  - `marketing_consent_source` 'signup' | 'console', nullable, required: Where the product-updates choice was made.
  - `marketing_consent_text_version` string, nullable, required: Version of the checkbox sentence stored with the choice.
  - `lifecycle_suppressed` boolean, required: True stops every follow-up email for this workspace.
  - `api_key` object, required
    - `id` string
    - `name` string, nullable
    - `prefix` string
    - `kind` 'secret' | 'oauth'
    - `scopes` string[]
    - `daily_cap_credits` integer, nullable
    - `approval_threshold_credits` integer, nullable
    - `approval_threshold_enrollments` integer, nullable: Null when unset. HTTP then has no enrollment threshold. MCP uses 25 scheduled enrollments.
    - `expires_at` string, date-time, nullable
  - `api_version` string, required: RecruitMCP-Version this request runs under.

## Other responses

- `400`: `invalid_request` (do not retry): A field is missing or has a value this endpoint does not accept. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `403`: `forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded.

## Changes

- **2026-10-20** `ad27b35513a6`: 4 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `429`

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/workspace/patch.md)

---

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