Approvals
List approvals
Requests an agent made to run an action that its tool policy puts behind a person: refunds, credits, writes. Newest first. Filter by status=pending to build a queue of what waits for a decision. Read only and safe to repeat. To change what needs approval, grant the tool with an approval policy: PUT /v2/agents/{id}/tools/{toolId}.
Required scope: approvals:read.
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
statusagentIdcaseIdHeaders
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List approvals › Responses
objecthasMorenextCursorRetrieve an approval
The exact arguments the action will run with, why it needed approval, who may decide it, who decided and why, and what the action returned. Use it before deciding, and to answer a claim afterwards. Read only and safe to repeat.
Required scope: approvals:read.
path Parameters
id^apr_[0-9A-Za-z]{22}… · requiredThe id of the approval (apr_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Retrieve an approval › Responses
objectidstatuspending waits for a decision. approved, executing, executed and failed follow an approval: the action runs only after it. rejected, expired and canceled never run it. preview only appears in the answer of approve with dryRun=true: the approval as it is now, with the decision that would be recorded; nothing was decided or run.
agentIdcaseIdtoolThe name of the action or tool the agent wants to run.
The exact arguments the action will run with if approved. Null when the tool is noPersist: those are kept encrypted and shown to nobody.
summaryA line for a person to read. For a noPersist tool it is only the name.
reasonCodeWhy it needed approval: policy_always, policy_condition (the condition on its arguments held), policy_accumulated (the sum for this contact in the period passed the limit) or policy_rule (a rule of the policy asked for it: see ruleIndex).
ruleIndexThe position (from 0) of the rule of the policy that decided this, when reasonCode is policy_rule. Null otherwise.
automatedDecisionTrue when the policy marks this as an automated decision about a person (Ley 21.719, art. 8 bis). The person may ask for a review.
dataSeenThe names of the argument fields the approver was shown. Never their values.
requestedByKeyIdThe API key whose turn proposed the action, if any. It can never decide this request.
resultWhat the action returned once it ran. Truncated.
executedAtexpiresAtescalatedAtreviewRequestedAtreviewReasonWhat the person said when they asked for the review: their point of view on the decision. Null if they gave none or no review was asked.
createdAtupdatedAtApprove an action
Approves the request and runs the action now, with the arguments you read in the approval; then the agent resumes the conversation with the result. This has the real effect of the action: it can move money or write to a person. It works only if the tool policy names this key as approver, the key has the approvals:write scope and the request was not created by this same key. Not idempotent: a request is decided once, and a second decision answers 409 approval_not_pending. A reason is required. Use dryRun=true to run the same checks (reason, key allowed to decide, still pending) and get the approval as it would end, without deciding or running anything.
Required scope: approvals:write.
path Parameters
id^apr_[0-9A-Za-z]{22}… · requiredThe id of the approval (apr_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Approve an action › Request Body
reason^[^\u0000]*$ · requiredWhy you decide this. Required for approving and for rejecting. It is stored with the decision and read by the auditor.
The person in your system who decided. Lelemon records it as declared by this key, not verified. A key cannot declare a role above its own.
Approve an action › Responses
objectidstatuspending waits for a decision. approved, executing, executed and failed follow an approval: the action runs only after it. rejected, expired and canceled never run it. preview only appears in the answer of approve with dryRun=true: the approval as it is now, with the decision that would be recorded; nothing was decided or run.
agentIdcaseIdtoolThe name of the action or tool the agent wants to run.
The exact arguments the action will run with if approved. Null when the tool is noPersist: those are kept encrypted and shown to nobody.
summaryA line for a person to read. For a noPersist tool it is only the name.
reasonCodeWhy it needed approval: policy_always, policy_condition (the condition on its arguments held), policy_accumulated (the sum for this contact in the period passed the limit) or policy_rule (a rule of the policy asked for it: see ruleIndex).
ruleIndexThe position (from 0) of the rule of the policy that decided this, when reasonCode is policy_rule. Null otherwise.
automatedDecisionTrue when the policy marks this as an automated decision about a person (Ley 21.719, art. 8 bis). The person may ask for a review.
dataSeenThe names of the argument fields the approver was shown. Never their values.
requestedByKeyIdThe API key whose turn proposed the action, if any. It can never decide this request.
resultWhat the action returned once it ran. Truncated.
executedAtexpiresAtescalatedAtreviewRequestedAtreviewReasonWhat the person said when they asked for the review: their point of view on the decision. Null if they gave none or no review was asked.
createdAtupdatedAtdryRunPresent and true when the request had dryRun=true.
Reject an action
Rejects the request: the action never runs and the agent tells the person it was not done. Same rules as approve: the policy must name this key, and a request is decided once (409 approval_not_pending after that). A reason is required.
Required scope: approvals:write.
path Parameters
id^apr_[0-9A-Za-z]{22}… · requiredThe id of the approval (apr_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Reject an action › Request Body
reason^[^\u0000]*$ · requiredWhy you decide this. Required for approving and for rejecting. It is stored with the decision and read by the auditor.
The person in your system who decided. Lelemon records it as declared by this key, not verified. A key cannot declare a role above its own.
Reject an action › Responses
objectidstatuspending waits for a decision. approved, executing, executed and failed follow an approval: the action runs only after it. rejected, expired and canceled never run it. preview only appears in the answer of approve with dryRun=true: the approval as it is now, with the decision that would be recorded; nothing was decided or run.
agentIdcaseIdtoolThe name of the action or tool the agent wants to run.
The exact arguments the action will run with if approved. Null when the tool is noPersist: those are kept encrypted and shown to nobody.
summaryA line for a person to read. For a noPersist tool it is only the name.
reasonCodeWhy it needed approval: policy_always, policy_condition (the condition on its arguments held), policy_accumulated (the sum for this contact in the period passed the limit) or policy_rule (a rule of the policy asked for it: see ruleIndex).
ruleIndexThe position (from 0) of the rule of the policy that decided this, when reasonCode is policy_rule. Null otherwise.
automatedDecisionTrue when the policy marks this as an automated decision about a person (Ley 21.719, art. 8 bis). The person may ask for a review.
dataSeenThe names of the argument fields the approver was shown. Never their values.
requestedByKeyIdThe API key whose turn proposed the action, if any. It can never decide this request.
resultWhat the action returned once it ran. Truncated.
executedAtexpiresAtescalatedAtreviewRequestedAtreviewReasonWhat the person said when they asked for the review: their point of view on the decision. Null if they gave none or no review was asked.
createdAtupdatedAtAsk for a human review of a decision
Use it when the person affected by a decision asks for it to be reviewed (Ley 21.719, art. 8 bis). It works only on a decided approval whose policy has automatedDecision. It fires the approval.review_requested webhook so your team can act, and it changes nothing else. Idempotent: asking twice fires the event once.
Required scope: approvals:write.
path Parameters
id^apr_[0-9A-Za-z]{22}… · requiredThe id of the approval (apr_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Ask for a human review of a decision › Request Body optional
reasonThe point of view of the person on the decision, in their words. It is stored with the record, shown in reviewReason and sent in the review_requested event. Do not put anything the person did not say.
Ask for a human review of a decision › Responses
objectidstatuspending waits for a decision. approved, executing, executed and failed follow an approval: the action runs only after it. rejected, expired and canceled never run it. preview only appears in the answer of approve with dryRun=true: the approval as it is now, with the decision that would be recorded; nothing was decided or run.
agentIdcaseIdtoolThe name of the action or tool the agent wants to run.
The exact arguments the action will run with if approved. Null when the tool is noPersist: those are kept encrypted and shown to nobody.
summaryA line for a person to read. For a noPersist tool it is only the name.
reasonCodeWhy it needed approval: policy_always, policy_condition (the condition on its arguments held), policy_accumulated (the sum for this contact in the period passed the limit) or policy_rule (a rule of the policy asked for it: see ruleIndex).
ruleIndexThe position (from 0) of the rule of the policy that decided this, when reasonCode is policy_rule. Null otherwise.
automatedDecisionTrue when the policy marks this as an automated decision about a person (Ley 21.719, art. 8 bis). The person may ask for a review.
dataSeenThe names of the argument fields the approver was shown. Never their values.
requestedByKeyIdThe API key whose turn proposed the action, if any. It can never decide this request.
resultWhat the action returned once it ran. Truncated.
executedAtexpiresAtescalatedAtreviewRequestedAtreviewReasonWhat the person said when they asked for the review: their point of view on the decision. Null if they gave none or no review was asked.
createdAtupdatedAt