> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update workspace settings

> Partially updates workspace settings. Every field is optional; an omitted field is left unchanged. Provide `display_name` to rename the workspace, `enforce_enabled_models` to toggle model enforcement, or `pii_redaction` to replace the workspace-default PII redaction plugin configuration.

<Note>
  **Related guide**: Workspace settings guide. See the [Workspace settings guide](/docs/ai-studio/organization/workspace-settings) for a walkthrough with examples.
</Note>


## OpenAPI

````yaml patch /v2/workspace-settings
openapi: 3.1.0
info:
  title: orq.ai API
  version: '2.0'
  description: orq.ai API documentation
servers:
  - url: https://my.orq.ai
security:
  - ApiKey: []
tags:
  - name: Chunking
    description: Split text into smaller chunks for retrieval and generation workflows.
  - name: File Systems
    description: >-
      Create and manage persistent file systems that agents and MCP clients read
      from and write to.
  - name: Knowledge Bases
    description: Create and manage knowledge bases used by agents and retrieval workflows.
  - name: Memory Stores
    description: Create and manage memory stores, memories, and memory documents.
  - name: Evals
    description: Run an evaluator against a conversation and its result
  - name: Logs
    description: >-
      OpenTelemetry log query API. Search, filter, aggregate, and facet log
      records ingested via OTLP.
  - name: Reporting
    description: >-
      GenAI reporting API over canonical analytics rollups. Accepts a metric
      name, time range, grain, group-by, and filters; returns a typed time
      series and optional totals.
  - name: Traces
    description: >-
      Query and inspect ingested trace data: search trace summaries, aggregate
      metrics, and read individual traces and their spans.
  - description: List models available through the AI Router.
    name: Models
  - name: Policies
  - name: Alerts
    description: >-
      Alerts evaluate a Reporting API metric on a fixed interval and fire
      notifications through notifiers when the value breaches a threshold. Each
      breach opens a trigger that tracks the incident until the value recovers.
  - name: Annotation Queues
    description: Annotation queues collect spans for human review.
  - name: API keys
    description: >-
      API keys authenticate programmatic access to the workspace. They expose
      opaque tokens, per-domain access grants, and budget and rate-limit
      constraints.
  - name: Audit Logs
    description: Audit logs record workspace entity changes and access-relevant events.
  - name: Budgets
    description: >-
      Budgets govern spend, token usage, and request rate across six scopes:
      workspace, project, identity, API key, provider, and model. Every
      applicable budget is enforced, and the most restrictive limit applies per
      dimension.
  - name: Files
    description: File upload and retrieval operations.
  - name: Guardrail Rules
    description: >-
      Guardrail Rules conditionally enforce evaluators and plugins for AI
      Gateway traffic. Rules may be scoped to a project or the whole workspace.
  - name: Hub
    description: Hub items are reusable templates available to a workspace.
  - name: Identities
    description: >-
      Identities represent end users from your system for usage and engagement
      tracking.
  - name: Management keys
    description: >-
      Management keys are workspace-scoped credentials that authenticate
      programmatic access to workspace administration surfaces (API keys,
      budgets). Unlike project-scoped API keys, a management key always operates
      at the workspace level.
  - name: MCP Gateway
    description: >-
      Register upstream MCP servers, discover and sync their tools, and assemble
      gateways that expose a curated tool surface to MCP clients.
  - name: Model Catalog
    description: >-
      Browse the orq.ai model catalog: every model orq offers, across every
      provider, with pricing, capabilities and benchmark data. List endpoints
      only return models that are not deprecated. This API is public, requires
      no authentication, and is rate limited to 120 requests per minute per IP.
      Responses carry a 5-minute cache-control max-age.
  - name: Notifiers
    description: Notifier destinations used to send delivery and workflow notifications.
  - name: Projects
    description: Projects organize resources within a workspace
  - name: Routing Rules
    description: >-
      Routing Rules conditionally select models and enforce request plugins for
      AI Gateway traffic. Rules are evaluated by ascending priority and may be
      scoped to a project or the whole workspace.
  - name: Threads
    description: Threads group related trace invocations and their aggregate usage
  - name: Skills
    description: >-
      Skills are modular instructions you can use to codify processes and
      conventions
  - name: Smart Routers
    description: >-
      Create and manage workspace Smart Routers. A Smart Router selects a model
      from an eligible pool for each request according to a quality, balanced,
      or cost profile.
  - name: Webhooks
    description: >-
      Create and manage webhooks that deliver workspace events to external HTTPS
      endpoints.
  - name: Workspaces
    description: >-
      A workspace is the tenant. Create is a user-session onboarding RPC; Get,
      List, and Update are the public management surface.
  - name: Workspace Security
    description: >-
      Workspace-level domain verification and IP allowlist controls. These
      operations are restricted to workspace administrators.
  - name: Workspace Settings
    description: >-
      Workspace-level settings managed with a workspace credential. A workspace
      is the tenant, so these settings are a singleton — there is nothing to
      create or delete, only read and update.
  - name: Responses
  - description: Run agents on a cron cadence. Minimum firing interval is 1 hour.
    name: Agent Schedules
  - name: Embeddings
  - name: Telemetry
    description: >-
      Unified query envelope for traces, metrics, and logs (ADR 0004). One
      request shape, one filter dialect, and one response shape per source,
      validated by a per-source registry.
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
paths:
  /v2/workspace-settings:
    patch:
      tags:
        - Workspace Settings
      summary: Update workspace settings
      description: >-
        Partially updates workspace settings. Every field is optional; an
        omitted field is left unchanged. Provide `display_name` to rename the
        workspace, `enforce_enabled_models` to toggle model enforcement, or
        `pii_redaction` to replace the workspace-default PII redaction plugin
        configuration.
      operationId: WorkspaceSettingsUpdate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceSettingsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateWorkspaceSettingsResponse'
components:
  schemas:
    UpdateWorkspaceSettingsRequest:
      type: object
      properties:
        display_name:
          type: string
          description: New workspace display name. Omit to keep the current name.
        enforce_enabled_models:
          type: boolean
          description: >-
            New value for the enforce-enabled-models flag. Omit to keep the
            current
             value.
        pii_redaction:
          allOf:
            - $ref: '#/components/schemas/PiiRedaction'
          description: >-
            Replacement workspace-default PII redaction configuration. Omit to
            leave
             the current PII redaction configuration unchanged; when present it fully
             replaces the stored pii_redaction object.
      description: >-
        UpdateWorkspaceSettingsRequest is a partial update: every field is
        optional
         and an omitted field is left unchanged.

         There is deliberately no `key` / `slug` field. The workspace slug is
         immutable through this service (it is embedded in resource URLs and API
         credentials), mirroring the dashboard's WorkspaceUpdateGuard, which rejects a
         `key` in the PATCH /workspaces/:key body. Do not add one.
    UpdateWorkspaceSettingsResponse:
      required:
        - settings
      type: object
      properties:
        settings:
          allOf:
            - $ref: '#/components/schemas/WorkspaceSettings'
          description: Updated workspace settings.
    PiiRedaction:
      required:
        - enabled
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the workspace-default PII redaction plugin is enabled.
        config:
          allOf:
            - $ref: '#/components/schemas/PiiRedactionConfig'
          description: Plugin configuration applied when enabled. Optional.
      description: >-
        PiiRedaction is the workspace-default configuration for the
        pii_redaction
         plugin: an enable flag plus the optional plugin config the gateway applies as
         a floor for requests that send no plugins of their own.
    WorkspaceSettings:
      required:
        - key
        - display_name
        - enforce_enabled_models
      type: object
      properties:
        key:
          type: string
          description: >-
            Read-only workspace key/slug. Returned for reference; it cannot be
            changed
             through this service.
        display_name:
          type: string
          description: Human-readable workspace display name.
        enforce_enabled_models:
          type: boolean
          description: Whether only workspace-enabled models may be served.
        pii_redaction:
          allOf:
            - $ref: '#/components/schemas/PiiRedaction'
          description: >-
            Workspace-default PII redaction plugin configuration. Omitted when
            the
             workspace has never configured it.
      description: WorkspaceSettings is the full settings state returned by Get and Update.
    PiiRedactionConfig:
      type: object
      properties:
        language:
          type: string
          description: |-
            Detector language. One of "en" or "nl"; omit for the gateway default
             ("en"). The valid entity catalog depends on this value.
        entities:
          type: array
          items:
            type: string
          description: |-
            Entity types to redact (e.g. "EMAIL_ADDRESS", "PERSON"). Values are
             validated against the entity catalog for `language`; omit to redact every
             type the detector finds.
        on_failure:
          type: string
          description: >-
            Behaviour when redaction cannot run: "block" (fail closed, the
            default) or
             "passthrough" (fail open, send the original text).
        threshold:
          type: number
          description: Detection confidence threshold in the [0, 1] range.
          format: double
      description: |-
        PiiRedactionConfig mirrors the workspace-default PII redaction plugin
         configuration. Every field is optional; the gateway applies its own
         defaults for unset fields.

         The stored value is validated on write using the same rules the gateway
         applies to live requests. Without that, an invalid workspace default
         would 400 every gateway call for the workspace, since the default plugin
         is injected into each request and validated there.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````