Mint a private namespace
curl -X POST https://aisenseapi.com/services/v1/lease/namespace \
-H "Content-Type: application/json" \
-d '{}'{
"ok": true,
"namespace": "ns_XbO8a6V9e5dMWYqghfPV3ykHTNpR3oZ0fQJm4l7K2nE",
"entropy_bits": 256
}The namespace is a bearer secret with 256 random bits. Keep it in your own job state. AI SENSE cannot list or recover it for you.
A namespace lets you use readable keys such as invoice:2026-09-05. Without one, the key itself must be a high-entropy ASCII value from 32 to 200 characters.
Acquire a lease
curl -X POST https://aisenseapi.com/services/v1/lease \
-H "Content-Type: application/json" \
-d '{
"namespace": "ns_XbO8a6V9e5dMWYqghfPV3ykHTNpR3oZ0fQJm4l7K2nE",
"key": "invoice:2026-09-05",
"ttl_seconds": 60,
"fingerprint": "charge-order-501"
}'{
"ok": true,
"status": "held",
"owner_token": "own_lCzWFx9BTqNkKlQJYu8jXdDX7n8h4xTJsU5BzPq3yLk",
"ttl_seconds": 60,
"fencing_token": 184,
"lease_expires_at_timestamp": 1788602460,
"lease_expires_at": "2026-09-05T10:01:00Z",
"absolute_expires_at_timestamp": 1788688800,
"absolute_expires_at": "2026-09-06T10:00:00Z"
}POST /lease/acquire is an explicit alias for POST /lease. The first acquisition returns HTTP 201. ttl_seconds defaults to 60 and accepts integers from 1 to 86400.
Handle another worker
A second acquisition while the lease is active returns HTTP 409. It does not expose the owner token.
{
"ok": false,
"status": "held",
"error": "Lease is held",
"retry_after_seconds": 43,
"fencing_token": 184,
"lease_expires_at": "2026-09-05T10:01:00Z",
"absolute_expires_at": "2026-09-06T10:00:00Z"
}The response also sets the HTTP Retry-After header. Wait that long or do other work. When the lease expires or is released, another caller can acquire it and receives a higher fencing token.
Use the fencing token
A lease alone cannot stop a paused worker from waking after its ownership ended. Send fencing_token with writes to the protected system. That system should remember the highest value and reject any older one.
- Worker A gets fence 184
It starts work and then pauses.
- The lease expires
Worker B acquires the same key and gets fence 185.
- Worker A wakes up
The protected system rejects its write because 184 is older than 185.
Renew, release or complete
Each mutation needs the original namespace, key and secret owner token.
POST /lease/renew
{ "namespace": "ns_...", "key": "invoice:2026-09-05",
"owner_token": "own_...", "ttl_seconds": 120 }
POST /lease/release
{ "namespace": "ns_...", "key": "invoice:2026-09-05",
"owner_token": "own_..." }
POST /lease/complete
{ "namespace": "ns_...", "key": "invoice:2026-09-05",
"owner_token": "own_...", "result": { "receipt_id": 4817 } }| Action | Result |
|---|---|
renew | Moves the short lease expiry and keeps the same fencing token. |
release | Ends ownership and makes the key available at once. |
complete | Stores a reusable JSON result and removes the owner secret. |
An old, invalid or expired owner receives HTTP 409 with status: "lost". It cannot renew, release or complete a newer lease.
MCP clients use create_lease_namespace, acquire_lease, renew_lease, release_lease and complete_lease for the same flow.
Reuse completed work
Acquire the same namespace, key and fingerprint after completion. The service returns HTTP 200 with status: "completed" and the saved result. It does not issue another owner token.
{
"ok": true,
"status": "completed",
"completed_at": "2026-09-05T10:00:38Z",
"result": { "receipt_id": 4817 },
"fencing_token": 184,
"absolute_expires_at": "2026-09-06T10:00:00Z"
}Use fingerprint to bind a key to its input. Reusing the key with another fingerprint returns HTTP 409 and status: "conflict". This catches accidental idempotency-key reuse before the old 24-hour lifecycle ends.
The 24-hour boundary
The first acquisition starts a fixed 24-hour lifecycle. Short leases may be renewed many times, but no renewal can move absolute_expires_at. Near that boundary the returned ttl_seconds is reduced to the time left.
An acquisition after the absolute expiry starts a fresh lifecycle and receives a new, higher fencing token. Old state is removed by an hourly cleanup.
Data and secrets
Treat the namespace, key, fingerprint and owner token as secrets. Anyone who knows the values used to identify the work can test the lease or read a completed result.
Raw namespaces, keys, owner tokens and fingerprints are not written to disk. The service stores SHA-256 hashes, timing state, the fencing token and an optional completed result.
A completed result may be at most 32 KB as JSON. Fields named like authorization, password, secret, token, private_key or api_key are replaced with [redacted] before storage. A secret inside an ordinary field value cannot be identified safely. Keep secrets and personal data out of results.
Useful flows
Duplicate agent runs
Let one worker perform the job while the others wait or reuse its result.
Webhook idempotency
Bind an incoming event ID to a fingerprint and return the first completed result.
Scheduled jobs
Prevent two temporary workers from processing the same item at once.
External writes
Use fencing tokens to stop a stale owner from overwriting newer work.