6 use cases · real code examples

What will you build?

Name: Surf
Author: Surf

From design tools to e-commerce, real-time editors to smart homes — see how Surf gives AI agents typed, structured access to any web application.

Scroll to explore·Real code examples

The difference

Why Surf, not just an API?

Your API is great for developers. Surf makes it great for AI agents too. One protocol, universal discovery, built for machines.

Without Surf

~28 lines

Read API docs

…and repeat for every API you integrate

With Surf

~5 lines

Discover manifest●

✓ Works with any Surf site~47ms

Auto-Discovery

Agents fetch /.well-known/surf.json and instantly know every command, parameter, type, and auth requirement. No docs to read, no API keys to hunt.

Universal Protocol

Every Surf-enabled site works the same way. Learn Surf once, interact with any site. No more custom REST conventions per service.

Agent-First Design

Commands include hints like idempotent, sideEffects, and estimatedMs — metadata that helps agents plan, retry, and reason about actions.

Zero Vision Models

No screenshots, no DOM parsing, no pixel-clicking. Just typed commands and structured responses. Faster, cheaper, 100% reliable.

Real-Time Sync

APIs are request/response. Surf has built-in WebSocket broadcasting via Surf Live — agents and UIs stay in sync, always.

Type Safety Built In

Every command has typed parameters with validation, scoped auth levels, and standardized error codes. No guessing, no custom parsing.

At a glance

Feature	Traditional API	Surf Protocol
Discovery	Read docs, find endpoints	Automatic via /.well-known/surf.json
Integration	Custom per API	Universal — one protocol for all
Auth	Custom flows	Standardized per-command auth levels
Type safety	Maybe OpenAPI	Built-in typed params + validation
Agent hints	None	Idempotent, sideEffects, estimatedMs
Real-time	Build your own	Surf Live — built-in WebSocket sync
Error handling	Custom per API	Standardized error codes

Use Case 01

AI Design Tool

Create graphics through typed commands

An AI agent creates designs by calling canvas commands — no mouse, no screenshots. Create shapes, apply gradients, add text, and export — all through structured Surf commands.

Commands

canvas.create— Create a new canvas with dimensions

canvas.addRect— Add a rectangle with fill and stroke

canvas.setGradient— Apply linear or radial gradients

canvas.addText— Add text with font, size, and color

canvas.addCircle— Add a circle with position and style

canvas.alignObjects— Auto-align shapes on the canvas

canvas.exportPNG— Export the canvas as PNG

Live demo View source

PixelForge — Untitled.surf

→ canvas.create({ w: 800, h: 600 })1/10

design-agent.ts

// Agent builds a gradient logo in one pipeline
const client = await SurfClient.discover(
  'https://pixelforge-pearl.vercel.app'
)
 
await client.pipeline([
  { command: 'canvas.create', params: { width: 800, height: 600 } },
  { command: 'canvas.addRect', params: { x: 100, y: 80, w: 300, h: 200, fill: '#0057FF' } },
  { command: 'canvas.setGradient', params: { type: 'linear', from: '#0057FF', to: '#00C9B1' } },
  { command: 'canvas.addText', params: { text: 'Made by AI', fontSize: 32 } },
  { command: 'canvas.addCircle', params: { cx: 520, cy: 200, r: 80 } },
  { command: 'canvas.alignObjects', params: { align: 'center' } },
])

Use Case 02

E-Commerce Store

Search, browse, and purchase programmatically

Agents search products, manage carts, and complete purchases through a typed command pipeline — replacing 10 page loads with a single 47ms API call.

Commands

products.list— List products with pagination

products.search— Search by name, category, or filters

products.get— Get detailed product info by ID

cart.add— Add a product to the cart

cart.get— View current cart contents + total

cart.checkout— Complete purchase (auth required)

View source

TechStore

Search products...

🎧

AirPods Max

$549

4.8

🎵

Sony WH-1000

$348

4.7

🔊

Bose QC Ultra

$429

4.6

🎶

Sennheiser HD

$299

4.5

→ products.list({ limit: 4 })

shopping-agent.ts

// Full shopping flow in one pipeline
const client = await SurfClient.discover(
  'https://store.example.com'
)
 
const result = await client.pipeline([
  { command: 'products.search', params: { q: 'wireless headphones', maxPrice: 600 }, as: 'results' },
  { command: 'cart.add', params: { id: '$results.products.0.id', qty: 1 } },
  { command: 'cart.checkout' },
])
// ✓ Order confirmed — 47ms total, 0 screenshots

Use Case 03NEW

Surf Live: Real-Time Video Editor

Agent edits while users watch — live

Powered by Surf Live, an AI agent edits a video timeline while connected browsers see every change in real-time. State syncs instantly via WebSocket — no polling, no refresh.

Commands

useSurfState()— React hook for synced state

useSurfEvent()— Subscribe to real-time events

SurfProvider— Context provider with auto-reconnect

timeline.update— Push timeline changes to all clients

Read the docs

Timeline

Connectedv1

Intro

Main

Agent

Browser 1

Browser 2

Live

surfLive.connect()

app.tsx

import { SurfProvider, useSurfEvent } from '@surfjs/react'
 
function App() {
  return (
    <SurfProvider url="wss://your-server.com/surf/live">
      <Timeline />
    </SurfProvider>
  )
}
 
function Timeline() {
  const [clips, setClips] = useState([])
 
  useSurfEvent('timeline.updated', (data) => {
    setClips(data.clips) // Updates instantly across all browsers
  })
 
  return <ClipList clips={clips} />
}

Use Case 04

CMS / Content Management

Agents manage pages, blocks, and media

An agent creates pages, adds content blocks, uploads media, and publishes — all through structured commands. No clicking through admin UIs.

Commands

page.create— Create a new page with metadata

content.addBlock— Add a content block (text, image, embed)

media.upload— Upload an image or file

page.setStatus— Move page through workflow stages

page.publish— Publish a draft page

Example coming soon

Page Builder

Draft

Preview

→ page.create({ title: "Landing" })

cms-agent.ts

// Agent creates a blog post with an image
const client = await SurfClient.discover('https://cms.example.com')
 
await client.pipeline([
  { command: 'page.create', params: { title: 'Hello World', type: 'blog' }, as: 'page' },
  { command: 'content.addBlock', params: { pageId: '$page.id', type: 'text', body: 'Welcome to our blog.' } },
  { command: 'media.upload', params: { url: 'https://example.com/hero.jpg' }, as: 'image' },
  { command: 'content.addBlock', params: { pageId: '$page.id', type: 'image', mediaId: '$image.id' } },
  { command: 'page.publish', params: { pageId: '$page.id' } },
])

Use Case 05

Developer Tools / CI/CD

Run builds, check tests, deploy previews

Agents trigger CI pipelines, check test results, and deploy preview environments — all through typed commands with structured responses.

Commands

ci.run— Trigger a CI build for a branch

test.status— Check test results and coverage

deploy.preview— Deploy to a preview environment

deploy.promote— Promote preview to production

logs.tail— Stream recent deployment logs

Example coming soon

Terminal — CI Pipelinezsh

$ surf ci.run --target staging

devops-agent.ts

// Agent runs full CI → deploy pipeline
const client = await SurfClient.discover('https://ci.example.com')
 
const result = await client.pipeline([
  { command: 'ci.run', params: { branch: 'feat/new-api' }, as: 'build' },
  { command: 'test.status', params: { buildId: '$build.id' }, as: 'tests' },
  { command: 'deploy.preview', params: { buildId: '$build.id' }, as: 'deploy' },
])
 
console.log(result.deploy.url) // → "preview-abc123.vercel.app"

Use Case 06

Smart Home / IoT

Control devices and read sensors

Agents control smart home devices — toggle lights, adjust thermostats, activate scenes. Structured commands replace brittle home automation scripts.

Commands

devices.list— List all connected devices and status

lights.set— Turn lights on/off, set brightness and color

thermostat.set— Set target temperature

scene.activate— Activate a predefined scene

blinds.set— Set blind/shade position

media.play— Play audio on connected speakers

Example coming soon

Smart Home

5 devices

Living Room

21°

Bedroom

Kitchen & Dining

Devices

Living Light

Bedroom Light

Thermostat

Blinds

Speaker

→ devices.list()

home-agent.ts

// Agent sets up a movie night scene
const client = await SurfClient.discover('https://home.local')
 
await client.pipeline([
  { command: 'lights.set', params: { room: 'living', brightness: 20, color: '#FF8C00' } },
  { command: 'thermostat.set', params: { target: 22 } },
  { command: 'scene.activate', params: { name: 'Movie Night' } },
  { command: 'blinds.set', params: { position: 20 } },
  { command: 'media.play', params: { source: 'ambient' } },
])
// Lights dimmed, temperature set, scene activated

Build your own

Add Surf to any website in minutes. Expose typed commands, and let any AI agent interact with your app.

$npx @surfjs/cli inspect your-site.com

Get started →

GitHub