Triggers

Fire a trigger

Fires a trigger synchronously and returns the terminal firing record. The firing itself always settles here; an eval target's run is queued rather than executed inline, so the record names a queued run to poll.

post/v1/projects/{project_id}/triggers/{trigger_id}/fire

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/triggers/{trigger_id}/fire
  • 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)

Path parameters

trigger_idstring required

Request body

inputobject

Fire-time input, shallow-merged over the trigger's static input. For eval targets it may carry agent_version and baseline_run_id.

tool_contextobject

Fire-time caller context, shallow-merged per key over the trigger's stored tool_context. A manual fire has a caller, so this is the one path that can supply a value without storing it.

Forwarded exactly as written: a {{secret:...}} reference is resolved only in the trigger's stored bag, never in one supplied here.

Response

Terminal firing record

idstring
trigger_idstring
project_idstring
source'manual' | 'webhook' | 'schedule' | 'event'
status'queued' | 'running' | 'completed' | 'failed'
inputobject nullable

Effective input, after the trigger's static input is merged under the fire-time input. For an event firing the fire-time input is the event envelope a webhook delivery carries (id, event, project_id, resource_type, resource_id, data, timestamp).

resultobject nullable

{ target_type, result_id, status, output } — output truncated

idempotency_keystring nullable

<event_id>:<trigger_id> for an event firing, where event_id is the id in input; null for every other source. The same event reaching the same trigger twice produces one firing under this key, so a consumer reading firings can recognise a redelivery.

attemptsinteger

Dispatch attempts started. Above 1 means an earlier attempt was interrupted before it recorded a result and the firing was redelivered — not that the target refused it, which is recorded terminally in error and never retried.

started_atstring date-time nullable
completed_atstring date-time nullable
created_atstring date-time
updated_atstring date-time

Example response

{
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "Provider returned 402: insufficient credits"
  }
}

Changes

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