--- title: "Create or update an event trigger" method: POST path: "/api/v2/agent/upsertEventTrigger" tags: ["Agent"] --- # Create or update an event trigger `POST /api/v2/agent/upsertEventTrigger` ## Request - Base URL: `https://zeropath.com` - URL: `https://zeropath.com/api/v2/agent/upsertEventTrigger` - Auth: API key in header `X-ZeroPath-API-Token-Id` and API key in header `X-ZeroPath-API-Token-Secret` Create or update event-driven assistant automation for the organization. Use this only when the requested automation should run in response to a ZeroPath notification event. Do not use event triggers for polling, recurring checks, timeout-rate monitoring, or requests like "check every hour"; use agent.createCronSchedule for those. LONG_RUNNING_SCAN means one scan has already crossed the long-running threshold and is not a recurring PR scan timeout monitor. The prompt field tells the agent what to do when the event fires. ## Request body - AgentUpsertEventTriggerRequest - `organizationId` string: Organization ID (injected by MCP server) - `triggerId` string, uuid: Trigger ID — include to update an existing trigger, omit to create a new one - `eventType` 'SCAN_STARTED' | 'SCAN_COMPLETE' | 'PR_SCAN_STARTED' | 'PR_SCAN_COMPLETE' | 'NEW_VULNERABILITIES_PR' | 'NEW_VULNERABILITIES_FULL_SCAN' | 'VULNERABILITY_PATCHED' | 'VULNERABILITY_REOPENED' | 'AUDIT_LOG_EVENT' | 'SCAN_FAILED' | 'SCAN_SCHEDULED' | 'LONG_RUNNING_SCAN' | 'PR_BLOCKED' | 'PR_MERGED_WITH_ISSUES' | 'REPORT_COMPLETE' | 'SCA_NEW_CVE' | 'SCA_NEW_ISSUE' | 'INBOUND_WEBHOOK' | 'PATCH_PR_DENIED' | 'VULNERABILITY_STATUS_CHANGED' | 'SCA_SCAN_COMPLETE' | 'SCA_SCAN_STARTED' | 'SCA_SCAN_FAILED' | 'REPO_ADDED' | 'RUNTIME_VALIDATION_FINISHED' | 'RUNTIME_VALIDATION_EXPLOITABLE' | 'RUNTIME_VALIDATION_NOT_EXPLOITABLE' | 'RUNTIME_VALIDATION_UNABLE' | 'CONTAINER_SCAN_STARTED' | 'CONTAINER_SCAN_COMPLETE' | 'CONTAINER_NEW_ISSUE' | 'ISSUE_AGED_PAST_THRESHOLD' | 'SLA_BURN_RATE_HIGH', required: The notification event type. Event triggers are event-driven automation: they run only after ZeroPath emits the selected notification event, and every enabled trigger matching that event and scope runs. They do not poll, run on a timer, or create recurring checks. Use agent.createCronSchedule for recurring monitoring, time-window analysis, timeout-rate checks, or requests phrased as "every N hours/days" or "on a schedule". PR scan timeout monitoring is a cron-schedule use case unless the user explicitly asks to react to an individual scan that has already emitted LONG_RUNNING_SCAN. Event type guide: SCAN_STARTED: A full repository code scan started. Use for reacting to the start of non-PR SAST scans. SCAN_COMPLETE: A full repository code scan completed and findings are available. Use for full-scan triage or summaries. PR_SCAN_STARTED: A pull request scan started. Use for reacting to a specific PR scan beginning. PR_SCAN_COMPLETE: A pull request scan completed and PR findings are available. Use for PR review follow-up. NEW_VULNERABILITIES_PR: New vulnerability findings were detected by a PR scan. Use for PR-scoped finding triage. NEW_VULNERABILITIES_FULL_SCAN: New vulnerability findings were detected by a full repository scan. Use for full-scan finding triage. VULNERABILITY_PATCHED: A vulnerability was marked patched, often after a remediation PR. Use for fix verification follow-up. VULNERABILITY_REOPENED: A vulnerability was reopened after previously being closed or resolved. Use for re-triage. AUDIT_LOG_EVENT: A security-relevant audit log entry was recorded. Use for reviewing administrative or configuration activity. SCAN_FAILED: A code scan failed. Use for investigating one failed scan event, not for recurring failure-rate reporting. SCAN_SCHEDULED: A platform code scan schedule was created or changed. This is about scanner schedules, not assistant cron schedules. LONG_RUNNING_SCAN: A single FullScan, PrScan, or SCAScan has already crossed ZeroPath long-running thresholds. Use only to react to that emitted incident. Do not use this for recurring PR scan timeout or timeout-rate monitoring; create an agent cron schedule instead. PR_BLOCKED: A pull request was blocked by security findings or policy. Use for advising on the blocked PR. PR_MERGED_WITH_ISSUES: A pull request was merged while security issues remained open. Use for post-merge risk follow-up. REPORT_COMPLETE: A generated ZeroPath report finished. Use for reviewing or distributing that report. SCA_NEW_CVE: A newly observed CVE affects dependencies in the organization, potentially across repositories. Use for dependency advisory triage. SCA_NEW_ISSUE: A concrete dependency vulnerability issue was created for a repository/package. Use for repo-specific SCA issue triage. INBOUND_WEBHOOK: An external system posted to this trigger-specific webhook URL. Use for custom external automation inputs. PATCH_PR_DENIED: A ZeroPath-generated patch PR was closed or rejected without merge. Use for inspecting feedback and deciding next remediation steps. VULNERABILITY_STATUS_CHANGED: One or more findings changed status. Use for syncing automation state after triage updates. SCA_SCAN_COMPLETE: A dependency analysis scan completed. Use for SCA scan result review. SCA_SCAN_STARTED: A dependency analysis scan started. Use for reacting to a specific SCA scan beginning. SCA_SCAN_FAILED: A dependency analysis scan failed. Use for investigating one failed SCA scan event. REPO_ADDED: A repository was added to the organization. Use for onboarding or initial security automation. RUNTIME_VALIDATION_FINISHED: A Runtime Validation run finished with aggregate results. Use for summarizing run-level validation outcome. RUNTIME_VALIDATION_EXPLOITABLE: Runtime Validation confirmed an issue is exploitable. Use for prioritizing remediation. RUNTIME_VALIDATION_NOT_EXPLOITABLE: Runtime Validation marked an issue not exploitable. Use for updating triage or accepted-risk decisions. RUNTIME_VALIDATION_UNABLE: Runtime Validation could not validate an issue. Use for identifying missing runtime context or setup gaps. CONTAINER_SCAN_STARTED: A container image scan started. Use for reacting to a specific container scan beginning. CONTAINER_SCAN_COMPLETE: A container image scan completed and image findings are available. Use for container scan result review. CONTAINER_NEW_ISSUE: A concrete container image vulnerability issue was created. Use for image-specific vulnerability triage. ISSUE_AGED_PAST_THRESHOLD: An open vulnerability issue has remained unresolved past its SLA policy age threshold. Use for aging-issue escalation or remediation follow-up. SLA_BURN_RATE_HIGH: An SLA compliance policy is burning down its remediation budget faster than the target rate. Use for proactive SLA risk monitoring before deadlines are missed. - `enabled` boolean: Whether the trigger is enabled - `trusted` boolean: Whether jobs created by this trigger run with trusted tool access. Defaults to false; set true only for admin-approved automation. - `name` string: Human-readable name for this trigger (e.g. "Triage critical findings") - `prompt` string, required: The prompt that tells the agent what to do when this event fires - `modelStrength` 'LOW' | 'HIGH': Model strength for jobs created by this trigger. Omit to use LOW. LOW is suitable for the vast majority of tasks; HIGH is for unusually complex work. - `repositoryIds` string[]: Scope to these repository IDs (empty or omit = all repos) - `tagIds` string[]: Scope to repos with these tag IDs (empty or omit = all repos) ## Response `200` Trigger created or updated - AgentUpsertEventTriggerResponse - `trigger` object, required - `id` string, uuid, required - `eventType` 'SCAN_STARTED' | 'SCAN_COMPLETE' | 'PR_SCAN_STARTED' | 'PR_SCAN_COMPLETE' | 'NEW_VULNERABILITIES_PR' | 'NEW_VULNERABILITIES_FULL_SCAN' | 'VULNERABILITY_PATCHED' | 'VULNERABILITY_REOPENED' | 'AUDIT_LOG_EVENT' | 'SCAN_FAILED' | 'SCAN_SCHEDULED' | 'LONG_RUNNING_SCAN' | 'PR_BLOCKED' | 'PR_MERGED_WITH_ISSUES' | 'REPORT_COMPLETE' | 'SCA_NEW_CVE' | 'SCA_NEW_ISSUE' | 'INBOUND_WEBHOOK' | 'PATCH_PR_DENIED' | 'VULNERABILITY_STATUS_CHANGED' | 'SCA_SCAN_COMPLETE' | 'SCA_SCAN_STARTED' | 'SCA_SCAN_FAILED' | 'REPO_ADDED' | 'RUNTIME_VALIDATION_FINISHED' | 'RUNTIME_VALIDATION_EXPLOITABLE' | 'RUNTIME_VALIDATION_NOT_EXPLOITABLE' | 'RUNTIME_VALIDATION_UNABLE' | 'CONTAINER_SCAN_STARTED' | 'CONTAINER_SCAN_COMPLETE' | 'CONTAINER_NEW_ISSUE' | 'ISSUE_AGED_PAST_THRESHOLD' | 'SLA_BURN_RATE_HIGH', required: The notification event type. Event triggers are event-driven automation: they run only after ZeroPath emits the selected notification event, and every enabled trigger matching that event and scope runs. They do not poll, run on a timer, or create recurring checks. Use agent.createCronSchedule for recurring monitoring, time-window analysis, timeout-rate checks, or requests phrased as "every N hours/days" or "on a schedule". PR scan timeout monitoring is a cron-schedule use case unless the user explicitly asks to react to an individual scan that has already emitted LONG_RUNNING_SCAN. Event type guide: SCAN_STARTED: A full repository code scan started. Use for reacting to the start of non-PR SAST scans. SCAN_COMPLETE: A full repository code scan completed and findings are available. Use for full-scan triage or summaries. PR_SCAN_STARTED: A pull request scan started. Use for reacting to a specific PR scan beginning. PR_SCAN_COMPLETE: A pull request scan completed and PR findings are available. Use for PR review follow-up. NEW_VULNERABILITIES_PR: New vulnerability findings were detected by a PR scan. Use for PR-scoped finding triage. NEW_VULNERABILITIES_FULL_SCAN: New vulnerability findings were detected by a full repository scan. Use for full-scan finding triage. VULNERABILITY_PATCHED: A vulnerability was marked patched, often after a remediation PR. Use for fix verification follow-up. VULNERABILITY_REOPENED: A vulnerability was reopened after previously being closed or resolved. Use for re-triage. AUDIT_LOG_EVENT: A security-relevant audit log entry was recorded. Use for reviewing administrative or configuration activity. SCAN_FAILED: A code scan failed. Use for investigating one failed scan event, not for recurring failure-rate reporting. SCAN_SCHEDULED: A platform code scan schedule was created or changed. This is about scanner schedules, not assistant cron schedules. LONG_RUNNING_SCAN: A single FullScan, PrScan, or SCAScan has already crossed ZeroPath long-running thresholds. Use only to react to that emitted incident. Do not use this for recurring PR scan timeout or timeout-rate monitoring; create an agent cron schedule instead. PR_BLOCKED: A pull request was blocked by security findings or policy. Use for advising on the blocked PR. PR_MERGED_WITH_ISSUES: A pull request was merged while security issues remained open. Use for post-merge risk follow-up. REPORT_COMPLETE: A generated ZeroPath report finished. Use for reviewing or distributing that report. SCA_NEW_CVE: A newly observed CVE affects dependencies in the organization, potentially across repositories. Use for dependency advisory triage. SCA_NEW_ISSUE: A concrete dependency vulnerability issue was created for a repository/package. Use for repo-specific SCA issue triage. INBOUND_WEBHOOK: An external system posted to this trigger-specific webhook URL. Use for custom external automation inputs. PATCH_PR_DENIED: A ZeroPath-generated patch PR was closed or rejected without merge. Use for inspecting feedback and deciding next remediation steps. VULNERABILITY_STATUS_CHANGED: One or more findings changed status. Use for syncing automation state after triage updates. SCA_SCAN_COMPLETE: A dependency analysis scan completed. Use for SCA scan result review. SCA_SCAN_STARTED: A dependency analysis scan started. Use for reacting to a specific SCA scan beginning. SCA_SCAN_FAILED: A dependency analysis scan failed. Use for investigating one failed SCA scan event. REPO_ADDED: A repository was added to the organization. Use for onboarding or initial security automation. RUNTIME_VALIDATION_FINISHED: A Runtime Validation run finished with aggregate results. Use for summarizing run-level validation outcome. RUNTIME_VALIDATION_EXPLOITABLE: Runtime Validation confirmed an issue is exploitable. Use for prioritizing remediation. RUNTIME_VALIDATION_NOT_EXPLOITABLE: Runtime Validation marked an issue not exploitable. Use for updating triage or accepted-risk decisions. RUNTIME_VALIDATION_UNABLE: Runtime Validation could not validate an issue. Use for identifying missing runtime context or setup gaps. CONTAINER_SCAN_STARTED: A container image scan started. Use for reacting to a specific container scan beginning. CONTAINER_SCAN_COMPLETE: A container image scan completed and image findings are available. Use for container scan result review. CONTAINER_NEW_ISSUE: A concrete container image vulnerability issue was created. Use for image-specific vulnerability triage. ISSUE_AGED_PAST_THRESHOLD: An open vulnerability issue has remained unresolved past its SLA policy age threshold. Use for aging-issue escalation or remediation follow-up. SLA_BURN_RATE_HIGH: An SLA compliance policy is burning down its remediation budget faster than the target rate. Use for proactive SLA risk monitoring before deadlines are missed. - `eventDescription` string, required: Human-readable explanation of when this event trigger fires and what behavior it represents. - `enabled` boolean, required - `trusted` boolean, required: Whether jobs created by this trigger run with trusted tool access. Untrusted triggers run with restricted execution. - `name` string, nullable: Human-readable name for this trigger - `prompt` string, required - `modelStrength` 'LOW' | 'HIGH', required - `webhookSecret` string, nullable: Auto-generated secret for INBOUND_WEBHOOK triggers. The webhook URL is: {baseUrl}/api/agent/webhook/{triggerId}?secret={webhookSecret} - `createdAt` string, date-time, required - `updatedAt` string, date-time, required ## Other responses - `400`: Error Response - `401`: Error Response --- [API](https://skmtc.dev/zeropath/apis/zeropath-api.md) - [All operations](https://skmtc.dev/zeropath/apis/zeropath-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zeropath/apis/zeropath-api/revisions/126e9c80ba0d?raw)