Decide an end user's approval
The end user’s answer, relayed by your app. Approving runs the parked call; the request-bound preview, expiry and receipts work as for any approval. An approval of another end user, or one the team decides, answers 404.
/api/v2/end-users/{endUserId}/approvals/{approvalId}/decideAuthorizationBearer token (Anlyon API key) · headerrequiredWorkspace API key sent as Authorization: Bearer <key>.
better-auth.session_tokenAPI key · cookierequiredBrowser session used by dashboard-only operations.
endUserIdstringrequiredYour own id for the end user. 1 to 128 characters of letters, digits and . _ : @ -. URL-encode it.
approvalIdstringrequiredPublic approval id (apr_...).
X-Request-IdstringOptional caller correlation ID. Unsafe or oversized values are replaced.
Anlyon-End-UserstringThe end user this call acts for: your own id for them, 1 to 128 characters of letters, digits and . _ : @ -. Accepted only with an API key, which stays on your server; a session or an OAuth token that sends it is refused. A key created with endUserRequired must send it on every action call (400 END_USER_REQUIRED). On an /end-users/{endUserId} route it must name the same end user as the path.
application/jsondecisionstringrequiredapprovedenyreasonstringRecorded as the decision note.
The decision
successbooleanrequiredtruedataobjectrequiredShow propertiesHide properties
approvalApprovalrequiredShow propertiesHide properties
idstringrequiredkindstringrequiredfunction_plan: the writes a hosted function's plan run recorded, bound to the plan's digest in payload.planDigest.
actioncustomfunction_planstatusstringrequiredpendingapproveddeniedexpiredtitlestringrequireddescriptionstring | nullrequiredpayloadobjectrequiredSecret-safe review payload.
decisionNotestring | nullrequireddecidedByApprovalActor | nullThe recorded reviewer who finalized the decision, not all voters. Null for pending, expired, automated or unattributed decisions. Available to approval readers; not copied into invocation responses.
Show propertiesHide properties
typestringrequiredapi_keyuseridstringrequiredStable recorded reviewer identity. Never an API key value.
displayNamestring | nullrequiredNull when no historical display name was recorded.
nullvotesApprovalVote[]Recorded votes in chronological order on detail reads, including long-poll results. Omitted on list, create and decide responses; fetch the detail to audit all reviewers.
Show propertiesHide properties
ApprovalVotedecisionstringrequiredapprovedenydecidedByApprovalActor | nullrequiredShow propertiesHide properties
ApprovalActornullnotestring | nullrequiredselfApprovedbooleanrequiredTrue when an app acting for the decider, or an API key they created, requested the approval. Allowed only while the decider is the only member who can decide approvals in its environment; with a second one, the request answers 403 SELF_APPROVAL_NOT_ALLOWED.
decidedAtstring<date-time>requiredrequiredApprovalsintegerrequiredDistinct approvers needed (N-of-M), as resolved from the governing policy when the approval was created.
approvedCountintegerrequiredApprovals recorded so far.
matchedPolicyIdstring | nullrequiredThe policy that governed this approval, as recorded when it was created. Null when no policy matched (the default gate applied) and on approvals recorded before policies existed.
matchedPolicyVersioninteger | nullrequiredThe version of that policy at the time. Null exactly when matchedPolicyId is null.
policyExplanationstring | nullrequiredA human-readable account of how the policy was applied. Null on approvals recorded before it was kept. It is the approval's own record; an invocation carries its own decision and does not need this.
decisionOriginstring | nullrequiredWho decided. Persisted, not inferred from status. Null while pending. unknown marks a decision made before origin was recorded whose evidence does not settle it; it is never guessed. assistant is an approval by opt-in Anlyon Vigil inside the limits an admin set; it never denies.
humanpolicysystemunknownassistantnullendUserIdstring | nullrequiredThe end user the gated call was made for (Anlyon-End-User), or null for a call with the workspace's own accounts. erased~<hash> once that end user is erased.
deciderstringrequiredWho decides it. end_user: the end user it was made for, in your app, through /api/v2/end-users/{endUserId}/approvals (a policy with decidedBy: end_user). Such an approval is not in the team's inbox or Slack, and the team's decide routes answer 404 for it. Not decidedBy, which is the reviewer.
teamend_userexpiresAtstring<date-time>requireddecidedAtstring<date-time> | nullrequiredcreatedAtstring<date-time>requiredadviceobjectAnlyon Vigil's suggestion, on dashboard (session) responses only and only for workspaces that opted in. API-key callers never receive it.
Show propertiesHide properties
statusstringrequiredpendingreadyfailedskippedstatusReasonstring | nullrequiredWhy advice failed or was skipped, e.g. quota_exceeded, timeout, already_decided.
modelstring | nullrequiredVigil's public model version. Auto-approve thresholds are calibrated per version.
recommendationstring | nullrequiredapprovedenyreviewnullrisknumber | nullrequiredExpected harm if approving were wrong, 0 routine to 4 critical.
riskLevelstring | nullrequiredroutinelowmoderatehighcriticalnullconfidencenumber | nullrequiredreasonsstring[]requiredflagsobject | nullrequiredShow propertiesHide properties
injectionSuspectednumber | nullrequiredconsistentWithHistorynumber | nullrequiredamountUnusualnumber | nullrequiredhistoryobject | nullrequiredThis agent and action over the last 30 days.
Show propertiesHide properties
approvedintegerrequireddeniedintegerrequiredmaxAmountnumber | nullrequiredmedianAmountnumber | nullrequiredauditRequestedbooleanrequiredThis Vigil decision was sampled for a person to check.
auditVerdictstring | nullrequiredagreedisagreenullcreatedAtstring<date-time>requiredcompletedAtstring<date-time> | nullrequiredinvocationInvocationShow propertiesHide properties
idstringrequiredeffectIdstring | nullrequiredThe governed effect this invocation created, for a governed action (an adapter or a declaration). Its outcome, evidence and recovery are at GET /api/v2/actions/effects/{id}. Null for template actions.
endUserIdstring | nullrequiredThe end user the call acted for (Anlyon-End-User), whose own accounts it used. Null for a call with the workspace's own accounts. erased~<hash> once that end user is erased.
gradestring | nullOn invoke responses and single reads: the receipt grade of the effect this invocation created. See Effect.grade. Absent when the invocation has no effect, and on list reads.
confirmedacknowledgedunknownfailedrefuseddeniedpendingnullretryOfstring | nullrequiredThe failed invocation this one deliberately retried.
retriedBystring | nullOn single reads: the invocation that retried this one.
resolutionobject | nullOn single reads: the operator's confirmed outcome for an invocation that was unknown.
Show propertiesHide properties
outcomestringrequiredsucceededfailedevidencestringrequiredexternalReferencestring | nullrequiredresolvedByobjectrequiredShow propertiesHide properties
typestringrequiredapi_keyuseridstringrequiredresolvedAtstring<date-time>requiredactionNamestringrequiredactionVersionIdstring | nullrequiredThe immutable action version this invocation ran. Lets an audit answer which definition executed a given call rather than inferring it. Null only for invocations recorded before versioning existed.
statusstringrequiredunknown means the request may have reached the destination and Anlyon cannot confirm what happened a timeout, or a socket that died after the request was written. It is deliberately distinct from failed, which means the call did not happen: an error before anything left, such as a blocked URL or an invalid template. Do not retry an unknown invocation automatically. Reconcile it with the destination first; retrying is how one refund becomes two. This value is additive clients that do not know it should treat an unrecognised status as not-successful rather than as failed.
pending_approvalrunningsucceededfailedunknowndeniedexpiredresponseStatusinteger | nullrequiredbodystring | nullrequiredRedacted and truncated upstream response body.
errorstring | nullrequireddurationMsinteger | nullrequiredapprovalIdstring | nullrequireddecisionInvocationDecision | nullrequiredWhy the request was allowed or refused, when a policy, a person or expiry decided it. Persisted on the invocation, so it reads the same after the policy is edited or deleted. Null while undecided, for an invocation that ran with no gate, and on rows recorded before this field existed. For a request that was never sent, responseStatus and body stay null: no response is fabricated.
Show propertiesHide properties
sourcestringrequiredpolicyhumansystemassistantcodestringrequiredPOLICY_DENIEDPOLICY_APPROVEDHUMAN_APPROVEDHUMAN_DENIEDAPPROVAL_EXPIREDASSISTANT_APPROVEDEND_USER_ERASEDeffectstringrequiredWhat actually happened to the request.
approveddeniedexpiredexplanationstringrequiredpolicyobject | nullrequiredThe policy that decided, as it stood at decision time. Null when no policy decided.
Show propertiesHide properties
idstringrequirednamestringrequiredversionintegerrequireddecidedAtstring<date-time>requiredDatabase time the decision was committed.
nullcreatedAtstring<date-time>requiredcompletedAtstring<date-time> | nullrequiredBad Request - Invalid input data
successbooleanrequiredrequestIdstringrequiredCorrelation ID matching the X-Request-Id response header.
errorobjectrequiredShow propertiesHide properties
codestringmessagestringdetailsobjectfixErrorFixHow to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.
Show propertiesHide properties
summarystringrequiredOne sentence that says what to do.
commandstringAn exact anlyon CLI command that fixes it. Absent when no command does.
urlstring<uri>An absolute console link where a person fixes it.
docsstring<uri>A docs page that explains it.
Unauthorized - Invalid or missing API key
successbooleanrequiredrequestIdstringrequiredCorrelation ID matching the X-Request-Id response header.
errorobjectrequiredShow propertiesHide properties
codestringmessagestringdetailsobjectfixErrorFixHow to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.
Show propertiesHide properties
summarystringrequiredOne sentence that says what to do.
commandstringAn exact anlyon CLI command that fixes it. Absent when no command does.
urlstring<uri>An absolute console link where a person fixes it.
docsstring<uri>A docs page that explains it.
Authenticated credential lacks the required scope or workspace access.
successbooleanrequiredrequestIdstringrequiredCorrelation ID matching the X-Request-Id response header.
errorobjectrequiredShow propertiesHide properties
codestringmessagestringdetailsobjectfixErrorFixHow to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.
Show propertiesHide properties
summarystringrequiredOne sentence that says what to do.
commandstringAn exact anlyon CLI command that fixes it. Absent when no command does.
urlstring<uri>An absolute console link where a person fixes it.
docsstring<uri>A docs page that explains it.
Not Found - Resource does not exist
successbooleanrequiredrequestIdstringrequiredCorrelation ID matching the X-Request-Id response header.
errorobjectrequiredShow propertiesHide properties
codestringmessagestringdetailsobjectfixErrorFixHow to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.
Show propertiesHide properties
summarystringrequiredOne sentence that says what to do.
commandstringAn exact anlyon CLI command that fixes it. Absent when no command does.
urlstring<uri>An absolute console link where a person fixes it.
docsstring<uri>A docs page that explains it.
The request conflicts with current resource state or a concurrent decision.
successbooleanrequiredrequestIdstringrequiredCorrelation ID matching the X-Request-Id response header.
errorobjectrequiredShow propertiesHide properties
codestringmessagestringdetailsobjectfixErrorFixHow to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.
Show propertiesHide properties
summarystringrequiredOne sentence that says what to do.
commandstringAn exact anlyon CLI command that fixes it. Absent when no command does.
urlstring<uri>An absolute console link where a person fixes it.
docsstring<uri>A docs page that explains it.
Too Many Requests - Rate limit exceeded. A workspace's API requests are limited per minute and per UTC clock hour by plan; Retry-After says when to try again, and an hourly refusal names the limit and when the count resets. Successful responses carry the same limits in X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (the minute) and X-RateLimit-Limit-Hour, X-RateLimit-Remaining-Hour, X-RateLimit-Reset-Hour (the hour).
successbooleanrequiredrequestIdstringrequiredCorrelation ID matching the X-Request-Id response header.
errorobjectrequiredShow propertiesHide properties
codestringmessagestringdetailsobjectfixErrorFixHow to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.
Show propertiesHide properties
summarystringrequiredOne sentence that says what to do.
commandstringAn exact anlyon CLI command that fixes it. Absent when no command does.
urlstring<uri>An absolute console link where a person fixes it.
docsstring<uri>A docs page that explains it.

