Surf API SDKs

Official client libraries for the Surf social platform API.
API Reference · Getting Started · Community

---

SDKs

Language	Path	Version	Requirements
Python	python/	1.0.0	Python 3.8+
TypeScript	typescript/	1.0.0	Node.js 18+
Go	go/	1.0.0	Go 1.21+
Java	java/	1.0.0	Java 17+

Quick Start

1. Get an API Token

Apply for developer access, create an application, and generate an API token.

2. Install an SDK

# Python
cd python && pip install -e .

# TypeScript
cd typescript && npm install && npm run build

# Go
go get github.com/Flipboard/surf-sdks/go

# Java
cd java && ./gradlew jar

3. Make Your First Request

from surf_api import SurfClient

client = SurfClient("surf_sk_live_your_token_here")
feed = client.feeds.get("surf/topic/technology")
print(feed["title"])

import { SurfClient } from './src';
const client = new SurfClient({ apiKey: 'surf_sk_live_...' });
const feed = await client.feeds.get('surf/topic/technology');

client := surf.NewClient("surf_sk_live_...")
feed, _ := client.Feeds.Get("surf/topic/technology")

SurfClient client = new SurfClient("surf_sk_live_...");
Feed feed = client.feeds.get("surf/topic/technology");

What You Can Do

Category	Description
Feeds	Browse topic feeds, trending posts, timelines across Mastodon, Bluesky, and RSS
Search	Full-text search for feeds, posts, accounts, and podcasts
Custom Feeds	Create personalized feeds from topics, hashtags, accounts, and RSS sources — with optional visual theming (header image, semantic colors, light/dark mode, responsive overrides)
AI	Ask questions about feeds, generate summaries, build feeds from natural language
Content	Resolve URLs, extract articles, detect language, analyze images
Audio	Text-to-speech, radio stations, podcasts, daily briefings
Write	Post, favourite, boost, bookmark -- target Bluesky or Mastodon with ?service=
MCP	Model Context Protocol integration for Claude and AI agents

83 endpoints across 13 categories. Full details in the API Reference.

Authentication

Method	Token Format	Use Case
API Token	surf_sk_live_*	Server-to-server, bots, data access
OAuth 2.0	surf_at_*	Acting on behalf of a user (PKCE required)

All SDKs include OAuth helpers for PKCE flow.

RTB (Real-Time Bidding)

All SDKs include an RTB client for programmatic ad buying via OpenRTB 2.5. Uses the same surf_sk_live_... API key — include the rtb:bid and rtb:reports scopes when creating your key. Impression/click/win/billing tracking is fired from the URLs in the bid response (there's no separate event call).

from surf_api import SurfRTBClient

rtb = SurfRTBClient(api_key="surf_sk_live_...")

# Test with sandbox mode (no real spend)
response = rtb.bid({
    "id": "req-1",
    "imp": [{"id": "1", "banner": {"w": 300, "h": 250}}],
}, sandbox=True)

# Report events
rtb.event(bid_id="bid-1", event="impression")

MCP Integration

The Surf API is available as an MCP server for Claude Code and other AI agents:

MCP Server URL: https://mcp.surf.social/mcp

Testing

Each SDK has integration tests that run against the live API. All require a SURF_API_TEST_TOKEN environment variable.

# Run all 4 SDKs at once (~3 min, handles rate limits automatically)
SURF_API_TEST_TOKEN=surf_sk_live_... ./test-harness/run_all.sh

Individual SDKs

Python (24 tests) -- requires requests and pytest:

cd python
SURF_API_TEST_TOKEN=surf_sk_live_... python3 -m pytest tests/ -v

TypeScript (24 tests) -- requires Node.js 18+ and tsx:

cd typescript
npm install
SURF_API_TEST_TOKEN=surf_sk_live_... npm run test:integration

Go (20 tests) -- requires Go 1.21+:

cd go
SURF_API_TEST_TOKEN=surf_sk_live_... go test -tags integration -v

Java (21 tests) -- requires JDK 17+ (Gradle wrapper included):

cd java
SURF_API_TEST_TOKEN=surf_sk_live_... ./gradlew integrationTest

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

• Bug reports: Open an issue
• Feature requests: Open an issue with the enhancement label
• Pull requests: Fork, create a branch, submit a PR

License

MIT

Links

• Surf
• Developer Portal
• API Reference
• Status Page
• Discord
• Support