# List Rule/Workflow API

Fetch a catalog of rules or workflows in your Nected workspace, with powerful **filtering, sorting, and pagination** so you can build admin tables, sync catalogs to other systems, or quickly separate **published** vs **draft** entities.

### Authentication

All requests require your Nected API key:

```
Nected-API-Key: <YOUR_API_KEY>
```

### Endpoint

```
GET https://api.nected.ai/dev/{entityType}
```

#### Path Parameters

| Name       | Type   | Required | Description          |
| ---------- | ------ | -------- | -------------------- |
| entityType | string | Yes      | `rule` or `workflow` |

#### Headers

| Header         | Value               | Required |
| -------------- | ------------------- | -------- |
| Nected-API-Key | Your API key string | Yes      |

### Query Parameters (Filtering, Sorting, Pagination)

> Use these parameters to narrow the list and control the order/page size.

#### Pagination

| Param     | Type   | Default | Description                          |
| --------- | ------ | ------- | ------------------------------------ |
| `page`    | number | `1`     | 1-based page index                   |
| `perPage` | number | `10`    | Items per page (use sensible bounds) |

#### Sorting

| Param     | Type   | Allowed                                               | Description      |
| --------- | ------ | ----------------------------------------------------- | ---------------- |
| `sortBy`  | string | `name`, `status`, `updatedAt`, `createdAt`, `version` | Field to sort on |
| `sortDir` | string | `asc` \| `desc`                                       | Sort direction   |

#### Common Filters

| Param           | Type             | Examples / Notes                                                                         |
| --------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `name`          | string           | Exact or prefix match (e.g., `name=Order*`)                                              |
| `status`        | string \| array  | `draft` \| `published` (single) or comma-separated list (e.g., `status=draft,published`) |
| `type`          | string           | For rules, e.g., `decisionTable`, `ruleset`; for workflows: `workflow`                   |
| `version`       | string           | E.g., `v1`, `v2`                                                                         |
| `q`             | string           | Free-text search across name/description (lightweight search)                            |
| `tags`          | string           | Comma-separated tags; returns entities having **any** of the tags                        |
| `createdBy`     | string (UUID)    | Filter by creator                                                                        |
| `updatedBy`     | string (UUID)    | Filter by last updater                                                                   |
| `createdAtFrom` | ISO8601 datetime | Lower bound for creation time (`createdAt>=…`)                                           |
| `createdAtTo`   | ISO8601 datetime | Upper bound for creation time (`createdAt<=…`)                                           |
| `updatedAtFrom` | ISO8601 datetime | Lower bound for last update (`updatedAt>=…`)                                             |
| `updatedAtTo`   | ISO8601 datetime | Upper bound for last update (`updatedAt<=…`)                                             |

> **Notes**
>
> * Unless noted otherwise, multiple filters are **AND**-ed.
> * `status` and `tags` accept comma-separated values to represent **OR** within that field.
> * `name` supports prefix wildcard via `*` at the end (implementation detail: treat as “starts with”).
> * Date-time values should be RFC 3339/ISO 8601 (e.g., `2025-10-16T10:00:00Z`).

***

### Examples

#### 1) List all published rules, newest first

**cURL**

```bash
curl --location "https://api.nected.ai/dev/rule?status=published&sortBy=updatedAt&sortDir=desc&page=1&perPage=20" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

**JavaScript (fetch)**

```js
const url = new URL("https://api.nected.ai/dev/rule");
url.search = new URLSearchParams({
  status: "published",
  sortBy: "updatedAt",
  sortDir: "desc",
  page: "1",
  perPage: "20",
}).toString();

const res = await fetch(url, { headers: { "Nected-API-Key": "<YOUR_API_KEY>" }});
const data = await res.json();
```

#### 2) Find drafts whose name starts with “Order”, updated in last 7 days

```bash
# Assume "now" is 2025-10-16T00:00:00Z
curl --location "https://api.nected.ai/dev/rule?status=draft&name=Order*&updatedAtFrom=2025-10-09T00:00:00Z" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

#### 3) Workflow catalog with free-text search and tags

```bash
curl --location "https://api.nected.ai/dev/workflow?q=discount&tags=seasonal,promo&sortBy=name&sortDir=asc" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

#### 4) Multi-status filter and version pin

```bash
curl --location "https://api.nected.ai/dev/rule?status=draft,published&version=v2" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

### Sample Response

```json
{
  "data": {
    "Pagination": {
      "perPage": 10,
      "totalPage": 4,
      "currentPage": 1,
      "totalRecord": 34
    },
    "entities": [
      {
        "entityId": "11111111-aaaa-bbbb-cccc-222222222222",
        "name": "OrderValidationRules",
        "description": "Rules for validating customer orders",
        "type": "decisionTable",
        "status": "draft",
        "version": "v1",
        "endpoints": "https://nected.ai/nected/rule/11111111-aaaa-bbbb-cccc-222222222222",
        "tags": ["orders","validation"],
        "createdAt": "2025-09-04T10:22:18Z",
        "updatedAt": "2025-10-12T15:03:42Z",
        "createdBy": "5c0d...c2e",
        "updatedBy": "8a11...9fd"
      }
    ]
  },
  "code": "success",
  "message": "Success."
}
```

> **Field notes**
>
> * `tags`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` may appear if available for your entities.

### Field Reference

#### `data.Pagination`

* `perPage` (number): Items per page.
* `totalPage` (number): Total pages.
* `currentPage` (number): Current 1-based page.
* `totalRecord` (number): Total matching records.

#### `data.entities[]`

* `entityId` (string): Unique ID.
* `name` (string): Display name.
* `description` (string): Short description.
* `type` (string): For rules, e.g., `decisionTable`, `ruleset`; for workflows: `workflow`.
* `status` (string): `draft` | `published`.
* `version` (string): Version label.
* `endpoints` (string): Console URL for the entity.
* `tags` (string\[]): Optional labels.
* `createdAt`, `updatedAt` (ISO8601): Timestamps.
* `createdBy`, `updatedBy` (string): User IDs.

### Error Codes

| HTTP | Code                    | Meaning                 | Action                                |
| ---- | ----------------------- | ----------------------- | ------------------------------------- |
| 401  | UNAUTHORIZED            | Missing/invalid API key | Check `Nected-API-Key`.               |
| 404  | NOT\_FOUND              | Unknown `entityType`    | Use `rule` or `workflow`.             |
| 429  | TOO\_MANY\_REQUESTS     | Rate limit exceeded     | Backoff + retry with jitter.          |
| 500  | INTERNAL\_SERVER\_ERROR | Unexpected error        | Retry; contact support if persistent. |

### Tips & Best Practices

* **Paginate aggressively** in UI tables (`perPage=20/50`) and **sort by `updatedAt desc`** to surface the most recent edits first.
* Use **free-text `q`** for quick searches and pair with **exact filters** (`status`, `version`) for precision.
* For **audits**, filter by `updatedAtFrom/To` and/or `updatedBy` to see who changed what recently.
* **Cache** list responses by filter set and invalidate on create/update to keep dashboards snappy.