Skip to main content
PATCH
/
api
/
boards
/
{board_id}
/
approvals
/
{approval_id}
Review Approval
curl --request PATCH \
  --url https://api.example.com/api/boards/{board_id}/approvals/{approval_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "<string>"
}
'
{
  "id": "<string>",
  "board_id": "<string>",
  "action_type": "<string>",
  "status": "<string>",
  "confidence": 123,
  "task_id": "<string>",
  "task_ids": [
    {}
  ],
  "task_titles": [
    {}
  ],
  "agent_id": "<string>",
  "payload": {},
  "rubric_scores": {},
  "created_at": "<string>",
  "resolved_at": "<string>"
}
Update an approval’s status to approve or reject a pending action.

​
Authentication

Requires user authentication with write access to the board.

​
Path Parameters

​
board_id
string
required
UUID of the board
​
approval_id
string
required
UUID of the approval to update

​
Request Body

​
status
string
required
New status: pending, approved, or rejected

​
Response

Returns the updated approval object.
​
id
string
Approval UUID
​
board_id
string
Board UUID
​
action_type
string
Type of action
​
status
string
Updated status: pending, approved, or rejected
​
confidence
number
Confidence score (0-100)
​
task_id
string
Primary task UUID
​
task_ids
array
Array of associated task UUIDs
​
task_titles
array
Array of task titles
​
agent_id
string
Agent UUID
​
payload
object
Action payload
​
rubric_scores
object
Rubric scores
​
created_at
string
ISO 8601 timestamp when created
​
resolved_at
string
ISO 8601 timestamp when status changed to approved/rejected

​
Example Request - Approve

curl -X PATCH "https://api.openclaw.ai/api/boards/550e8400-e29b-41d4-a716-446655440000/approvals/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved"
  }'

​
Example Request - Reject

curl -X PATCH "https://api.openclaw.ai/api/boards/550e8400-e29b-41d4-a716-446655440000/approvals/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "rejected"
  }'

​
Example Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "board_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_type": "tool_use",
  "status": "approved",
  "confidence": 85.5,
  "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "task_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "task_titles": ["Deploy backend service"],
  "agent_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "payload": {
    "tool_name": "shell",
    "command": "kubectl apply -f deployment.yaml",
    "reason": "Need to deploy production changes with kubectl"
  },
  "rubric_scores": {
    "safety": 90,
    "necessity": 85
  },
  "created_at": "2026-03-05T10:30:00Z",
  "resolved_at": "2026-03-05T10:35:00Z"
}

​
Behavior

​
Approval Resolution

When an approval is approved or rejected:
  1. The resolved_at timestamp is set to the current time
  2. The status changes to approved or rejected
  3. The board lead agent receives a notification via the OpenClaw gateway

​
Lead Notification Message

The board lead receives a message with the following format: 
APPROVAL RESOLVED
Board: Production Board
Approval ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Action: tool_use
Decision: approved
Confidence: 85.5
Task ID: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Take action: continue execution using the final approval decision.

​
Reverting to Pending

You can change an approval back to pending status. When reverting from approved or rejected to pending:
  • The system validates that no other pending approval exists for the same tasks
  • If conflicts exist, a 409 Conflict error is returned

​
Error Responses

​
404 Not Found

{
  "detail": "Approval not found"
}

​
409 Conflict

Returned when trying to set status to pending but another pending approval exists for the same task. 
{
  "detail": {
    "message": "Each task can have only one pending approval.",
    "conflicts": [
      {
        "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "approval_id": "other-approval-id"
      }
    ]
  }
}

​
Activity Log

Approval resolution events are logged to the activity feed:
  • approval.lead_notified: Lead was successfully notified
  • approval.lead_notify_failed: Notification to lead failed

Build docs developers (and LLMs) love

Get started for freeTalk to us