handover.tools

Store a piece of context and get back a short code. The person gives the link handover.tools/<code> to an agent on another device and it can fetch the content — no copy-paste of long text. The code is 8 letters, easy to type on a phone. NOT ENCRYPTED: the server can read what you store, so never put credentials, tokens, or private data in it. Content becomes unreadable after the TTL expires, and by default it can only be fetched once. The response also returns a revoke_key — keep it for the rest of this session so you can destroy the content immediately with handoff_revoke if the person changes their mind. Writes are limited to a small number per day; reads are not.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "The text to hand off. Maximum 256 KB of UTF-8."
    },
    "label": {
      "type": "string",
      "description": "Optional short hint shown to whoever fetches it, so they can confirm they got the right thing. Max 120 characters."
    },
    "ttl_minutes": {
      "type": "integer",
      "description": "Minutes until the content can no longer be fetched. Default 60, maximum 1440 (24h)."
    },
    "burn_after_read": {
      "type": "boolean",
      "description": "If true (the default) the content can be fetched exactly once and is deleted on that fetch."
    }
  },
  "required": [
    "content"
  ]
}

Fetch content stored by handoff_put using its 8-character code. The code is case-insensitive and hyphens are ignored, so 'kvmtrhxp' and 'KVMT-RHXP' are the same; the person may give it as a link like handover.tools/kvmtrhxp, and passing that is fine too. Return the content to the person verbatim and complete: it can be fetched only once. If the code is unknown, already fetched, or expired, content is null with a reason — these cases are deliberately indistinguishable.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "The 8-character code from handoff_put, e.g. 'kvmtrhxp'."
    }
  },
  "required": [
    "code"
  ]
}

Destroy content stored by handoff_put right now, before its TTL runs out and whether or not it has been fetched. Requires the revoke_key returned by handoff_put — the person fetching with the short code cannot revoke, only the writer can. Use this the moment someone says they sent the wrong thing, or changed their mind. Revoking an already gone item is not an error: the outcome is reported as 'already_gone'.

{
  "type": "object",
  "properties": {
    "revoke_key": {
      "type": "string",
      "description": "The revoke_key returned by handoff_put. Not the short code — the short code cannot destroy anything."
    }
  },
  "required": [
    "revoke_key"
  ]
}

Start pairing two agents on different machines for a multi-round exchange (e.g. one explores, the other studies and asks follow-up questions). Use the local client at https://handover.tools/client/channel.py — do not call this by hand. The client generates a secret password locally, and this call returns only a 3-character nameplate; the person gives nameplate + password (8 letters) to the other machine. The server never sees the password, so it cannot impersonate either side (SPAKE2). The person stays in the loop: send only after they approve, fetch only when they ask. Counts as one write against the daily write quota.

{
  "type": "object",
  "properties": {
    "pake_msg": {
      "type": "string",
      "description": "Base64 SPAKE2 message from the local client (side A)."
    }
  },
  "required": [
    "pake_msg"
  ]
}

Second half of pairing, run by the local client at https://handover.tools/client/channel.py. Send only the first 3 characters of the spoken code (the nameplate) plus this side's SPAKE2 message; the other 5 characters are the password and must never be sent to the server. The nameplate is consumed on success. Returns this side's key and the peer's SPAKE2 message. Unknown, used, or expired nameplates are deliberately indistinguishable.

{
  "type": "object",
  "properties": {
    "nameplate": {
      "type": "string",
      "description": "First 3 characters of the spoken code, e.g. 'K7M'."
    },
    "pake_msg": {
      "type": "string",
      "description": "Base64 SPAKE2 message (side B)."
    }
  },
  "required": [
    "nameplate",
    "pake_msg"
  ]
}

Relay one ciphertext to the other side of a paired channel. The ciphertext must come from the local client at https://handover.tools/client/channel.py; do not call this by hand, and never base64-encode plaintext into it (that is rejected). Only send after the person has seen and approved the draft — the server cannot enforce this, the calling agent must. Returns the message's sequence number and how far the peer has read.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "This side's channel key."
    },
    "ciphertext": {
      "type": "string",
      "description": "Base64 ciphertext from the client."
    }
  },
  "required": [
    "key",
    "ciphertext"
  ]
}

Use the local client at https://handover.tools/client/channel.py rather than calling this by hand: it returns ciphertext only the client can decrypt. Returns the peer's messages this side has not fetched yet, and marks them read so the peer can see they arrived. Call only when the person asks. peek=true reads without marking; after=N re-reads from sequence N (recovery). Side A also receives the peer's SPAKE2 message here to finish pairing. Large backlogs are paged: more=true means fetch again.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "This side's channel key."
    },
    "after": {
      "type": "integer",
      "description": "Return messages with seq greater than this. Defaults to what this side has already fetched."
    },
    "peek": {
      "type": "boolean",
      "description": "If true, do not mark messages as read."
    }
  },
  "required": [
    "key"
  ]
}

Either side can close. Deletes the channel, both keys, and every stored message immediately. The other side's next fetch reports not_found_or_closed.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "This side's channel key."
    }
  },
  "required": [
    "key"
  ]
}