> ## 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.

# Pause Client Workspace

> Pauses a client workspace with a hard or soft stop

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

Use this when a client cancels or fails payment. You choose the stop behavior per call:

* **hard**: the client's AI agents stop answering right away and the widget no longer loads on their site.
* **soft**: the client's AI agents keep answering until their remaining message credits run out. Credits are not refilled while paused.

In both modes the monthly credit reset skips the workspace until you resume it. Calling pause again with a different mode switches the mode.

## 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 | A unique key for this request. Retrying with the same key and body returns the original response. |

## Body Parameters

| Name   | Type   | Description       |
| ------ | ------ | ----------------- |
| mode\* | String | `hard` or `soft`. |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.sitespeak.ai/v1/agency/clients/{client_id}/pause" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: pause-2026-08-01-client-1001" \
    -d '{
      "mode": "hard"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sitespeak.ai/v1/agency/clients/{client_id}/pause',
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'pause-2026-08-01-client-1001'
      },
      body: JSON.stringify({
        mode: 'hard'
      })
    }
  );

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

## Response

Returns the client workspace with its new status. After a hard pause, `messages_remaining` is `0` while the pause lasts.

<Tabs>
  <Tab title="200 Success">
    ```json theme={null}
    {
      "client": {
        "id": "dfcee2e1-3ace-41c6-9803-fb2b7c7cdfc7",
        "name": "Acme Inc",
        "external_reference": "billing-account-1001",
        "status": "paused",
        "pause_mode": "hard",
        "paused_at": "2026-08-01T09:15:00+00:00",
        "limits": {
          "chatbots": 2,
          "sources": 50,
          "messages": 5000
        },
        "usage": {
          "chatbots": 1,
          "sources": 12,
          "messages": 1240
        },
        "messages_remaining": 0,
        "credits_reset_at": null,
        "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 `mode` is missing or not `hard` or `soft`.
  </Tab>
</Tabs>