AI Leases API Reference

Complete reference for long-running task management.

Create Lease

Endpoint: POST /v1/ai/lease

Request

curl -X POST https://api.onceonly.tech/v1/ai/lease \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support_chat_001",
    "ttl": 1800,
    "metadata": {
      "agent_id": "support_bot",
      "ticket_id": "TCK-123"
    }
  }'

Response - Acquired

{
  "ok": true,
  "status": "acquired",
  "key": "support_chat_001",
  "ttl": 1800,
  "ttl_left": null,
  "lease_id": "lease_abc123xyz",
  "version": 1,
  "first_seen_at": "2025-01-15T10:30:00Z",
  "done_at": null,
  "result_hash": null,
  "error_code": null,
  "retry_after_sec": null,
  "usage": 12,
  "limit": 3000,
  "charged": 1
}

usage and limit are example values. The actual monthly limit depends on your plan.

Response - Polling

{
  "ok": true,
  "status": "polling",
  "key": "support_chat_001",
  "ttl": 1800,
  "ttl_left": 1750,
  "lease_id": "lease_abc123xyz",
  "version": 1,
  "first_seen_at": "2025-01-15T10:30:00Z",
  "done_at": null,
  "result_hash": null,
  "error_code": null,
  "retry_after_sec": 5,
  "usage": 12,
  "limit": 3000,
  "charged": 0
}

Check Status

Endpoint: GET /v1/ai/status?key={key}

Response

{
  "ok": true,
  "status": "in_progress",
  "key": "support_chat_001",
  "ttl_left": 1500,
  "lease_id": "lease_abc123xyz",
  "version": 1,
  "first_seen_at": "2025-01-15T10:30:00Z",
  "done_at": null,
  "result_hash": null,
  "error_code": null,
  "retry_after_sec": 5
}

Extend Lease

Endpoint: POST /v1/ai/extend

Add more time to an active lease.

Request

curl -X POST https://api.onceonly.tech/v1/ai/extend \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support_chat_001",
    "lease_id": "lease_abc123xyz",
    "ttl": 1800
  }'

Response

{
  "ok": true,
  "status": "extended",
  "key": "support_chat_001",
  "ttl": 1800,
  "version": 2
}

Complete Lease

Endpoint: POST /v1/ai/complete

Mark lease as successfully completed.

Request

curl -X POST https://api.onceonly.tech/v1/ai/complete \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support_chat_001",
    "lease_id": "lease_abc123xyz",
    "result": {
      "status": "resolved",
      "messages": 15
    },
    "result_hash": "a1b2c3d4e5f6"
  }'

Response

{
  "ok": true,
  "status": "completed",
  "key": "support_chat_001",
  "version": 2
}

Cancel Lease

Endpoint: POST /v1/ai/cancel

Cancel a lease (reported as failed with error_code=canceled or canceled:<reason>).

Request

curl -X POST https://api.onceonly.tech/v1/ai/cancel \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support_chat_001",
    "lease_id": "lease_abc123xyz",
    "reason": "user_requested"
  }'

Response

{
  "ok": true,
  "status": "failed",
  "key": "support_chat_001",
  "version": 2
}

Fail Lease

Endpoint: POST /v1/ai/fail

Mark lease as failed with error.

Request

curl -X POST https://api.onceonly.tech/v1/ai/fail \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support_chat_001",
    "lease_id": "lease_abc123xyz",
    "error_code": "connection_lost"
  }'

Response

{
  "ok": true,
  "status": "failed",
  "key": "support_chat_001",
  "version": 2
}

Get Result

Endpoint: GET /v1/ai/result?key={key}

Response

{
  "ok": true,
  "status": "completed",
  "key": "support_chat_001",
  "result": {
    "status": "resolved",
    "messages": 15
  },
  "result_hash": "a1b2c3d4e5f6",
  "error_code": null,
  "done_at": "2025-01-15T10:45:00Z"
}

AI Run

POST /v1/ai/run is documented separately because it has two distinct modes:

keyed background execution
synchronous governed tool execution

See AI Run API for the full request and response flow.