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": 1000,
  "charged": 1
}

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": 1000,
  "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": 3
}

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": 4
}

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": 4
}

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"
}

Run (Legacy / Test Runner)

Endpoint: POST /v1/ai/run

Two modes:

Mode A (legacy): key + optional ttl/metadata (returns the same shape as /v1/ai/lease).
Mode B (test runner): agent_id + tool + args (returns policy decision + optional result).

Request (Mode A)

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

Request (Mode B)

curl -X POST https://api.onceonly.tech/v1/ai/run \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "support_bot",
    "tool": "send_email",
    "args": {"to": "user@example.com"},
    "spend_usd": 0.001
  }'

Response (Mode B)

{
  "ok": true,
  "allowed": true,
  "decision": "executed",
  "policy_reason": "ok",
  "risk_level": "low",
  "result": {"status": "sent"}
}