Proposals, runs and state
Manager proposes campaigns, waits for a decision, and does its work in asynchronous runs. This page covers listing and deciding campaign proposals, starting runs and following them to completion, and reading Manager's state, plans and metrics. Strategy proposals are decided on Program and strategy.
Every operation takes the tenant's provider scope as query parameters, such as githubOwnerId.
Campaign proposals
List open proposals
Returns campaign proposals that are still waiting on a decision (status PROPOSED or REVISED), newest round first. Each item carries the proposal itself, the quarter goal it serves and a summary of the campaign it points at. A proposed strategy version is not listed here. Requires configuration read access.
The id of each item's proposal is the proposalId the decision call expects.
Return the proposed campaigns still waiting on a human decision, newest round first. A proposed strategy version is decided through its own surface and is not listed here.
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Internal Server Error
GET /manager/proposals HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"proposals": [
{
"campaign": {
"findingsTotal": 1,
"id": "text",
"repositories": [
"text"
],
"severities": [
{
"count": 1,
"severity": "text"
}
]
},
"goal": {
"objective": "text",
"quarter": "text"
},
"proposal": {
"actorKind": "customer",
"campaignId": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"createdBy": "text",
"decidedAt": "2026-01-01T00:00:00.000Z",
"decidedBy": "text",
"decisionReason": "text",
"editSource": "text",
"goalKeys": [
"text"
],
"id": "text",
"kind": "STRATEGY",
"ordinal": 1,
"pace": {
"observedPerWeek": 1,
"requiredPerWeek": 1,
"verdict": "ACHIEVABLE"
},
"reasoning": "text",
"revision": 1,
"runId": "text",
"status": "PROPOSED",
"strategyId": "text",
"title": "text",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
}
]
}Decide a proposed campaign
Accepts or rejects one proposed campaign. The body has proposalId and a decision of accept or reject.
The campaign already exists in the PROPOSED lifecycle state while it waits, claiming nothing. Accepting moves it to ACTIVE, and rejecting moves it to CANCELLED. Neither call creates a new campaign, and generating the proposal was never approval to run it.
A proposal that is already decided, unknown, or belongs to another tenant returns 412. These cases are indistinguishable on purpose.
A proposal whose campaign has since been deleted, started, or cancelled also returns 412 and the open proposals that can no longer be decided are retired. Re-read List open proposals before retrying.
A proposal of another kind, such as a strategy proposal, returns 400. Use Decide the proposed strategy for those.
A decision cannot be repeated or reversed through this endpoint.
The decision is recorded against the caller. Requires finding write access.
Accept or reject a proposed campaign. Accepting starts it; the campaign already exists and acceptance moves it out of PROPOSED.
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Precondition Failed
Internal Server Error
POST /manager/proposals/decision HTTP/1.1
Host: api.<TENANT>.nullify.ai
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"decision": "accept",
"proposalId": "text"
}{
"proposal": {
"actorKind": "customer",
"campaignId": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"createdBy": "text",
"decidedAt": "2026-01-01T00:00:00.000Z",
"decidedBy": "text",
"decisionReason": "text",
"editSource": "text",
"goalKeys": [
"text"
],
"id": "text",
"kind": "STRATEGY",
"ordinal": 1,
"pace": {
"observedPerWeek": 1,
"requiredPerWeek": 1,
"verdict": "ACHIEVABLE"
},
"reasoning": "text",
"revision": 1,
"runId": "text",
"status": "PROPOSED",
"strategyId": "text",
"title": "text",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
}Starting runs
Every start operation returns as soon as the run is accepted, with a runId and an executionArn. The run has not finished and may still write nothing. Follow it with Get a Manager run.
All of them refuse to start, with 429, while a singleton Manager process holds the tenant lock for that kind of run, and POST /manager/trigger also refuses while the ticket reconciler is working on the tenant. Wait and retry. They require finding write access.
Start a Manager run
Starts a Manager run for the tenant. mode selects the workflow: full (the tenant-wide sweep), campaigns, tacit_knowledge, threat_intel, strategy, strategy_explore, action_items or plan_preview. Any other value returns 400. Omitting mode runs the full sweep, or a single-campaign run when campaignId is set. strategy_explore proposes the campaigns that would deliver the strategy already in force, and it is the only mode that does so.
evaluationTime overrides the instant Manager treats as now when judging staleness for escalations and nudges. It must be within 90 days of the current time. Leave it unset unless you are replaying a scenario.
Whether a run takes outward actions such as opening pull requests or messaging people is governed by Manager configuration and ground rules, not by this call.
Starts a Manager run for this tenant. Follow the returned runId with GET /manager/runs/{runId}.
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Too Many Requests
Internal Server Error
Gateway Timeout
POST /manager/trigger HTTP/1.1
Host: api.<TENANT>.nullify.ai
Content-Type: application/json
Accept: */*
Content-Length: 79
{
"campaignId": "text",
"evaluationTime": "2026-01-01T00:00:00.000Z",
"mode": "text"
}{
"executionArn": "text",
"message": "text",
"response": "text",
"runId": "text",
"version": "text"
}Start a daily summary run
Starts a run that writes the tenant's daily summary for an audience (internal or customer, required) and posts it to the channel configured for that audience. Returns 412 if the tenant has nowhere to deliver that audience's summary or the audience is switched off, and 503 if delivery fails.
Starts a manager run that writes the tenant's daily summary for the audience and posts it to the channel the tenant has configured for that audience. Follow the returned runId with GET /manager/runs/{runId}.
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Too Many Requests
Internal Server Error
POST /manager/daily-summary/trigger HTTP/1.1
Host: api.<TENANT>.nullify.ai
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"audience": "internal"
}{
"executionArn": "text",
"runId": "text"
}Start a tacit knowledge run
Starts a run that processes findings and generates questions for your team, which appear as action items. Unlike the other start operations, this one returns only a message: there is no runId to poll, so watch List action items for new items instead.
Trigger the tacit knowledge to process findings and generate customer questions
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Too Many Requests
Internal Server Error
Gateway Timeout
POST /manager/tacit-knowledge/trigger HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"message": "text",
"version": "text"
}Following a run
Get a Manager run
Returns the state of a strategy, campaign-generation or campaign run started by one of the operations above or by Generate default campaigns, and what it wrote: strategyId, strategyVersion, campaignIds and campaignRunIds.
Poll until terminal is true. state is one of PENDING, RUNNING, SUCCEEDED, FAILED, SKIPPED, TIMED_OUT or ABORTED; FAILED, TIMED_OUT and ABORTED carry an error where one is known. A run that succeeded without writing what its mode produces is reported as SKIPPED, with the reason in detail, so treat SKIPPED as a successful run that did nothing. An unrecognized execution status is reported as PENDING rather than terminal, so keep polling.
runId must be a ULID; anything else returns 400. A run another tenant started returns 404. The campaignRunIds can be read with Get a campaign run.
Returns the state of a strategy, campaign-generation or campaign run and the strategy, campaigns and campaign runs it wrote. A run that succeeded without writing anything is reported SKIPPED.
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Internal Server Error
GET /manager/runs/{runId} HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"campaignIds": [
"text"
],
"campaignRunIds": [
"text"
],
"completedAt": "text",
"detail": "text",
"error": "text",
"executionArn": "text",
"mode": "text",
"runId": "text",
"startedAt": "text",
"state": "PENDING",
"strategyId": "text",
"strategyVersion": 1,
"terminal": true
}State, plans and metrics
Get the Manager state
Returns the current state of Manager for the tenant. Returns 404 when no plan summary exists yet, which is the normal answer before the first run completes.
Returns the current state of the manager
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Internal Server Error
Gateway Timeout
GET /manager/state HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"currentState": {
"content": "text",
"createdAt": "text"
},
"version": "text"
}Get the Manager state (legacy)
A deprecated alias for Get the Manager state at the older /manager/state/latest path with the same behavior. Use /manager/state in new integrations.
Returns the current state of the manager (legacy endpoint)
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Internal Server Error
Gateway Timeout
GET /manager/state/latest HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"currentState": {
"content": "text",
"createdAt": "text"
},
"version": "text"
}List Manager state history
Returns earlier Manager states, with page (from 1) and pageSize (default 10).
Returns a history of manager states
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Internal Server Error
Gateway Timeout
GET /manager/states HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"stateHistory": [
{
"content": "text",
"createdAt": "text"
}
],
"version": "text"
}List plans
Returns Manager's plans, optionally limited to one campaign with campaignId, with page and pageSize. A plan is the scheduled work Manager resolved for a run; campaign summaries and previews are derived from it.
Returns a list of plans
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Internal Server Error
Gateway Timeout
GET /manager/plans HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"numItems": 1,
"plans": [
{
"createdAt": "2026-01-01T00:00:00.000Z",
"events": [
{
"actionType": "text",
"campaignIds": [
"text"
],
"createdAt": "text",
"description": "text",
"findingIds": [
"text"
],
"id": "text",
"metaData": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"pullRequestIds": [
"text"
],
"reasoning": "text",
"repositoryIds": [
"text"
],
"status": "text",
"threatInvestigationIds": [
"text"
],
"ticketIds": [
"text"
],
"userIds": [
"text"
]
}
],
"id": "text",
"response": {
"actionsExecuted": {
"channelMessagesSent": 1,
"directMessagesSent": 1,
"findingsAllowlisted": 1,
"findingsEscalated": 1,
"prCommentsCreated": 1,
"prsClosed": 1,
"prsCreated": 1,
"prsReassigned": 1,
"ticketCommentCreated": 1,
"ticketsClosed": 1,
"ticketsCreated": 1,
"ticketsReassigned": 1
},
"preview": {
"projectedActions": {
"allowlistFindings": [
{
"estimatedDate": "text",
"findingId": "text",
"reason": "text"
}
],
"closeFixPullRequests": [
{
"estimatedDate": "text",
"pullRequestId": "text",
"reason": "text"
}
],
"closeTickets": [
{
"estimatedDate": "text",
"reason": "text",
"ticketId": "text"
}
],
"commentOnFixPullRequests": [
{
"estimatedDate": "text",
"pullRequestId": "text",
"reason": "text"
}
],
"commentOnTickets": [
{
"estimatedDate": "text",
"reason": "text",
"ticketId": "text"
}
],
"createFixPullRequests": [
{
"estimatedDate": "text",
"findingId": "text",
"reason": "text"
}
],
"createTickets": [
{
"estimatedDate": "text",
"findingId": "text",
"reason": "text"
}
],
"escalateFindings": [
{
"estimatedDate": "text",
"findingId": "text",
"reason": "text"
}
],
"messageChannels": [
{
"channelId": "text",
"estimatedDate": "text",
"reason": "text",
"topic": "text"
}
],
"reassignFixPullRequests": [
{
"estimatedDate": "text",
"pullRequestId": "text",
"reason": "text"
}
],
"reassignTickets": [
{
"estimatedDate": "text",
"reason": "text",
"ticketId": "text"
}
],
"sendDirectMessages": [
{
"estimatedDate": "text",
"findingId": "text",
"reason": "text",
"userId": "text"
}
]
},
"thoughts": "text"
},
"summary": {
"campaigns": [
{
"campaignDeleted": true,
"campaignId": "text",
"content": "text",
"status": "text"
}
],
"content": "text",
"createdAt": "text"
},
"thoughts": [
{
"content": "text",
"createdAt": "text",
"findingId": "text"
}
],
"threatReport": {
"createdAt": "text",
"summary": "text"
}
}
}
],
"version": "text"
}Get metrics
Returns cumulative Manager metrics for the tenant: event aggregates, merged pull request and resolved ticket counts, findings in backlog, in progress and resolved, and mean and median remediation timings. Treat the response schema as authoritative for field meanings.
By default the figures are current. Pass asOf (an RFC 3339 timestamp) to compute them as of that instant. asOf bounds when work counts as resolved, not when a finding was created, so findings that appeared after the cutoff stay unresolved in the result instead of being excluded. prMergedCount is measured from real pull request state while prCreateCount is an event counter, so the merged count can exceed the created count; the response does not clamp it. An invalid asOf returns 400. timeSaved is deprecated and equals totalRemediationDuration.
Returns metrics for the manager
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
Operator routes only: the GitHub App installation ID to use alongside githubOwnerId when the tenant's stored record has none. Ignored on customer routes.
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Forbidden
Not Found
Internal Server Error
Gateway Timeout
GET /manager/metrics HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"backlogSearches": 1,
"escalatedFindings": 1,
"escalations": 1,
"findingsAnalysis": {
"autofixTimeTotal": 1,
"detectionTimeTotal": 1,
"estimatedBacklogStoryPoints": 1,
"findingsAllowlistedCount": 1,
"findingsCount": 1,
"findingsFixPendingVerificationCount": 1,
"findingsFixedCount": 1,
"findingsInBacklogCount": 1,
"findingsInProgressCount": 1,
"findingsNoLongerDetectedCount": 1,
"findingsResolvedCount": 1,
"findingsWithOpenAutoFixPRCount": 1,
"findingsWithOpenTicketCount": 1,
"fixedTimeToResolve": {
"meanMs": 1,
"medianMs": 1,
"sample": 1
},
"funnel": {
"aging": {
"cachedNoPr": {
"count": 1,
"oldestMs": 1,
"p50Ms": 1,
"p90Ms": 1
},
"prOpenReviewedUnmerged": {
"count": 1,
"oldestMs": 1,
"p50Ms": 1,
"p90Ms": 1
},
"prOpenUnreviewed": {
"count": 1,
"oldestMs": 1,
"p50Ms": 1,
"p90Ms": 1
}
},
"fixSourceBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"stages": {
"cachedNoPr": 1,
"detected": 1,
"prMerged": 1,
"prOpenReviewed": 1,
"prOpenUnreviewed": 1,
"triaged": 1,
"verifiedFixed": 1
},
"version": 1
},
"meanTimeToAutofix": 1,
"meanTimeToDetectAndTriage": 1,
"meanTimeToMerge": 1,
"meanTimeToPullRequestCreation": 1,
"meanTimeToReview": 1,
"meanTimeToTriage": 1,
"medianTimeToAutofix": 1,
"medianTimeToDetectAndTriage": 1,
"medianTimeToMerge": 1,
"medianTimeToPullRequestCreation": 1,
"medianTimeToReview": 1,
"medianTimeToTriage": 1,
"stageSamples": {
"autofix": 1,
"detectAndTriage": 1,
"detectAndTriageAfterOutliers": 1,
"merge": 1,
"mergeAfterOutliers": 1,
"pullRequestCreation": 1,
"pullRequestCreationAfterOutliers": 1,
"review": 1,
"reviewAfterOutliers": 1,
"triage": 1
},
"triageTimeTotal": 1
},
"internetSearchCount": 1,
"messageCount": 1,
"plansGenerated": 1,
"prCloseCount": 1,
"prCommentCount": 1,
"prCreateCount": 1,
"prMergedCount": 1,
"previewMessageCount": 1,
"storyPointsConsumed": 1,
"tasksAssigned": 1,
"ticketCloseCount": 1,
"ticketCommentCount": 1,
"ticketCreateCount": 1,
"ticketsResolvedCount": 1,
"timeSavedAssigning": 1,
"version": "text"
}Last updated