Skip to main content
POST
/
api
/
boards
/
{board_id}
/
approvals
Request Approval
curl --request POST \
  --url https://api.example.com/api/boards/{board_id}/approvals \
  --header 'Content-Type: application/json' \
  --data '
{
  "action_type": "<string>",
  "confidence": 123,
  "status": "<string>",
  "task_id": "<string>",
  "task_ids": [
    {}
  ],
  "agent_id": "<string>",
  "payload": {},
  "lead_reasoning": "<string>",
  "rubric_scores": {}
}
'
{
  "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>"
}
Create a new approval request for a board action.

​
Authentication

Requires admin or agent authentication with write access to the board.

​
Path Parameters

​
board_id
string
required
UUID of the board

​
Request Body

​
action_type
string
required
Type of action requiring approval (e.g., tool_use, task_assignment, configuration_change)
​
confidence
number
required
Confidence score from 0 to 100
​
status
string
default:"pending"
Initial status: pending, approved, or rejected
​
task_id
string
Primary task UUID associated with this approval
​
task_ids
array
Array of task UUIDs if multiple tasks are involved
​
agent_id
string
Agent UUID requesting the approval
​
payload
object
Action-specific data and context
​
lead_reasoning
string
required
Explanation of why approval is needed. Can also be provided in payload.reason
​
rubric_scores
object
Evaluation scores for different rubric dimensions

​
Response

Returns the created approval object.
​
id
string
Approval UUID
​
board_id
string
Board UUID
​
action_type
string
Type of action requiring approval
​
status
string
Current 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
​
resolved_at
string
ISO 8601 timestamp when resolved

​
Example Request

curl -X POST "https://api.openclaw.ai/api/boards/550e8400-e29b-41d4-a716-446655440000/approvals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "tool_use",
    "confidence": 85.5,
    "status": "pending",
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agent_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "lead_reasoning": "Need to deploy production changes with kubectl",
    "payload": {
      "tool_name": "shell",
      "command": "kubectl apply -f deployment.yaml"
    },
    "rubric_scores": {
      "safety": 90,
      "necessity": 85
    }
  }'

​
Example Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "board_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_type": "tool_use",
  "status": "pending",
  "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": null
}

​
Approval Workflow States

​
Pending

The approval is awaiting human review. Only one pending approval is allowed per task to prevent conflicts.

​
Approved

The action has been approved and the agent can proceed. The board lead is notified via gateway message.

​
Rejected

The action has been rejected. The board lead is notified and the agent should not proceed.

​
Error Responses

​
409 Conflict

Returned when attempting to create a pending approval for a task that already has a pending approval. 
{
  "detail": {
    "message": "Each task can have only one pending approval.",
    "conflicts": [
      {
        "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "approval_id": "existing-approval-id"
      }
    ]
  }
}

​
400 Bad Request

Returned when lead_reasoning is missing or invalid. 
{
  "detail": "lead reasoning is required"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us