Illuminate REST API

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.

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

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 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.