API Reference

Human-in-the-Loop Tool Approval

When agents require human approval before executing certain tools, use these endpoints to approve or decline tool execution requests.

Overview

Human-in-the-Loop (HITL) allows you to require manual approval before your agent executes sensitive or high-impact tools. When an agent encounters a tool that requires approval, it will pause execution and wait for your decision.

Workflow

Agent encounters a tool that requires approval during execution
Agent pauses and sends an approval request event via SSE stream
Your application receives the event with a unique runId
Display the tool details to your user for review
Call /v1/hitl/approve or /v1/hitl/decline with the runId
Agent resumes execution (if approved) or stops (if declined)

CRITICAL: Keep SSE Connection Open
When you receive a tool-call-approval event, do NOT close the SSE connection. The agent waits on the same connection for your approve/decline response. Close the connection only after receiving the final 'complete' or 'error' event.

Approval Request Example

json

data: {
  "type": "meebly-event",
  "event": {
    "type": "tool-call-approval",
    "payload": {
      "runId": "run_abc123",
      "pendingApprovals": [
        {
          "toolCallId": "call_xyz789",
          "toolName": "delete_customer_data",
          "args": {
            "customerId": "12345",
            "includeBackups": false
          }
        }
      ]
    }
  },
  "isComplete": false
}

The pendingApprovals array can contain multiple tools requiring approval. You can approve/decline them individually or in batch by including multiple runIds. Each tool has a toolCallId, toolName, and argsso you can show users exactly what action the agent wants to perform.

Approve Tool Execution

POST/v1/hitl/approve

Approve a pending tool execution request, allowing the agent to proceed with the action.

Request Headers

bash

X-API-Key: YOUR_API_KEY
X-Backend-Token: YOUR_BACKEND_TOKEN (optional)

Examples

bash

curl -X POST "https://api.meebly.ai/v1/hitl/approve" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Backend-Token: YOUR_BACKEND_TOKEN" \
  -d '{
    "runId": "run_abc123",
    "environmentId": "env_xyz789"
  }'

javascript

// Approve a tool execution request
const response = await fetch("https://api.meebly.ai/v1/hitl/approve", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
    "X-Backend-Token": "YOUR_BACKEND_TOKEN"
  },
  body: JSON.stringify({
    runId: "run_abc123",
    environmentId: "env_xyz789"
  })
});

const result = await response.json();
if (response.ok) {
  console.log("Tool execution approved");
} else {
  console.error("Error:", result.error);
}

python

import requests

# Approve a tool execution request
response = requests.post(
    "https://api.meebly.ai/v1/hitl/approve",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
        "X-Backend-Token": "YOUR_BACKEND_TOKEN"
    },
    json={
        "runId": "run_abc123",
        "environmentId": "env_xyz789"
    }
)

if response.status_code == 200:
    print("Tool execution approved")
else:
    print("Error:", response.json().get("error"))

Decline Tool Execution

POST/v1/hitl/decline

Decline a pending tool execution request, preventing the agent from proceeding with the action.

Request Headers

bash

X-API-Key: YOUR_API_KEY
X-Backend-Token: YOUR_BACKEND_TOKEN (optional)

Examples

bash

curl -X POST "https://api.meebly.ai/v1/hitl/decline" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Backend-Token: YOUR_BACKEND_TOKEN" \
  -d '{
    "runId": "run_abc123",
    "environmentId": "env_xyz789"
  }'

javascript

// Decline a tool execution request
const response = await fetch("https://api.meebly.ai/v1/hitl/decline", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
    "X-Backend-Token": "YOUR_BACKEND_TOKEN"
  },
  body: JSON.stringify({
    runId: "run_abc123",
    environmentId: "env_xyz789"
  })
});

const result = await response.json();
if (response.ok) {
  console.log("Tool execution declined");
} else {
  console.error("Error:", result.error);
}

python

import requests

# Decline a tool execution request
response = requests.post(
    "https://api.meebly.ai/v1/hitl/decline",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
        "X-Backend-Token": "YOUR_BACKEND_TOKEN"
    },
    json={
        "runId": "run_abc123",
        "environmentId": "env_xyz789"
    }
)

if response.status_code == 200:
    print("Tool execution declined")
else:
    print("Error:", response.json().get("error"))

Parameters

Parameter	Type	Required	Description
`runId`	string	Yes	The unique identifier from the approval request event
`environmentId`	string	No	Environment context (optional)

Tool approval timeouts vary by agent configuration. If no response is received within the timeout period, the tool execution will be automatically declined.

PreviousWorkflows NextLogging & Monitoring

Last updated: March 2026Report an issue