How to use ToolRelay

Get from API key to a working agent call in three minutes.

ToolRelay gives agents one API for paid capabilities: models, search, web reads, image and video generation, and text to speech. This page shows the exact setup path instead of sending you into raw API docs first.

Open dashboard

The shortest path

1Get your keySign in, open Dashboard, then copy the default setup block or create a named key under API Keys.
2Teach your agentPaste the skill line and API key into Codex, Claude Code, Cursor, or any agent that can follow a remote skill document.
3Run one real callUse curl to call web.read. Once that works, your agent can reuse the same key and base URL.

What ToolRelay is

ToolRelay is a unified API for agents. Your agent asks for a capability, ToolRelay routes to the right upstream provider, records usage, and charges credits only for successful calls.

One key

TOOLRELAY_API_KEY

One API

https://toolrelay.dev

One skill

toolrelay.dev/skill.md

1. Use the ToolRelay Skill

The skill document tells the agent when to use ToolRelay, which endpoints exist, how to handle costs, and what errors to expect. The line below is an instruction for your agent, not a shell command.

Terminal

set up toolrelay.dev/skill.md
TOOLRELAY_API_KEY=tr_live_...

skill.md

Keep your live key private. Do not paste it into public repos, issues, or screenshots.

Open skill.md Open API docs

2. Set the API key

Agents and terminal sessions need the same key. Use export in bash or zsh. Fish uses set, because KEY=value is not valid fish syntax.

bash / zsh

Terminal

export TOOLRELAY_BASE_URL="https://toolrelay.dev"
export TOOLRELAY_API_KEY="tr_live_..."

fish

Terminal

set -x TOOLRELAY_BASE_URL "https://toolrelay.dev"
set -x TOOLRELAY_API_KEY "tr_live_..."

3. Run a real curl call

Start with web.read because it is easy to verify: the response should contain clean page content, usage metadata, and a charged execution when the provider succeeds.

Terminal

curl -X POST https://toolrelay.dev/v1/relay \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "capability": "web.read",
    "input": { "url": "https://example.com" },
    "maxCostUsd": 0.05
  }'

Terminal

curl -X POST https://toolrelay.dev/v1/chat/completions \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "openrouter/openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Say hello in one sentence." }]
  }'

4. Put it into your agent workflow

After the first call works, copy one of these patterns into the agent or IDE you already use.

Codex

Use ToolRelay when you need live web search, page reads, image/video generation, or TTS. Start by reading toolrelay.dev/skill.md.

npx toolrelay install codex

Claude Code

Install the ToolRelay skill, then use TOOLRELAY_API_KEY for web.read, web.search, chat/model, image/video, and tts tasks.

npx toolrelay install claude

Cursor or MCP client

Add ToolRelay as an MCP or shell-backed capability provider. Keep the key in your local environment, not in project files.

npx toolrelay install cursor

Claude Code
Codex
Cursor
Windsurf
Cline
Gemini CLI
Any MCP client

What is available now

The first useful mental model is capability first: ask for the job, not the vendor. These are the core capability families to start with.

CapabilityEndpointProvider

chat/model/v1/chat/completionsOpenRouter

web.search/v1/relayTavily

web.read / scrape/v1/relayFirecrawl

image.generate/v1/relayReplicate

video.generate/v1/relayReplicate

tts.generate/v1/relayElevenLabs

Done

What success looks like

You are ready when you can copy a setup block, set TOOLRELAY_API_KEY, run curl successfully, and explain that skill.md is the instruction layer for agents.

Open dashboard