SRIFT

Create a new SRIFT secure session. Returns the 7-character session ID and a shareable URL. The host approves all future joins. E2EE keys derive locally from the session ID + optional roomSecret.

{
  "type": "object",
  "properties": {
    "sessionName": {
      "type": "string",
      "description": "Human-readable session name (optional, e.g. \"Project Collab\")"
    },
    "roomSecret": {
      "type": "string",
      "description": "Optional shared secret mixed into key derivation. Never sent to server. Without it the key is derivable from the session ID (which the server sees); set it to make the key participant-only."
    }
  }
}

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "7-character unique session room code"
    },
    "url": {
      "type": "string",
      "description": "Direct browser join URL to share with peers"
    },
    "role": {
      "type": "string",
      "description": "User role in session (host)"
    }
  },
  "required": [
    "sessionId"
  ]
}

Request to join an existing SRIFT session by its 7-character session ID. The host must approve before transfers/chat work.

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "7-character session ID (e.g. ABC1234)"
    },
    "username": {
      "type": "string",
      "description": "Display name (optional, defaults to AI-Agent)"
    },
    "roomSecret": {
      "type": "string",
      "description": "Optional shared secret matching the host's"
    }
  },
  "required": [
    "sessionId"
  ]
}

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "Session room code"
    },
    "status": {
      "type": "string",
      "description": "Join request status (approved, pending, or joined)"
    },
    "message": {
      "type": "string",
      "description": "Status message or instructions"
    }
  },
  "required": [
    "sessionId"
  ]
}

Get current session details: session { id, role (host/guest), connection state, your userId }, pending join requests (approve with srift_approve_join), and members with their userIds (remove one with srift_kick_user).

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "session": {
      "type": "object",
      "description": "The active session (id is null when there is none)",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Active session ID"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Session name"
        },
        "role": {
          "type": [
            "string",
            "null"
          ],
          "description": "\"host\", \"guest\", or null"
        },
        "isConnected": {
          "type": "boolean",
          "description": "True if connected to the signaling server"
        },
        "userId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Your user id in the session"
        },
        "status": {
          "type": "string",
          "description": "Guest only: \"pending_approval\" or \"approved\" (hosted endpoint)"
        }
      }
    },
    "peerCount": {
      "type": "number",
      "description": "Number of connected sockets in the room (hosted endpoint)"
    },
    "participants": {
      "type": "array",
      "description": "Session members (local daemon): pass userId to srift_kick_user to remove one",
      "items": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "isHost": {
            "type": "boolean"
          },
          "online": {
            "type": "boolean"
          }
        }
      }
    },
    "pendingJoins": {
      "type": "array",
      "description": "List of pending guest join requests waiting for host approval",
      "items": {
        "type": "object",
        "properties": {
          "tempUserId": {
            "type": "string",
            "description": "Temporary ID of requesting user"
          },
          "username": {
            "type": "string",
            "description": "Username of requesting user"
          }
        }
      }
    }
  }
}

Close the active session. Flushes E2EE keys, disconnects signaling, clears chat history.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True if session was closed cleanly"
    },
    "message": {
      "type": "string",
      "description": "Confirmation message"
    }
  }
}

Host-only. Approve a pending guest join request by their temp user ID.

{
  "type": "object",
  "properties": {
    "tempUserId": {
      "type": "string",
      "description": "Temp user ID from session_status pendingJoins"
    }
  },
  "required": [
    "tempUserId"
  ]
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True if guest was approved"
    },
    "tempUserId": {
      "type": "string",
      "description": "Approved user temporary ID"
    }
  }
}

Host-only. Reject a pending guest join request.

{
  "type": "object",
  "properties": {
    "tempUserId": {
      "type": "string",
      "description": "Temp user ID from session_status pendingJoins"
    },
    "reason": {
      "type": "string",
      "description": "Optional rejection reason message sent to guest"
    }
  },
  "required": [
    "tempUserId"
  ]
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True if guest join request was rejected"
    },
    "tempUserId": {
      "type": "string",
      "description": "Rejected user temporary ID"
    }
  }
}

Host-only. Disconnect and remove a peer from the active room. Get the peer's userId from srift_session_status (participants).

{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "User ID of the participant to disconnect and remove"
    }
  },
  "required": [
    "userId"
  ]
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "True if peer was successfully kicked"
    },
    "userId": {
      "type": "string",
      "description": "ID of kicked peer"
    }
  }
}

List all active and recent transfers with progress, speed, ETA, and status.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "transfers": {
      "type": "array",
      "description": "List of live or recent file transfers",
      "items": {
        "type": "object",
        "properties": {
          "fileId": {
            "type": "string",
            "description": "Transfer unique file ID"
          },
          "name": {
            "type": "string",
            "description": "Filename"
          },
          "size": {
            "type": "number",
            "description": "Size in bytes"
          },
          "progress": {
            "type": "number",
            "description": "Transfer percentage 0-100"
          },
          "status": {
            "type": "string",
            "description": "Transfer status (uploading, downloading, completed, failed)"
          },
          "speedKBps": {
            "type": "number",
            "description": "Current transfer speed in KB/s"
          },
          "etaSeconds": {
            "type": "number",
            "description": "Estimated remaining seconds"
          }
        }
      }
    }
  }
}

Diagnose SRIFT on this machine: connectivity (DNS, proxy, HTTPS/TLS, WebSocket relay, UDP/P2P, peer discovery, clock), the local runtime (loopback, background processes, daemon + version, disk) and the environment (sandbox/CI/container detection, curl). Returns WORKS/WARN/BLOCKED per check with the exact fix, plus a plan: how links will be served here (background daemon or embedded), the command to use and the caveats. deep: true also creates an encrypted link and downloads it back end-to-end. Read-only apart from that temporary self-test link. Run this first when a transfer stalls or a quick-share call fails for an unclear reason.

{
  "type": "object",
  "properties": {
    "fresh": {
      "type": "boolean",
      "description": "Force a fresh probe instead of returning a cached result (slower, more accurate)."
    },
    "deep": {
      "type": "boolean",
      "description": "Also run an end-to-end self-test: create an encrypted single-use link and download it back through the relay (≈2 MB, a few seconds)."
    }
  }
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "True if the diagnostic ran successfully (independent of what it found)"
    },
    "base": {
      "type": "string",
      "description": "The SRIFT server that was probed"
    },
    "checkedAt": {
      "type": "string",
      "description": "When the probe ran (ISO 8601); cached results show an older time"
    },
    "verdict": {
      "type": "string",
      "description": "\"ok\", \"degraded\", or \"blocked\""
    },
    "rungs": {
      "type": "array",
      "description": "Each transport rung checked, in order, with status and a fix hint if blocked",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "\"WORKS\", \"WARN\" (works with a caveat), \"BLOCKED\", or \"SKIPPED\""
          },
          "group": {
            "type": "string",
            "description": "\"connectivity\", \"runtime\" or \"environment\""
          },
          "detail": {
            "type": "string"
          },
          "fix": {
            "type": "string"
          }
        }
      }
    },
    "env": {
      "type": "object",
      "description": "Relevant environment (proxy vars, sandbox indicators, Node version, etc.)"
    },
    "recommendedMode": {
      "type": "string",
      "description": "\"relay\" when links can be served from here, otherwise \"none\""
    },
    "summary": {
      "type": "string",
      "description": "One-line conclusion"
    },
    "plan": {
      "type": "object",
      "description": "serveFrom (background-daemon | embedded | unavailable), transport, shareCommand, downloadCommand, advice[] — what to do in this environment"
    },
    "context": {
      "type": "object",
      "description": "runtime (mcp, cli, npx, binary, pypi…), cliVersion, serverVersion, daemonVersion"
    },
    "selfTest": {
      "type": "object",
      "description": "deep only: { ok, ms, bytes, mbps, via, error? }"
    }
  }
}