---
title: "Update Workspace"
method: PATCH
path: "/api/v1/workspace"
tags: ["workspace"]
---

# Update Workspace

`PATCH /api/v1/workspace`

Update workspace settings. Requires workspace admin for the name field.

All fields are optional. Only provided fields are updated.

## Request body

- WorkspaceUpdateRequest — Request model for updating workspace settings. All fields are optional -- only provided fields are updated.
  - `name` string, nullable — New name for the workspace
  - `avatar_color` string, nullable — Avatar color name for the workspace. Set to null to remove.

## Response `200`

Successful Response

- WorkspaceResponse — Response model for workspace details.
  - `id` string, uuid, required
  - `name` string, required
  - `avatar_color` string, nullable
  - `created_at` string, date-time, nullable
  - `budget_authority` 'credits' | 'paid_balance', required — Which budget a metered run draws down. Two members, because there are two budgets. Free usage and paid usage are the same balance on the same account, spent at the same prices and refused by the same check; what a workspace paid for that balance decides what its refusal offers next, not how the run is admitted. A third member for the free tier is what let the two drift — different prices, different exemptions, different per-run sizing — while both claimed to meter usage.
  - `credit_balance` CreditBalance, required — Credit balance breakdown for a workspace. Uses pool accounting: total is the credits ever granted (never decremented), used is cumulative consumption, remaining = total - used.
    - `total` integer, required
    - `used` integer, required
    - `remaining` integer, required
  - `member_count` integer, required
  - `feature_toggles` object
  - `workspace_type` 'standard' | 'discovery', required
  - `discovery_allowance` DiscoveryAllowanceCustomerProjection — Customer-safe allowance state with no internal cost detail.
    - `status` 'available' | 'near_limit' | 'exhausted' | 'unavailable', required
    - `episode_key` string, uuid, nullable
    - `remaining_percent` integer, nullable, required
    - `display_remaining_percent` string, nullable, required
  - `on_free_plan` boolean
  - `paid_balance` PaidBalanceCustomerProjection — Customer-safe view of a subscribed workspace's spendable balance. Plan usage is a share, never dollars. The only dollar figure is ``paid_overage_usd``: overage the customer explicitly bought, which only a confirmed payment can add. It is absent, not zero, when they bought none, so an overrun past the plan never reads as a dollar debt. ``includes_given_usage`` says usage staff gave is part of the share, and nothing more. It carries no amount on purpose: a top-up moves the share, and an amount beside it would price in dollars what the customer never bought. ``status`` rides along because an admitted turn on a past-due account is otherwise indistinguishable from a healthy one — the refusal payload can only carry the warning once work is already being refused, which is after the point of warning anyone. ``spendable_now`` states whether the balance can be spent, rather than leaving a client to re-derive it from the status. A balance survives the statuses that refuse every turn, so a client deciding for itself which those are holds a second copy of ``keeps_paid_access`` that nothing keeps in step.
    - `status` 'pending' | 'active' | 'past_due' | 'unpaid' | 'cancelled', required — Subscription state as MAIA understands it, not as Stripe reports it. ``PAST_DUE`` is the retry window: full access with a visible warning. ``UNPAID`` is that window exhausted — paid work refuses until payment succeeds, but the subscription has not ended, so purchased usage is kept. ``CANCELLED`` is paid access ended; only this transition expires it.
    - `plan_usage` PlanUsageShare, required — What is left of a plan's usage, as a share of it and never as dollars. Plan usage is disclosed the same way whoever paid for it, including any allowance MAIA grants on top of a subscription: the customer did not buy those dollars one by one, so a dollar figure would quote them a price they never agreed to. Shaped as the free allowance's measured states so one meter renders both.
      - `status` 'available' | 'near_limit' | 'exhausted', required
      - `remaining_percent` integer, required
      - `display_remaining_percent` string, required
    - `paid_overage_usd` string, nullable, required
    - `display_paid_overage` string, nullable, required
    - `includes_given_usage` boolean
    - `spendable_now` boolean, required
  - `national_county_coverage` boolean
  - `upload_limits` UploadLimits, required — Byte caps the client checks before an upload leaves the browser. Served rather than restated client-side so the enforced number has one home. A file over the hosting platform's request ceiling is refused before the server's own cap can run, and that refusal reaches the browser without CORS headers — unreadable to the page — so the browser is the only place the size can be explained.
    - `structured_bytes` integer, required
    - `pdf_bytes` integer, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-19** `8fb358001d37` — 1 info
  - added the optional property `paid_balance/anyOf[subschema #1: PaidBalanceCustomerProjection]/includes_given_usage` to the response with the `200` status
- **2026-09-18** `73f618ba0a7e` — 1 info
  - added the optional property `national_county_coverage` to the response with the `200` status
- **2026-09-16** `95495ef535bc` — 2 warning
  - removed the optional property `auto_dial_enabled` from the response with the `200` status
  - removed the optional property `dial_agent_settings` from the response with the `200` status
- **2026-09-15** `499d0b94aa94` — 2 breaking, 3 info
  - removed the required property `paid_balance/anyOf[subschema #1: PaidBalanceCustomerProjection]/display_spendable` from the response with the `200` status
  - removed the required property `paid_balance/anyOf[subschema #1: PaidBalanceCustomerProjection]/spendable_usd` from the response with the `200` status
  - added the required property `paid_balance/anyOf[subschema #1: PaidBalanceCustomerProjection]/display_paid_overage` to the response with the `200` status
  - added the required property `paid_balance/anyOf[subschema #1: PaidBalanceCustomerProjection]/paid_overage_usd` to the response with the `200` status
  - …1 more
- …earlier changes not shown

[Full history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/workspace/patch.md)

---

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