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

# Custom Statuses

> The Custom Statuses API lets you define the custom session statuses your team works with, and read or set the custom status on any session.

Every session has one of three built-in statuses: `open`, `closed_resolved`, or `closed_unresolved`. A custom status refines one of them with a name your team recognizes, such as "Waiting on customer" or "Escalated to engineering", plus an optional customer-facing label, color, and icon. This API manages those definitions and reads or sets the custom status on a session.

## Key Concepts

* **Custom status** — A named refinement of a built-in status. Each one has a `parent_status`; applying it to a session moves the session to that built-in status
* **`sub_status_id`** — Every session object carries the id of its custom status, or `null` when only the built-in status applies. Resolve ids with the list endpoint
* **Applying and clearing** — Set a session's custom status with `PUT /chat/sessions/{session_id}/sub-status`; clear it with `DELETE` on the same path. Clearing keeps the built-in status exactly as it is
* **Filtering** — `POST /chat/sessions/filter` accepts `sub_status_ids` to find sessions in any of the given custom statuses
* **Customer-facing fields** — `display_name` and `display_description` are what customers may see; `name` and `description` are for your team only
* **Timeline** — Every set and clear leaves an event in the session history, attributed to the API

## Available Endpoints

<CardGroup>
  <Card title="List Custom Statuses" icon="list" href="./list">
    List every custom status in your organization
  </Card>

  <Card title="Get Custom Status" icon="eye" href="./get">
    Fetch one custom status by id
  </Card>

  <Card title="Create Custom Status" icon="plus" href="./create">
    Define a new custom status under a built-in one
  </Card>

  <Card title="Update Custom Status" icon="pen" href="./update">
    Change any subset of a custom status
  </Card>

  <Card title="Delete Custom Status" icon="trash" href="./delete">
    Remove a custom status
  </Card>

  <Card title="Set Session Custom Status" icon="circle-check" href="../chat-sessions/sub_status_set">
    Apply a custom status to a session
  </Card>

  <Card title="Clear Session Custom Status" icon="circle-xmark" href="../chat-sessions/sub_status_clear">
    Remove the custom status from a session
  </Card>
</CardGroup>