Beta Program - 3 Months Free Business!

Join Beta Program
KirokuForms

Human-in-the-Loop API

KirokuForms provides a powerful Human-in-the-Loop (HITL) API that allows AI systems to request human input through dynamically generated forms when needed.

What is Human-in-the-Loop?

Human-in-the-Loop is a collaborative approach where AI systems can request human judgment for tasks that require:

  • Verification of AI-generated content
  • Decision-making in high-stakes situations
  • Additional information not available to the AI system
  • Judgment on ambiguous or subjective matters
  • Feedback to improve AI performance

KirokuForms implements HITL capabilities through the Model Context Protocol (MCP), which provides a standardized way for AI systems to request human input, wait for responses, and incorporate that feedback back into their workflows.

Key Concepts

HITL Tasks

A HITL task represents a request for human input. Each task includes:

  • Title - Brief description of what is being requested
  • Description - Detailed instructions for the human reviewer
  • Form - The interface used to collect the human input
  • Initial Data - Contextual information or pre-filled values
  • Expiration - Optional time limit for completing the task

Form Generation Methods

Forms for HITL tasks can be created in several ways:

  • Custom Field Definitions - Define each form field manually
  • Template-Based - Use a pre-defined form template
  • Data-Based - Dynamically generate fields based on data structure

Task Lifecycle

HITL tasks follow this lifecycle:

  1. Created - Task is initialized by the AI system
  2. Pending - Task is waiting for human input
  3. Completed - Human has provided the requested input
  4. Expired - Task has passed its expiration time without completion
  5. Cancelled - Task was explicitly cancelled

API Endpoints

Request Human Review (Task Creation)

Create HITL Task Endpoint 
POST /api/mcp/tools/request-human-review

This endpoint creates a new HITL task that will be presented to a human reviewer.

Request Body

Request Human Review - Custom Fields 
{
  "title": "Verify Customer Information",
  "description": "Please review this customer data for accuracy",
  "initialData": {
    "customer_name": "Acme Corp",
    "revenue": 1500000,
    "industry": "Technology"
  },
  "fields": [
    {
      "type": "text",
      "label": "Company Name",
      "name": "customer_name",
      "required": true,
      "defaultValue": "Acme Corp"
    },
    {
      "type": "number",
      "label": "Annual Revenue",
      "name": "revenue",
      "required": true
    },
    {
      "type": "radio",
      "label": "Information Verified?",
      "name": "is_verified",
      "required": true,
      "options": [
        {"label": "Yes, information is correct", "value": "yes"},
        {"label": "No, needs correction", "value": "no"}
      ]
    },
    {
      "type": "textarea",
      "label": "Notes",
      "name": "notes",
      "required": false,
      "placeholder": "Additional comments..."
    }
  ],
  "settings": {
    "expiration": "2h",
    "priority": "high",
    "callbackUrl": "https://your-server.com/webhooks/hitl"
  }
}

Alternative: Using a Template

Request Human Review - Using Template 
{
  "title": "Verify Customer Information",
  "description": "Please review this customer data for accuracy",
  "templateId": "customer-verification-template",
  "initialData": {
    "customer_name": "Acme Corp",
    "revenue": 1500000,
    "industry": "Technology"
  },
  "settings": {
    "expiration": "2h",
    "priority": "high",
    "callbackUrl": "https://your-server.com/webhooks/hitl"
  }
}

Response

Task Creation Response 
{
  "success": true,
  "data": {
    "taskId": "task-123456",
    "hitlTaskId": "hitl-abc123",
    "formId": "form-xyz789",
    "formUrl": "https://www.kirokuforms.com/hitl/task/task-123456?token=abc...xyz"
  },
  "message": "Human review task created successfully"
}

Get Task Status

Get Task Status Endpoint 
GET /api/mcp/resources/hitl/tasks/{taskId}

This endpoint retrieves the current status and details of a HITL task.

Response

Task Status Response 
{
  "success": true,
  "data": {
    "id": "hitl-abc123",
    "taskId": "task-123456",
    "title": "Verify Customer Information",
    "description": "Please review this customer data for accuracy",
    "status": "pending",
    "createdAt": "2025-01-15T14:30:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "expiresAt": "2025-01-15T16:30:00Z",
    "formId": "form-xyz789",
    "template": {
      "id": "customer-verification-template",
      "name": "Customer Verification",
      "fields": [
        // Field definitions...
      ]
    },
    "initialData": {
      "customer_name": "Acme Corp",
      "revenue": 1500000,
      "industry": "Technology"
    },
    "submission": null,
    "accessTokens": [
      {
        "id": "token-123",
        "token": "abc...xyz",
        "expiresAt": "2025-01-15T16:30:00Z"
      }
    ]
  }
}

Get Completed Task Result

Get Task Result Endpoint 
GET /api/mcp/resources/hitl/tasks/{taskId}/result

This endpoint retrieves the submission data for a completed HITL task.

Response (Completed Task)

Completed Task Result 
{
  "success": true,
  "data": {
    "customer_name": "Acme Corporation",
    "revenue": 1750000,
    "industry": "Technology",
    "is_verified": "yes",
    "notes": "Updated company name and revenue based on latest filing."
  }
}

Response (Pending Task)

Pending Task Response 
{
  "success": false,
  "error": {
    "code": "TASK_NOT_COMPLETED",
    "message": "Task is still pending completion"
  }
}

Cancel Task

Cancel Task Endpoint 
POST /api/mcp/resources/hitl/tasks/{taskId}/cancel

This endpoint cancels a pending HITL task.

Response

Cancel Task Response 
{
  "success": true,
  "data": {
    "taskId": "task-123456",
    "status": "cancelled"
  },
  "message": "Task cancelled successfully"
}

Field Types

The HITL API supports these field types for form generation:

Type Description Properties
text Single-line text input label, name, required, defaultValue, placeholder, validation
textarea Multi-line text input label, name, required, defaultValue, placeholder, rows, validation
number Numeric input label, name, required, defaultValue, min, max, step, validation
email Email input with validation label, name, required, defaultValue, placeholder, validation
select Dropdown selection label, name, required, defaultValue, options, validation
radio Radio button group label, name, required, defaultValue, options, validation
checkbox Checkbox or checkbox group label, name, required, defaultValue, options, validation
date Date picker label, name, required, defaultValue, min, max, validation

Webhook Integration

Webhooks allow your application to receive real-time notifications when HITL tasks are completed. To use webhooks, provide a callbackUrl in the task settings.

Webhook Payload

Webhook Payload Example 
{
  "eventType": "hitl.task.completed",
  "taskId": "task-123456",
  "timestamp": "2025-01-15T15:30:00Z",
  "data": {
    "status": "completed",
    "formData": {
      // The submitted form data
      "customer_name": "Acme Corporation",
      "revenue": 1750000,
      "industry": "Technology",
      "is_verified": "yes",
      "notes": "Updated company name and revenue based on latest filing."
    }
  }
}
Webhook Signature Header 
KirokuForms-Signature: t=1642260000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce308175258

Next Steps

Now that you understand the HITL API basics:

  1. Integrate with LangGraph for AI workflow orchestration
  2. Create a webhook handler for asynchronous workflows
  3. Explore form generation for creating dynamic forms
  4. Browse example implementations for common use cases