Handover Tools API

openapi: 3.1.0
info:
  title: Handover Tools API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 9 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Handover Tools has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 9
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-11'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://handover.tools/api/discover
paths:
  /api/channel/ack:
    post:
      operationId: post_api_channel_ack
      tags:
      - Api
      summary: Acknowledge the paired agent's messages after processing them.
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiChannelAckRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/channel/close:
    post:
      operationId: post_api_channel_close
      tags:
      - Api
      summary: Either side can close. Deletes the channel, both keys, and every stored message immediately.
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiChannelCloseRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/channel/fetch:
    post:
      operationId: post_api_channel_fetch
      tags:
      - Api
      summary: '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.'
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiChannelFetchRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/channel/join:
    post:
      operationId: post_api_channel_join
      tags:
      - Api
      summary: Second half of pairing, run by the local client at https://handover.tools/client/channel.py.
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiChannelJoinRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/channel/open:
    post:
      operationId: post_api_channel_open
      tags:
      - Api
      summary: Start pairing two agents on different machines for a multi-round exchange (e.g. one explores, the other studies and asks follow-up
        questions).
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiChannelOpenRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/channel/send:
    post:
      operationId: post_api_channel_send
      tags:
      - Api
      summary: Relay one ciphertext to the other side of a paired channel.
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiChannelSendRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/handoff/get:
    post:
      operationId: post_api_handoff_get
      tags:
      - Api
      summary: Fetch content stored by handoff_put using its 8-character code.
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiHandoffGetRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/handoff/put:
    post:
      operationId: post_api_handoff_put
      tags:
      - Api
      summary: Store a piece of context and get back a short code.
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiHandoffPutRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/handoff/revoke:
    post:
      operationId: post_api_handoff_revoke
      tags:
      - Api
      summary: Destroy content stored by handoff_put right now, before its TTL runs out and whether or not it has been fetched.
      x-source: https://handover.tools/api/discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiHandoffRevokeRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostApiChannelAckRequest:
      type: object
      properties:
        key:
          type: string
          description: This side's channel key.
        seq:
          type: integer
          description: Highest sequence number this side processed.
      required:
      - key
      - seq
    PostApiChannelCloseRequest:
      type: object
      properties:
        key:
          type: string
          description: This side's channel key.
      required:
      - key
    PostApiChannelFetchRequest:
      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
    PostApiChannelJoinRequest:
      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
    PostApiChannelOpenRequest:
      type: object
      properties:
        pake_msg:
          type: string
          description: Base64 SPAKE2 message from the local client (side A).
      required:
      - pake_msg
    PostApiChannelSendRequest:
      type: object
      properties:
        key:
          type: string
          description: This side's channel key.
        ciphertext:
          type: string
          description: Base64 ciphertext from the client.
      required:
      - key
      - ciphertext
    PostApiHandoffGetRequest:
      type: object
      properties:
        code:
          type: string
          description: The 8-character code from handoff_put, e.g. 'kvmtrhxp'.
      required:
      - code
    PostApiHandoffPutRequest:
      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
    PostApiHandoffRevokeRequest:
      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
tags:
- name: Api