Developer Documentation

Integrate ads into your AI app in minutes.

Everything you need: SDK setup, API reference, response schemas, and configuration options.

Authentication

Get your API key

Create an app in your developer dashboard, then generate an API key. Pass it as a Bearer token in every request.

// Every request requires an API key in the Authorization header Authorization: Bearer your_api_key_here Content-Type: application/json

Sign up & create an app

Go to sign up, then create an app in your developer dashboard.

Generate an API key

In your app settings, click "Generate API Key." Copy the key — you won't see it again.

Use the key in requests

Pass the key as a Bearer token in the Authorization header.

SDK Quick Start

Coming Soon

Install, init, serve ads

Official SDKs are in development. In the meantime, use the REST API directly.

JavaScript / Node.js

$ npm install @surfacedd/sdk import { Surfacedd } from '@surfacedd/sdk' const client = new Surfacedd('your_api_key') // Get a contextual ad for the user query const ad = await client.getAd({ query: 'best laptops for coding', format: 'text' })

Python

$ pip install surfacedd from surfacedd import Surfacedd client = Surfacedd("your_api_key") # Get a contextual ad for the user query ad = client.get_ad( query="best laptops for coding", format="text" )

REST API Reference

POST /api/v1/ads

Send user query context and get back a contextual sponsored ad. This is the core endpoint.

Request

POST /api/v1/ads Authorization: Bearer your_api_key Content-Type: application/json { "query": "best running shoes", "format": "text" }

Parameters

Field	Type	Required	Description
`query`	string	Yes	The user's query or context
`format`	string	No	Ad format: `text`, `image`, `video`, `voice`, or `code`. Defaults to `text`.

Response

{ "status": "ok", "ad": { "id": "ad_abc123", "type": "text", "sponsored": true, "label": "Sponsored", "content": { "title": "Product Name", "description": "...", "url": "https://...", "brand": "Brand Name", "price": "$99", "placement": "sponsored_result" }, "tracking": { "impression_id": "...", "click_url": "/api/v1/ads/click?id=...&sig=..." } }, "meta": { "query_category": "electronics", "format_served": "text", "relevance_score": 0.85 } }

Error Codes

Status	Meaning
`200`	Success. Ad returned (or `ad: null` if no match).
`400`	Invalid request body. Check `query` is a string.
`401`	Missing or invalid API key.
`429`	Rate limit exceeded. Retry after cooldown.

Rate Limits

100 requests / minute

Per app. Check X-RateLimit-Remaining header in responses. If you hit the limit, wait and retry.

Ad Formats

Five formats, one endpoint

Pass the format parameter to control what type of ad is returned. Each format includes different placement and content fields.

text

Sponsored results for chatbots and search assistants. Returns placement: "sponsored_result" with title, description, URL, brand, and price.

image

Display banners for image generation tools. Returns placement: "sidebar_banner" with dimensions (300x250) and image_url.

video

Pre-roll ads for video AI tools. Returns placement: "pre_roll" with duration_seconds, skip_after, and CTA text.

voice

Audio spots for voice assistants. Returns placement: "audio_spot" with a spoken script and duration.

code

Sidebar suggestions for code/productivity AI. Returns placement: "sidebar_suggestion" with context_match.

Click Tracking

Track ad clicks

When a user clicks an ad, redirect them through the click_url in the response. Each URL is signed with an HMAC signature for fraud prevention.

// The ad response includes a signed tracking URL ad.tracking.click_url // "/api/v1/ads/click?id=...&sig=..." // When the user clicks, send them through this URL // It validates the signature, registers the click, // and redirects to the product page GET /api/v1/ads/click?id=impression_id&sig=hmac_signature // → 302 redirect to product URL

Parameter	Description
`id`	Impression ID from the ad response
`sig`	HMAC signature (auto-generated in `click_url`). Prevents click fraud.

Configuration

Control the ad experience

You decide what ads appear and how often. Format selection is available today, with more controls on the way.

Format Selection

Choose which ad formats to allow in your app. Text only? Text and image? All five? Set this per-app when you register your app.

Coming Soon

Category Blocking

Block ad categories that don't fit your app. No gambling in a kids' app. No competitors in your tool.

Coming Soon

Frequency Caps

Control how often ads appear. Every response, every 5th, or once per session.

MCP Integration

Coming Soon

MCP Server for AI agents

We're building an MCP server that will let you connect Surfacedd directly to Claude, ChatGPT, and other MCP-compatible AI agents.

// Add to your MCP server configuration { "mcpServers": { "surfacedd": { "command": "npx", "args": ["@surfacedd/mcp-server"], "env": { "SURFACEDD_API_KEY": "your_api_key" } } } }

Want early access to the MCP server? Join the developer waitlist and we'll notify you when it ships.

Ready to integrate?

Test the API live in our playground, or sign up and start earning.

Try the API Playground →Create Account →