Developers

API Documentation

Build integrations, automate link management, and connect returnbob to your stack — or to any AI assistant or agent via our standard MCP server. REST API, JSON, Bearer auth.

v1 Stable https://returnbob.com/api/v1 + MCP Server

REST API MCP Server

Authentication

API access requires the Developer plan or higher. Generate your keys in Settings → API.

Authorization: Bearer rtb_live_your_api_key

Every account has two independent keys:

rtb_live_… Full Access

Sees and manages every link — public, unlisted, private and password-protected. Keep it for your own scripts/tools only.

rtb_pub_… Public Links Only

Only sees/manages public and unlisted links — private and password-protected links stay completely invisible (404, not 403). Safe to hand to an AI agent.

link

Endpoints

GET /api/v1/me Get the authenticated account (username, plan, key scope)

GET /api/v1/links List your links — paginated, sortable, searchable (q, per, page, sort, dir)

POST /api/v1/links Create a link (auto_meta:true fetches title/description automatically)

GET /api/v1/links/{id} Get a single link

PUT /api/v1/links/{id} Update a link — only send the fields you want to change

DELETE /api/v1/links/{id} Delete a link permanently

GET /api/v1/analytics Clicks, device breakdown, traffic sources, top links (days, source params)

?q= on GET /links searches slug, title, destination URL, description, note, and hashtags — e.g. /api/v1/links?q=marketing.

Quick Example

curl -X POST "https://returnbob.com/api/v1/links" \
  -H "Authorization: Bearer rtb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"destination_url":"https://example.com","auto_meta":true}'

Error Codes

401 Missing/invalid key

403 Plan or scope restricted

404 Not found

422 Validation failed

500 Server error

All errors return {"error": "message"}.

For AI Agents & Assistants

Connect returnbob to Any MCP Client

returnbob runs a standard Model Context Protocol (MCP) server — an open protocol, not tied to any one AI product. Any MCP-compatible client can use it: AI chat assistants, coding agents, IDE integrations, browser extensions, or your own custom app or website. Point your client at the URL below and it can create, manage, and analyze your links directly from a conversation — no dashboard needed.

The endpoint

Every MCP client connects the same way: a URL plus a Bearer token in the request header. Use your Public Links Only key so the agent can never see private or password-protected links:

URL: https://returnbob.com/mcp Header: Authorization: Bearer rtb_pub_your_key

Prefer full access for your own automation? Use an rtb_live_… key instead — same URL, different key.

How you register that URL+header depends on your client. One concrete example — Claude Code / Claude Desktop:

claude mcp add --transport http returnbob https://returnbob.com/mcp \ --header "Authorization: Bearer rtb_pub_your_key"

Any other MCP client — another AI assistant, an agent framework, a custom website — connects with the exact same URL and header, just using that client's own way of adding a remote MCP server. Check your client's documentation for the equivalent step.

info

Some hosted web-only assistants only support OAuth for custom connectors rather than a static Bearer header — check whether your client supports custom headers for remote MCP servers if you hit an authentication wall.

build

Available Tools

get_me Get the authenticated account and key scope

list_links List or search links (by URL, title, topic) — paginated and sortable

create_link Create a link (with optional auto title/description fetch)

update_link Update any field on an existing link

delete_link Delete a link permanently

get_analytics Clicks, device breakdown, traffic sources, top links

A rtb_pub_… key restricts every tool above to public/unlisted links — private and password-protected links stay invisible, including to list_links and get_analytics.

Try asking your agent something like:

"Create a returnbob link to our latest release notes and show me last week's click stats."

settings

Need API or MCP access?

Upgrade to Developer or Pro in Settings → Billing, then grab your keys in Settings → API.