# Get Entity Detail API

Retrieve the **complete definition** of a specific rule or workflow by ID. Use this when you need to inspect input parameters, versions, status, the workflow graph, or to power an entity details page before invoking or updating it.

### Authentication

All requests require your Nected API key:

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

### Endpoint

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

#### Path Parameters

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

#### Headers

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

### Optional Query Parameters

Use these to control the level of detail and related metadata you want back.

| Param     | Type         | Allowed / Example                             | Description                                                       |
| --------- | ------------ | --------------------------------------------- | ----------------------------------------------------------------- |
| `view`    | string       | `summary` \| `full` (default: `full`)         | Controls payload verbosity (e.g., omit large blobs in `summary`). |
| `include` | string (CSV) | `params,data,versions,audit,stats,references` | Adds optional sections to the response if available.              |
| `version` | string       | `v1`, `v2`, `latest`, `published`             | Fetch a specific or logical version for the entity.               |
| `expand`  | string (CSV) | `nodes.operator,params.constraints`           | Expand nested fields (advanced; when supported).                  |

> **Notes**
>
> * If `version` is omitted, the API returns the **current working** version for the entity.
> * `include` values are additive. Unknown values are ignored.
> * `view=summary` is useful for table rows or side panels where you don’t need the full graph.

### Examples

#### 1) Get a rule (full payload)

```bash
curl --location "https://api.nected.ai/dev/rule/11111111-aaaa-bbbb-cccc-222222222222" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

#### 2) Get a workflow with graph and audit slice

```bash
curl --location "https://api.nected.ai/dev/workflow/33333333-aaaa-bbbb-cccc-444444444444?include=data,audit&view=full" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

#### 3) Pin to the published version of a rule

```bash
curl --location "https://api.nected.ai/dev/rule/11111111-aaaa-bbbb-cccc-222222222222?version=published" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

#### 4) Fetch summary for quick preview (faster)

```bash
curl --location "https://api.nected.ai/dev/workflow/33333333-aaaa-bbbb-cccc-444444444444?view=summary" \
  --header "Nected-API-Key: <YOUR_API_KEY>"
```

### Sample Response (Rule)

```json
{
  "data": {
    "entityId": "11111111-aaaa-bbbb-cccc-222222222222",
    "name": "OrderValidationRules",
    "description": "Rules for validating customer orders",
    "type": "decisionTable",
    "params": [
      {
        "name": "customer_id",
        "dataType": "numeric",
        "type": "dataSet",
        "isOptional": false,
        "isNullable": false,
        "isCaseSensitive": false
      },
      {
        "name": "item_details",
        "dataType": "json",
        "type": "primitive",
        "isOptional": false,
        "isNullable": false,
        "isCaseSensitive": false
      }
    ],
    "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",
    "stats": {
      "lastRunAt": "2025-10-14T07:31:10Z",
      "runCount30d": 142
    }
  },
  "code": "success",
  "message": "Success."
}
```

### Sample Response (Workflow)

```json
{
  "data": {
    "entityId": "33333333-aaaa-bbbb-cccc-444444444444",
    "name": "DiscountWorkflow",
    "description": "Workflow for applying seasonal discounts",
    "type": "workflow",
    "data": {
      "nodes": [
        {
          "id": "1",
          "type": "trigger",
          "name": "API Trigger",
          "settings": {
            "authType": "private",
            "isEnabled": true
          }
        },
        {
          "id": "2",
          "type": "sleepNode",
          "name": "Wait Node",
          "settings": {
            "durationValue": 5,
            "durationUnit": "m"
          }
        }
      ],
      "edges": [
        { "id": "edge_1", "source": "1", "target": "2", "type": "smoothEdge" }
      ]
    },
    "status": "published",
    "version": "v2",
    "endpoints": "https://nected.ai/nected/workflow/33333333-aaaa-bbbb-cccc-444444444444",
    "tags": ["discount","promo"],
    "createdAt": "2025-07-22T08:01:11Z",
    "updatedAt": "2025-10-10T18:47:22Z",
    "createdBy": "f2aa...73b",
    "updatedBy": "8a11...9fd",
    "audit": {
      "lastPublisher": "8a11...9fd",
      "lastPublishedAt": "2025-10-10T18:47:22Z"
    }
  },
  "code": "success",
  "message": "Success."
}
```

***

### Field Reference

#### Common fields

* `entityId` (string): Unique ID of the entity.
* `name` (string): Display name.
* `description` (string): Summary of purpose.
* `type` (string): `decisionTable`, `workflow`, etc.
* `status` (string): `draft` | `published`.
* `version` (string): Version label. May reflect requested `version` query.
* `endpoints` (string): Console URL for quick access.
* `tags` (string\[]): Optional labels.
* `createdAt`, `updatedAt` (ISO8601): Timestamps.
* `createdBy`, `updatedBy` (string): User IDs.

#### Rule-specific

* `params` (array): Input schema for rule evaluation.
  * `name` (string)
  * `dataType` (string) — e.g., `string`, `numeric`, `boolean`, `json`, `array`.
  * `type` (string) — e.g., `primitive`, `dataSet`.
  * `isOptional` (bool)
  * `isNullable` (bool)
  * `isCaseSensitive` (bool)
* `stats` (object, optional): Lightweight usage statistics if requested via `include=stats`.

#### Workflow-specific

* `data` (object): Graph definition.
  * `nodes[]`: Node list with `id`, `type`, `name`, and node `settings`.
  * `edges[]`: Connections with `id`, `source`, `target`, `type`.
* `audit` (object, optional): Publishing metadata when requested via `include=audit`.

### Error Codes

| HTTP | Code                    | Meaning                 | Action                                |
| ---- | ----------------------- | ----------------------- | ------------------------------------- |
| 401  | UNAUTHORIZED            | Missing/invalid API key | Check `Nected-API-Key`.               |
| 404  | NOT\_FOUND              | Entity not found        | Verify `entityType` and `entityId`.   |
| 409  | CONFLICT                | Version conflict        | Adjust `version` selection.           |
| 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

* Prefer `view=summary` for lists/sidebars; fetch `view=full&include=data` only when rendering a full details page.
* When showing historical snapshots, pin with `version=published` or a specific `vX` to avoid drift.
* Use `include=params` for rule input forms and validation UIs; use `include=data` for workflow canvases.
* Cache entity details by `entityId+version` and invalidate on update/publish events.