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

# Update Client Workspace

> Updates a client workspace: name, limits, external reference, or a mid-cycle credit reset

Available on agency plans. The API token must belong to the agency owner.

Only the fields you send are changed. Two common flows:

* **Raise credits mid-cycle**: send a higher `message_limit`. The client keeps their usage and gains the difference.
* **Plan change with a credit reset**: send the new `message_limit` together with `reset_credits: true`. The client's usage counter restarts immediately, so their remaining credits become the full new limit, up to your agency plan's remaining monthly credits. Nothing carries over.

Limits apply from the next message or source the client uses. Message credits also reset automatically at the start of each calendar month.

## Path Parameters

| Name         | Type   | Description                     |
| ------------ | ------ | ------------------------------- |
| client\_id\* | String | The ID of the client workspace. |

## Headers

| Name            | Type   | Description                                                                            |
| --------------- | ------ | -------------------------------------------------------------------------------------- |
| Accept\*        | String | application/json                                                                       |
| Authorization\* | String | Bearer {api_token}                                                                     |
| Content-Type\*  | String | application/json                                                                       |
| Idempotency-Key | String | Optional. When set, retrying with the same key and body returns the original response. |

## Body Parameters

| Name                | Type    | Description                                                                                                                                                                                               |
| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                | String  | The client workspace name.                                                                                                                                                                                |
| external\_reference | String  | Your own identifier for this client. Send `null` to clear it.                                                                                                                                             |
| message\_limit      | Integer | Monthly message credit limit. Send `null` to remove the client-level limit.                                                                                                                               |
| source\_limit       | Integer | Source limit. Send `null` to remove the client-level limit.                                                                                                                                               |
| chatbot\_limit      | Integer | Maximum number of AI agents. Send `null` to remove the client-level limit.                                                                                                                                |
| reset\_credits      | Boolean | When `true`, the client's usage counter restarts now and their remaining credits become the full `message_limit` (or the existing limit when `message_limit` is omitted). Use for mid-cycle plan changes. |

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.sitespeak.ai/v1/agency/clients/{client_id}" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "message_limit": 5000,
      "reset_credits": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sitespeak.ai/v1/agency/clients/{client_id}',
    {
      method: 'PATCH',
      headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        message_limit: 5000,
        reset_credits: true
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

## Response

Returns the updated client workspace. After a credit reset, `credits_reset_at` holds the reset time and `usage.messages` starts again from 0.

<Tabs>
  <Tab title="200 Success">
    ```json theme={null}
    {
      "client": {
        "id": "dfcee2e1-3ace-41c6-9803-fb2b7c7cdfc7",
        "name": "Acme Inc",
        "external_reference": "billing-account-1001",
        "limits": {
          "chatbots": 2,
          "sources": 50,
          "messages": 5000
        },
        "usage": {
          "chatbots": 1,
          "sources": 12,
          "messages": 0
        },
        "messages_remaining": 5000,
        "credits_reset_at": "2026-07-22T19:32:46+00:00",
        "created_at": "2026-07-22T19:31:40+00:00"
      }
    }
    ```
  </Tab>

  <Tab title="403 Not an agency account">
    Returns when the API token does not belong to an agency account owner.
  </Tab>

  <Tab title="404 Not found">
    Returns when no client workspace with this ID exists in your agency.
  </Tab>

  <Tab title="422 Validation error">
    Returns when a field is invalid.
  </Tab>
</Tabs>