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

# List Workflows

> Retrieve the workflows the access token's user may see or request

## Endpoint

```
GET /v2/workflows
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `workflows:read`

## Query Parameters

| Parameter     | Type    | Required | Description                                       |
| ------------- | ------- | -------- | ------------------------------------------------- |
| `active_only` | boolean | No       | Only return active workflows. Defaults to `false` |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/v2/workflows?active_only=true" \
    -H "Authorization: Bearer your_access_token"
  ```

  ```python Python theme={null}
  import requests

  url = "https://platform.chamelio.ai/v2/workflows"
  headers = {
      "Authorization": "Bearer your_access_token"
  }
  params = {
      "active_only": True
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://platform.chamelio.ai/v2/workflows?active_only=true', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_access_token'
    }
  });

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

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "workflows": [
    {
      "workflow_id": "vendor_contract_review",
      "workflow_name": "Vendor Contract Review",
      "version": 1,
      "description": "Review and approve vendor contracts",
      "is_active": true,
      "variables": [
        {
          "variable_id": "contract_file",
          "variable_name": "Contract Document",
          "type": "file",
          "required": true,
          "description": "The vendor contract to review"
        },
        {
          "variable_id": "vendor_name",
          "variable_name": "Vendor Name",
          "type": "text",
          "required": true,
          "description": "Name of the vendor"
        }
      ]
    }
  ],
  "total": 1
}
```

### Response Fields

| Field       | Type    | Description                                  |
| ----------- | ------- | -------------------------------------------- |
| `workflows` | array   | Workflow schemas the user may see or request |
| `total`     | integer | Number of workflows returned                 |

### Workflow Schema Fields

| Field           | Type    | Description                              |
| --------------- | ------- | ---------------------------------------- |
| `workflow_id`   | string  | Unique identifier for the workflow       |
| `workflow_name` | string  | Human-readable workflow name             |
| `version`       | integer | Workflow version number                  |
| `description`   | string  | Description of what the workflow does    |
| `is_active`     | boolean | Whether the workflow is currently active |
| `variables`     | array   | List of input variables for the workflow |

## Error Responses

### 400 Bad Request

Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.

```json theme={null}
{
  "detail": "client_credentials tokens are not associated with a user"
}
```

### 401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token does not carry the required scope.

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: workflows:read"
}
```

### 429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 500 Internal Server Error

Returned when the request fails due to a server error.

```json theme={null}
{
  "detail": "Failed to list workflows"
}
```

## Notes

<Info>
  This endpoint returns only the workflows the access token's user has permission on - not every
  workflow in the organization. Two users authorizing the same application can legitimately see
  different lists.
</Info>

<Info>
  Use the `workflow_id` and `version` from this response to get the full workflow schema or initiate a
  workflow instance.
</Info>

<Tip>
  Set `active_only=true` to filter out deprecated or inactive workflows and only see workflows you can
  currently use.
</Tip>

## Use Cases

This endpoint is useful for:

* **Workflow discovery** - Show a user the workflows they can actually start
* **Dynamic integrations** - Build applications that adapt to available workflows
* **User interfaces** - Populate workflow selection dropdowns per user
* **Permission-aware automation** - Avoid attempting workflows the user cannot request