Getting Started
How It Works
The three-step Surf protocol
How It Works#
Surf follows a three-step protocol:
1. Discovery
Agents fetch /.well-known/surf.json to discover all available commands, their parameters, descriptions, and auth requirements. The manifest includes a SHA-256 checksum for drift detection via ETag/304.
2. Execution
Agents POST to /surf/execute with a command name and typed parameters. Surf validates params, runs middleware, and executes the handler.
3. Response
Results are returned as structured JSON. For long-running tasks, use SSE streaming. For multi-step workflows, use pipelines. For real-time events, connect via WebSocket.