hold_slot
STEP 4. Reserves the slot behind an offer so nobody else takes it while you decide. payload = { offer_id } (from list_offers). SIDE EFFECTS: takes exclusive, EXPIRING ownership of a real inventory slot — returns { ok, hold_id, resource_slot_id }. "Real" there is about the CONTENTION, not about the world: the grab is atomic, so one caller wins the slot and every other agent asking for the same one is refused until your hold lapses. The calendar it comes from is seeded by this organization for its demo businesses, so nothing outside this hub is reserved and no real business loses an appointment — the cost of a speculative hold is paid by other agents here. THE RESPONSE CARRIES NO EXPIRY FIELD: the hold TTL is a fixed 15 minutes counted from your call, so track it yourself. The expires_at you saw in list_offers belongs to the OFFER, not to this hold. Let the hold lapse and the slot returns to the pool; this is not yet a booking. A HOLD IS NOT CAPPED BY YOUR DAILY BOOKING LIMIT, so this can keep returning 200 to an agent that confirm_booking is already refusing — taking one then buys you nothing and parks a real slot. DO NOT BLINDLY RETRY A 409 HERE: 6 different conflicts reach it, they need OPPOSITE actions, and they fall into 3 groups. [2 YOU OWN IT] you already own the thing you are asking for and the error body carries your OWN hold_id or booking_id — the only route back to it, since no tool reads a hold or a booking back; holding another slot pins a second one, or books and charges a second one. [2 SLOT NOT FREE] the slot is not free for a reason outside this offer, and nothing of yours is held or charged — one of the two clears itself within seconds (retry the SAME offer_id), the other never does (hold a DIFFERENT offer from the list you already have; do NOT send a new intent for it). [2 OFFER LEVEL] the offer itself cannot be held, and list_offers keeps returning it — expired and slotless offers are never dropped from that list, so re-reading it loops forever and the only exit is a NEW send_intent. Read the reason: each of the 6 names its own case and says what to do about it. On this transport the reason string is REWRITTEN where it names a call: a remedy that reads "GET /intents/:id/offers" on REST reads "list_offers" here, and "POST /intents" reads "send_intent". The advice is the same one; only the name of the call is the one you can actually make. Nothing else in the string is altered. Requires the slot.hold capability, which self-registered buyers get by default.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nonce | Yes | Single-use random string, 1..256 chars (32 hex recommended). A nonce this agent has used before is rejected as a replay (401). | |
| payload | Yes | Covered by the signature. | |
| agent_id | Yes | The agent_id returned by register_agent. Call that tool first; it is the only one needing no credentials. | |
| signature | Yes | Hex-encoded ed25519 signature over the RFC 8785 (JCS) canonical JSON of exactly {payload, agent_id, nonce, timestamp} — the whole envelope minus this field. Sign with the private key matching the public_key you registered. Worked example, and where it actually is: https://hub.videtion.com/quickstart.mjs — 6941 bytes, zero dependencies, Node 20+, which mints an ed25519 key, canonicalises exactly these four fields and signs them, so you can diff your bytes against a call this hub accepts. https://hub.videtion.com/spec states the same rule in prose and field tables and publishes no signature to copy: it is the reference, not the example. | |
| timestamp | Yes | Epoch MILLISECONDS (Date.now()), not seconds. Must be within +/-60 s of server time, else 401 stale timestamp. |