CLAIM

What it does

Acquire an exclusive lease or a capacity-limited semaphore, renew before expiry and release when finished. Increasing fencing tokens help cooperating consumers reject stale workers.

Public developer beta: documentation, signup and free usage are available. Use your product API key for requests; public examples do not require Vercel preview access. Paid subscriptions are available; free usage remains available.

First request

Create a project in the account page and save the API key shown once. Use it as a bearer token. Keep keys in server-side configuration.

curl https://claim.aiagenthuddle.com/v1/leases \
  -H "Authorization: Bearer $CLAIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"job/123","agent_id":"worker-a","ttl_seconds":30,"request_id":"12345678-1234-4123-8123-123456789012"}'

A competing worker receives DENIED. Lease expiry removes authority; it does not terminate the worker. Keep the original request_id when retrying an uncertain acquisition.

REST endpoints

Failure behaviour and limits

• Fencing tokens are decimal strings. Compare them as integers and enforce them in the downstream system that commits the effect. A lease cannot stop an expired worker by itself.
• Use a stable request_id when retrying the same acquire, renew or release request. Without it, another acquire is a new operation. A replay cannot revive an expired lease.
• Successful release receipts replay their original result. A fresh release returning NOT_ACTIVE does not store or reserve its request ID, so different input using that unrecorded ID can be treated as a new request. Use distinct IDs for distinct requests. Stored receipts reject different-input reuse.
• Resources are isolated by project. Default mode is exclusive; semaphore mode requires an explicit capacity.
• The hosted preview passed one 1,000-request exclusive burst and one capacity-five burst after connection-limit failures were repaired. This is correctness evidence under those conditions, not an unlimited-throughput SLA.

Request bodies are limited to 16 KiB. Missing, revoked or cross-product keys are rejected. Rate limits return HTTP 429; service unavailability remains an error rather than a successful operation.

Engineering notes

An expired lease cannot stop a worker: a concrete failure scenario and the limits of the recovery mechanism.

MCP and SDK access

JavaScript · Node.js

Save the module as sdk.js in a project with "type": "module". The client uses the built-in fetch API.

import { ClaimClient } from './sdk.js';

const claim = new ClaimClient(
  'https://claim.aiagenthuddle.com',
  process.env.CLAIM_API_KEY
);

const result = await claim.acquire({
  resource: 'job/123', agent_id: 'worker-a',
  ttl_seconds: 30, request_id: crypto.randomUUID()
});
// Inspect GRANTED / DENIED before starting work.
// Enforce the granted fencing token downstream.
console.log(result);

Authenticated stateless MCP is available at /mcp. Tools: claim_acquire, claim_renew, claim_release, claim_status, claim_wait. Official current and legacy clients have passed protected hosted checks. No resumable SSE sessions or unsupported MCP features are advertised.

The standalone JavaScript client is available directly. Download sdk.js into your server-side project. No npm package is published. Keep credentials outside browser bundles.

Usage, privacy and support

Free preview access includes 1,000 ordinary request units per UTC month. Existing-operation recovery and lease cleanup have a separate rate allowance. Read the service terms, usage limits, privacy notice and support information before integrating. Download the standalone JavaScript module; no npm package is published.