---
source_url: https://www.pubnub.com/docs/analytics/decisions/rest-api
title: Illuminate REST API
updated_at: 2026-09-30T07:20:08.000Z
---

# Illuminate REST API

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

The Illuminate REST API gives programmatic access to create and manage Business Objects, Metrics, Decisions, Dashboards, and Queries. It is accessed through the PubNub Admin API.

For full per-endpoint request and response schemas, see the [Admin API reference](https://www.pubnub.com/docs/admin-api/illuminate-introduction.md).

## Authentication

Illuminate REST endpoints use Admin API key authentication. Session-based authentication is not used.

**Base URL:** `https://admin-api.pubnub.com/v2/illuminate/`

### Required headers

Include these headers on every request:

| Header | Value |
| --- | --- |
| `Authorization` | Your Admin API key |
| `PubNub-Version` | `2026-02-09` |
| `Content-Type` | `application/json` |

### Authentication example

```bash
curl --request GET \
  --url 'https://admin-api.pubnub.com/v2/illuminate/<resource>' \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "PubNub-Version: 2026-02-09" \
  -H "Content-Type: application/json"
```

## Conventions

### IDs

Every create response returns stable IDs (for example, `businessObjectId`, `metricId`, `decisionId`). Use them to create dependent resources and when updating rules.

* `fields[].id` from a Business Object response is reused as `measureId`, `dimensionIds`, and `inputFields[].sourceId` in Metrics and Decisions.
* `actions[].id` from a Decision response is required when configuring rules and resetting execution limits.

### Timestamps

All timestamps are ISO 8601 in UTC, for example `2025-08-21T19:27:01Z`. The time component is optional when specifying date ranges.

### Cascading deletion

Deleting a Business Object also permanently deletes its Metrics, Decisions, and Dashboard charts.

### Business Object activation

A Business Object can be created with `isActive: false` without subscribe keys. To activate it (`isActive: true`), at least one subscribe key must be included in `subkeys`.

## Endpoint index

| Resource | Operation | Method | Endpoint |
| --- | --- | --- | --- |
| Business Objects | Create | POST | `/business-objects` |
|  | List | GET | `/business-objects` |
|  | Get | GET | `/business-objects/{id}` |
|  | Update | PUT | `/business-objects/{id}` |
|  | Delete | DELETE | `/business-objects/{id}` |
| Metrics | Create | POST | `/metrics` |
|  | List | GET | `/metrics` |
|  | Get | GET | `/metrics/{id}` |
|  | Update | PUT | `/metrics/{id}` |
|  | Delete | DELETE | `/metrics/{id}` |
| Decisions | Create | POST | `/decisions` |
|  | List | GET | `/decisions` |
|  | Get | GET | `/decisions/{id}` |
|  | Update | PUT | `/decisions/{id}` |
|  | Delete | DELETE | `/decisions/{id}` |
|  | Reset action limits | POST | `/decisions/{id}/action-limit-reset` |
|  | Retrieve action log | GET | `/decisions/{id}/action-log` |
| Dashboards | Create | POST | `/dashboards` |
|  | List | GET | `/dashboards` |
|  | Get | GET | `/dashboards/{id}` |
|  | Update | PUT | `/dashboards/{id}` |
|  | Delete | DELETE | `/dashboards/{id}` |
| Queries | Execute ad-hoc | POST | `/queries/execute` |
|  | Create | POST | `/queries` |
|  | List | GET | `/queries` |
|  | Get | GET | `/queries/{id}` |
|  | Update | PUT | `/queries/{id}` |
|  | Delete | DELETE | `/queries/{id}` |
|  | Execute saved | POST | `/queries/{id}/execute` |
|  | Get fields | GET | `/queries/{id}/fields` |
|  | Create predefined Decision | POST | `/queries/{id}/predefined-decisions` |

## Data types

### Business Object field types

| Field | `jsonFieldType` value | Notes |
| --- | --- | --- |
| Short text | `TEXT` |  |
| Long text | `TEXT_LONG` | A `String (Max)` field holds text up to 1,000 characters long. A Business Object can include up to 5 `String (Max)` fields. |
| Number | `NUMERIC` | Used as a measure in metrics. |
| Timestamp | `TIMESTAMP` | ISO 8601 format, for example `2025-08-21T19:27:01Z`. |
| Derived (duration) | `NUMERIC` (derived) | Computed from two timestamp fields using `TIME_DIFF`. |

### Business Object field sources

| `source` value | Description |
| --- | --- |
| `JSONPATH` | Value extracted from a JSON path in the message payload. |
| `DERIVED` | Value computed from other fields. Supports `TIME_DIFF` only. |

### Dimensions and measures

When creating Metrics, fields are used in two roles:

| Role | Field type | Used as |
| --- | --- | --- |
| Measure | `NUMERIC` | The value being aggregated (sum, average, etc.) |
| Dimension | `TEXT` | The grouping or filtering field |

## Metric functions

| `function` value | Description | `measureId` required |
| --- | --- | --- |
| `COUNT` | Count of records | No. Omit `measureId`. |
| `COUNT_DISTINCT` | Count of distinct values | Yes |
| `SUM` | Sum of a numeric field | Yes |
| `AVG` | Average of a numeric field | Yes |
| `MIN` | Minimum value of a numeric field | Yes |
| `MAX` | Maximum value of a numeric field | Yes |

## Metric filter operations

Filters apply to dimension (TEXT) fields only. Matching is case-sensitive.

| `operation` value | Description |
| --- | --- |
| `STRING_EQUALS` | Exact match |
| `STRING_NOT_EQUAL` | Does not match |
| `STRING_CONTAINS` | Contains the argument |
| `STRING_NOT_CONTAINS` | Does not contain the argument |
| `STRING_IS_EMPTY` | Field is empty |
| `STRING_IS_NOT_EMPTY` | Field is not empty |
| `STRING_STARTS_WITH` | Starts with the argument |
| `STRING_ENDS_WITH` | Ends with the argument |

## Evaluation windows

The `evaluationWindow` field in Metric requests accepts these values (in seconds):

| Value | Duration |
| --- | --- |
| `60` | 1 minute |
| `300` | 5 minutes |
| `600` | 10 minutes |
| `900` | 15 minutes |
| `1800` | 30 minutes |
| `3600` | 1 hour |
| `86400` | 1 day |

## Action types

The following `actionType` values are supported in Decisions:

| `actionType` value | Description |
| --- | --- |
| `PUBNUB_PUBLISH` | Publish a message to a PubNub channel |
| `WEBHOOK_EXECUTION` | Make an HTTP request to an external endpoint |
| `APPCONTEXT_SET_USER_METADATA` | Update PubNub [App Context](https://www.pubnub.com/docs/data-storage/metadata/overview.md) user metadata |
| `APPCONTEXT_SET_CHANNEL_METADATA` | Update PubNub App Context channel metadata |
| `APPCONTEXT_SET_MEMBERSHIP_METADATA` | Update PubNub App Context membership metadata |

## Execution limit types

The `executionLimitType` field on Decision actions accepts these values:

| `executionLimitType` value | Description |
| --- | --- |
| `ALWAYS` | The action fires every time the rule matches |
| `ONCE_PER_INTERVAL` | The action fires once within the evaluation interval |
| `ONCE_PER_INTERVAL_PER_CONDITION` | The action fires once per unique condition value within the interval |
| `ONCE_PER_INTERVAL_PER_CONDITION_GROUP` | The action fires once per unique combination of all condition values within the interval |

## Recommended Decision creation workflow

Creating a Decision through the API requires multiple dependent IDs. Follow this sequence:

1. Create the Business Object with `isActive: false`.
2. Use the `fields[].id` values from the response to create a Metric.
3. Create the Decision with `isEnabled: false`. Add input fields and actions.
4. Read the Decision response. Use the returned `actions[].id` and `inputFields[].id` values to build rules.
5. Update the Decision with your rules.
6. Enable the Decision by setting `isEnabled: true`.

## Error codes

| Code | Meaning |
| --- | --- |
| `200` | Success |
| `201` | Created |
| `400` | Bad request. Check your request parameters. |
| `401` | Unauthorized. Include a valid `Authorization` header. |
| `403` | Forbidden. Your account does not have access to this resource. |
| `404` | Not found. The resource ID does not exist. |
| `422` | Unprocessable entity. Too many records found. |
| `500` | Internal server error. |

Last updated at: 2026-09-30T07:20:08.000Z