Agent Coordination

When multiple agents operate on the same tenant, the coordination API prevents conflicts. Agents register themselves, maintain liveness via heartbeats, acquire exclusive leases on contacts, and run consensus votes for shared decisions.

Register an agent

POST https://api.molted.email/v1/agent/register

curl

curl -X POST https://api.molted.email/v1/agent/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "name": "outbound-agent",
    "config": {
      "humanizer_enabled": true,
      "humanizer_style": "professional"
    }
  }'

If an agent with the same tenant and name already exists, it is updated (upsert).

Response

{
  "id": "agent-1",
  "tenantId": "tenant_abc123",
  "name": "outbound-agent",
  "status": "active",
  "config": {
    "humanizer_enabled": true,
    "humanizer_style": "professional"
  },
  "lastHeartbeatAt": "2026-03-01T12:00:00Z",
  "createdAt": "2026-03-01T12:00:00Z",
  "updatedAt": "2026-03-01T12:00:00Z"
}

Heartbeat

Agents must send a heartbeat at least every 5 minutes to remain active. Agents that miss the heartbeat window are considered inactive and lose their leases.

POST https://api.molted.email/v1/agent/coordination/heartbeat

curl

curl -X POST https://api.molted.email/v1/agent/coordination/heartbeat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "agentId": "agent-1"
  }'

Contact leases

Leases give an agent exclusive access to a contact. While a lease is held, other agents' send requests for that contact are blocked with reason lease_conflict.

Acquire a lease

POST https://api.molted.email/v1/agent/coordination/lease

curl

curl -X POST https://api.molted.email/v1/agent/coordination/lease \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "agentId": "agent-1",
    "contactEmail": "user@example.com",
    "durationMinutes": 30
  }'

Field	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`agentId`	`string`	Yes	The agent acquiring the lease.
`contactEmail`	`string`	Yes	Contact to lease.
`durationMinutes`	`number`	No	Lease duration. Defaults to 30 minutes.

Release a lease

DELETE https://api.molted.email/v1/agent/coordination/lease/:id

curl

curl -X DELETE https://api.molted.email/v1/agent/coordination/lease/LEASE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

List active leases

GET https://api.molted.email/v1/agent/coordination/leases

curl

curl "https://api.molted.email/v1/agent/coordination/leases?tenantId=tenant_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": "lease_abc123",
    "agentId": "agent-1",
    "contactEmail": "user@example.com",
    "expiresAt": "2026-03-01T12:30:00Z",
    "createdAt": "2026-03-01T12:00:00Z"
  }
]

Consensus voting

When agents need to make a shared decision, they can create a consensus vote. Active agents (those with a heartbeat within the last 5 minutes) are eligible to vote. Majority wins.

Create a vote

POST https://api.molted.email/v1/agent/coordination/consensus

curl

curl -X POST https://api.molted.email/v1/agent/coordination/consensus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "agentId": "agent-1",
    "question": "Should we escalate user@example.com to human review?",
    "options": ["yes", "no"],
    "timeoutMinutes": 5
  }'

Field	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`agentId`	`string`	Yes	Agent creating the vote.
`question`	`string`	Yes	The question to vote on.
`options`	`array`	Yes	List of vote options.
`timeoutMinutes`	`number`	No	Time before the vote expires. Defaults to 5 minutes.

Cast a vote

POST https://api.molted.email/v1/agent/coordination/consensus/:id/vote

curl

curl -X POST https://api.molted.email/v1/agent/coordination/consensus/VOTE_ID/vote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-2",
    "vote": "yes"
  }'

Vote status

Status	Description
`pending`	Voting is still open.
`approved`	Majority voted in favor.
`rejected`	Majority voted against.
`expired`	The vote timed out before reaching a result.

On this page