WatchEye
Browse endpoints
View as Markdown OpenAPI spec

Create a program

POST /api/v1/programs operationId: program.create

Base: https://portal.watcheye.com.au/api/v1/programs

Create a new program in the calling account. Only program_name is required; every other field has a sensible default.

Defaults

Fields you do not supply default to:

  • status - active
  • data_retention_months - 12
  • event_grouping - separate (with max_separate_events defaulting to 10)
  • report_emails - empty
  • default_risk_level - low

Idempotency

This endpoint accepts the Idempotency-Key header so that retries on network failure are safe. See the Idempotency section of the API guide for the full contract.

Header parameters

FieldDescription
Idempotency-Key string [max 255 characters]

Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the Idempotent-Replay: true response header.

Honoured on POST requests only. See the Idempotency section of the API guide for the full contract.

Example: 8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f

Request body

Content type application/json. The program details

FieldDescription
program_namerequired string [2..255 characters]

Example: AML Onboarding Program
status string

Enum: active, paused

Example: active
report_emails array of strings [max 5 items] or null

Email addresses (max 5) that receive event report notifications
data_retention_months integer

Enum: 0, 1, 3, 6, 12, 24, 36, 48, 60, 72, 84

Example: 12
event_grouping string

Enum: separate, grouped

Example: separate
max_separate_events integer [5..100] or null

Required when event_grouping is separate; ignored when grouped. Range 5-100.

Example: 10
default_risk_level string or null

The risk level pre-filled when a new entity is added to this program. When set to null (No risk assigned), new entities start with no risk rating, which may be left unassigned and set later; bulk file uploads assign low.

Enum: low, medium, high

Example: low

Responses

201

Program created

application/json
FieldDescription
data object
data.uuid string (uuid)

The program's UUID

Example: 9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f
data.program_number string

A short obfuscated public identifier for the program (e.g. "P-123-456-789")

Example: P-123-456-789
data.program_name string

The display name of the program

Example: AML Onboarding Program
data.status string

Lifecycle status of the program:

  • active - normal operation
  • paused - monitors do not run; entities and checks remain accessible
  • archived - read-only; the program is hidden from default lists but not deleted

Enum: active, paused, archived

Example: active
data.report_emails array of strings

Email addresses (max 5) that receive event report notifications for this program
data.data_retention_months integer

How long, in months, to keep entity data for. Permitted values: 0 (no retention), 1, 3, 6, 12, 24, 36, 48, 60, 72, 84.

Example: 12
data.event_grouping string

Whether events from the same entity should be grouped into one event:

  • separate - each event is created as a separate event (capped by max_separate_events)
  • grouped - events are merged into a single event per entity

Enum: separate, grouped

Example: separate
data.max_separate_events integer or null

When event_grouping is separate, the maximum number of separate events to create for a single entity (5-100). Null when event_grouping is grouped.

Example: 10
data.default_risk_level string or null

The risk level pre-filled when a new entity is added to this program:

  • low / medium / high - new entities pre-fill with this risk rating
  • null - new entities start with no risk assigned; the rating may be left unassigned and set later (bulk file uploads assign low)

Enum: low, medium, high

Example: low
data.created_at string (date-time)

ISO 8601 timestamp at which the program was created

Example: 2025-01-01T00:00:00Z
data.updated_at string (date-time)

ISO 8601 timestamp at which the program was last updated

Example: 2025-01-01T00:00:00Z
api_reference string (uuid)
409

Conflict - a request with this Idempotency-Key is currently being processed

application/json
FieldDescription
message string

Example: A request with this Idempotency-Key is already being processed.
422

Idempotency-Key was reused with a different request body

application/json
FieldDescription
message string

Example: Idempotency-Key was reused with a different request body.
Standard error responses: 400 401 402 403 429 5XX See common error responses
Previous List programs Next Show a program