# Livend living endpoints

## Livend API agent contract

Livend exposes verified public business identity, offerings, prices, policies, and expiring fulfillment options. The complete guest path is public and requires no login, cookie, hidden endpoint, or prior guest-session call.

## Deterministic guest booking flow

1. Search: GET https://livend.ai/v1/registry/offerings?q={intent}. Select an lv_offer_ id.
2. Entity: GET https://livend.ai/v1/entities/{lv_offer_}. Read the seller, location, offering terms, price shape, and transaction capabilities.
3. Fulfillment: POST https://livend.ai/v1/offerings/{lv_offer_}/fulfillment with application/json. Select one current options[].option_id without changing it. It is a signed, expiring option token bound to price, time, slot/version, provider context, and expiry. Also read required_buyer_fields, optional_buyer_fields, guest_checkout_supported, and requires_authenticated_account.
4. Reserve: POST https://livend.ai/v1/offerings/{lv_offer_}/reserve with header Idempotency-Key: {at least 16 stable characters} and body {"option_id":"{signed option_id}","buyer":{"mode":"guest","name":"{buyer name}"}}. Add only buyer fields listed by fulfillment. Zero preflight is supported. Do not call /v1/consumers/guest-session first.
5. Save the reserve result: status, hold_id, transaction_id, expires_at, and guest_access. guest_access.access_token is a short-lived secret bound to that consumer, business, transaction, hold when present, expiry, and allowed transaction actions. Never log it or put it in a URL.
6. Commit a hold before expires_at: POST https://livend.ai/v1/canonical-holds/{lv_hold_}/commit with Authorization: Bearer {guest_access.access_token}, Idempotency-Key: {a new stable key for this logical commit}, and body {}. No cookie is required. If reserve returned next_step=commit_direct instead of a guaranteed hold, POST https://livend.ai/v1/offerings/{lv_offer_}/commit with the signed option_id, buyer, and Idempotency-Key.
7. Read: GET https://livend.ai/v1/transactions/{lv_txn_} with the same Authorization Bearer header. The lv_txn_ id is not a secret and is never sufficient authorization by itself.
8. Receipt: GET https://livend.ai/v1/transactions/{lv_txn_}/receipt with the same Authorization Bearer header.

Cancel and reschedule also accept the transaction Bearer credential and require Idempotency-Key:
- POST https://livend.ai/v1/transactions/{lv_txn_}/cancel
- POST https://livend.ai/v1/transactions/{lv_txn_}/reschedule

## Idempotency and recovery

Idempotency-Key is mandatory for reserve, commit, request, cancel, and reschedule. Reuse the same key and exact body after a timeout or lost response. Identical retries return the original result and must not create another hold, transaction, or provider booking. Reusing a key with a different body returns IDEMPOTENCY_CONFLICT. A missing key returns IDEMPOTENCY_KEY_REQUIRED with a usable example.

## State and truth

Use transaction_state: AVAILABLE, HELD, REQUESTED, PENDING, COMMITTED, PROVIDER_CONFIRMED, FAILED, EXPIRED, or CANCELLED. Also read engine_state, provider_confirmation, and user_safe_status. REQUESTED and PENDING are not confirmed bookings. PROVIDER_CONFIRMED means the provider acknowledged the commitment. Confirmed is not fulfilled; outcome records what happened later.

When payment.status is not_managed_by_livend, payment happens outside Livend. It does not mean the offering is free. Livend does not process payments yet.

## Autonomous recovery errors

Errors include stable error, message, retryable, and next_action when an action is valid. Handle FULFILLMENT_NO_LONGER_AVAILABLE and HOLD_EXPIRED by running check_fulfillment again. Handle BUYER_DETAILS_REQUIRED by supplying required_fields when guest_checkout_supported is true. TRANSACTION_ACCESS_INVALID is not retryable with the same token. PROVIDER_COMMIT_FAILED is terminal for that attempt and reports provider_confirmation=false and transaction_state=FAILED.

A rate limit returns HTTP 429, Retry-After seconds, and {"error":"RATE_LIMITED","retry_after_seconds":N,"scope":"..."}. Guest identity creation is limited independently. A valid in-flight transaction credential can still commit, read, and fetch a receipt when an unrelated guest-creation limit is exhausted. Recovery windows never outlast the maximum hold TTL.

## Other public machine surfaces

Landing: https://livend.ai/
Directory: https://livend.ai/directory
Sitemap: https://livend.ai/sitemap.xml
Registry offering search: https://livend.ai/v1/registry/offerings?q=...
Entity documents: https://livend.ai/v1/entities/{lv_biz_|lv_loc_|lv_offer_}
Machine contracts: OpenAPI 3.26+ and MCP tools search_offerings, get_entity
Public resolution APIs and availability: https://livend.ai/v1/public/businesses and https://livend.ai/v1/entities/{livend_id}
Public business resolution: https://livend.ai/v1/public/businesses
OpenAPI document: https://livend.ai/v1/openapi.json
OAuth authorization server metadata: https://livend.ai/.well-known/oauth-authorization-server
MCP tools: search_offerings, get_entity, check_fulfillment, reserve_fulfillment, commit_fulfillment, request_fulfillment, get_transaction, get_receipt, cancel_transaction, reschedule_transaction

Owner truth: accepting_bookings=false means visible but paused. booking_mode request_only or walk_in_only narrows booking. A request is never a booking until the transaction becomes committed or provider confirmed.