Triggers

Create a trigger

Creates a new trigger for a project

post/v1/projects/{project_id}/triggers

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/triggers
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

namestring required
descriptionstring
type'manual' | 'webhook' | 'schedule' | 'event' required
target_type'orchestration' | 'agent' | 'tool' | 'eval' required
target_idstring required
actionstring

Tool targets only — the action for mcp tools

inputobject
tool_contextobject

Caller context every firing forwards to the run it starts, so an agent whose tools authorize through {{context:<key>}} can be put on a schedule — a firing has no request to carry one. Each key is forwarded as one X-Naturali-Context-<key> header.

Write-only. It is accepted here and never returned on a read, so the record cannot be used to recover a value.

A value may be a {{secret:sec_...}} reference, which keeps the credential in the secret store and leaves only its id on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference is refused here rather than at fire time when it is not in that id form (a secret's name does not resolve) or names a secret that does not exist in this project.

cronstring

5-field cron expression (UTC). Required when type is schedule

event_patternstring

Internal-event subscription pattern. Required when type is event, rejected otherwise. * matches every event, prefix.* a namespace, or give an exact event name such as documents.ingested

activeboolean
policy_idstring

Response

Trigger created

idstring
project_idstring
namestring
descriptionstring nullable
type'manual' | 'webhook' | 'schedule' | 'event'
target_type'orchestration' | 'agent' | 'tool' | 'eval'
target_idstring

Public ID of the target resource (orchestration, agent, tool, or eval)

actionstring nullable

Tool targets only — the action for mcp tools

inputobject nullable

Static input, shallow-merged under fire-time input. For eval targets the effective input may carry agent_version and baseline_run_id, which are passed to the queued run.

cronstring nullable

5-field cron expression (UTC). Present only for schedule triggers

event_patternstring nullable

Internal-event subscription pattern. Present only for event triggers: *, prefix.*, or an exact event name

activeboolean
policy_idstring nullable

Optional boundary policy that further restricts firings

next_fire_atstring date-time nullable

Read-only, schedule triggers only. Server-computed next fire time

created_atstring date-time
updated_atstring date-time
secretstring

Webhook triggers only. Returned only on create and rotate

Changes

No recorded changes to this operation across all 1 revision of this API.