LoopIn

Human-in-the-loop interrupt API for AI agents.

LoopIn lets AI agents pause at critical decision points, request human review, and resume execution based on the human's decision. No more agents making high-stakes calls alone.

Why LoopIn?

Autonomous agents are powerful — until they hit a decision they shouldn't make without a human. LoopIn gives every agent a safe exit ramp:

1. Agent hits a decision point → calls POST /interrupts
2. LoopIn notifies the human → via webhook or a direct review URL
3. Human approves or rejects → via the review page or POST /interrupts/:id/decide
4. Agent polls for the decision → GET /interrupts/:id
5. Agent resumes → using the decision (and any modified params the human provided)

Endpoints

POST /interrupts

Create a new interrupt request.

Request:

{
  "agentId": "agent-payments-v2",
  "userId": "user-123",
  "action": "Transfer $4,200 to vendor account ending in 9821",
  "context": {
    "vendor": "Acme Supplies",
    "amount": 4200,
    "currency": "USD",
    "invoiceId": "INV-2024-0892",
    "accountLast4": "9821"
  },
  "urgency": "high",
  "expiresIn": 1800,
  "callbackUrl": "https://my-agent.example.com/webhooks/loopin"
}

Response:

{
  "interruptId": "3f4e2a1b-...",
  "status": "pending",
  "expiresAt": "2024-04-12T14:30:00Z",
  "reviewUrl": "http://localhost:3002/review/3f4e2a1b-..."
}

GET /interrupts/:interruptId

Poll for the current status and decision.

Response (pending):

{
  "interruptId": "3f4e2a1b-...",
  "status": "pending",
  "action": "Transfer $4,200 to vendor account ending in 9821",
  "context": { ... },
  "urgency": "high",
  "createdAt": "2024-04-12T13:00:00Z",
  "expiresAt": "2024-04-12T14:30:00Z",
  "reviewUrl": "http://localhost:3002/review/3f4e2a1b-..."
}

Response (resolved):

{
  "interruptId": "3f4e2a1b-...",
  "status": "approved",
  "decision": "approved",
  "decidedAt": "2024-04-12T13:07:22Z",
  "reason": "Invoice verified, proceed."
}

POST /interrupts/:interruptId/decide

Submit a human decision.

Request:

{
  "decision": "approved",
  "reason": "Invoice verified, proceed.",
  "modifiedParams": { "amount": 4200 }
}

Response:

{
  "interruptId": "3f4e2a1b-...",
  "status": "resolved",
  "decision": "approved",
  "decidedAt": "2024-04-12T13:07:22Z"
}

GET /interrupts/pending/:userId

List all pending interrupts waiting for a user's review.

Response:

[
  {
    "interruptId": "3f4e2a1b-...",
    "action": "Transfer $4,200 to vendor...",
    "urgency": "high",
    "createdAt": "...",
    "expiresAt": "...",
    "reviewUrl": "..."
  }
]

DELETE /interrupts/:interruptId

Cancel a pending interrupt (agent no longer needs the decision).

GET /analytics/:userId

Usage statistics.

Response:

{
  "userId": "user-123",
  "totalInterrupts": 47,
  "approvalRate": 0.83,
  "avgResponseTimeMs": 142000,
  "byStatus": { "approved": 39, "rejected": 8 },
  "byUrgency": { "high": 12, "medium": 28, "low": 7 },
  "topActionTypes": [
    { "action": "Send payment", "count": 18 },
    { "action": "Delete records", "count": 9 }
  ]
}

Review Page

Every interrupt gets a human-readable review URL:

GET /review/:interruptId

This renders an HTML page showing:

• What the agent wants to do
• All context data (formatted JSON)
• Urgency badge
• Approve / Reject buttons
• Optional reason text field

Share this URL with whoever needs to review the request. No login required by default.

MCP Tools

The LoopIn MCP server exposes all 6 tools for use with any MCP-compatible AI client (Claude Desktop, Cursor, etc.):

MCP Server setup (stdio)

{
  "mcpServers": {
    "loopin": {
      "command": "npx",
      "args": ["-y", "@colossal-api/loopin-mcp"],
      "env": {
        "LOOPIN_API_URL": "https://your-loopin-instance.railway.app",
        "LOOPIN_API_KEY": "your-key"
      }
    }
  }
}

Agent Usage Pattern

1. Agent reaches a decision point
   → POST /interrupts { agentId, userId, action, context, urgency }
   ← { interruptId, reviewUrl }

2. Agent saves interruptId and pauses
   → (optionally: notify human via other channels with reviewUrl)

3. Agent polls until resolved
   → GET /interrupts/:interruptId
   ← { status: "pending" }   ← keep polling
   ← { status: "approved", decision, modifiedParams }  ← resume

4. Agent resumes execution
   → use modifiedParams if provided, otherwise proceed as planned

Human Usage Pattern

Option A — Review URL (simplest)

1. Receive the reviewUrl from the agent (via email, Slack, etc.)
2. Open the URL in any browser
3. Review the context, click Approve or Reject, add optional reason
4. Done — the agent gets the decision on its next poll

Option B — List pending (dashboard)

1. GET /interrupts/pending/:userId — see all open requests
2. Open individual reviewUrls or call POST /interrupts/:id/decide directly

Environment Variables

Colossal API Portfolio

LoopIn is part of the Colossal API suite of infrastructure APIs for AI agents:

• SubRadar — Subscription detection and cancellation
• MeetSync — Calendar negotiation and scheduling
• LoopIn — Human-in-the-loop interrupt and approval

All products share the same design philosophy: simple REST APIs with MCP server wrappers so agents can use them natively.