Docs · SearchPipe AI Search API & MCP Integration

Quickstart

Sign up — free credits are granted automatically (usage beyond that is billed per credit; see Pricing).
Open API Keys in the console and create a key, e.g. sp-xxxxxxxx; the creation dialog hands you a ready-to-use MCP link.
Drop the key into an MCP client (recommended), or call POST /search directly.

MCP setup (recommended)

SearchPipe is a remote MCP Server (streamable-http transport) with the API key embedded directly in the URL, so even clients without custom-header support work:

# MCP link format (key embedded in the URL, no headers needed):
https://searchpipe.tech/mcp/?api_key=sp-YOUR_API_KEY

# One-command add for Claude Code:
claude mcp add --transport http searchpipe "https://searchpipe.tech/mcp/?api_key=sp-YOUR_API_KEY"

# Tool name: searchpipe_search (same parameters as POST /search)

Clients that do support custom headers can pick either style: use https://searchpipe.tech/mcp/ as the URL and add an Authorization: Bearer sp-… header.

Per-client configuration details and connection troubleshooting: MCP setup guide.

Agent self-setup

Send the link below to your AI agent — it can read these instructions and complete the MCP setup and verification by itself:

https://searchpipe.tech/agent-setup/SKILL.md

Even easier: sign in to the console, open API Keys and click "Copy one-line setup" — the prompt already embeds your API key and MCP link, so pasting it to your agent is all it takes (for security, the prompt itself is never shown on the page).

REST API authentication

Use the REST API for direct programmatic calls or your own agent pipeline. Every call must be authenticated with an API key (create one); two ways to pass it:

Authorization: Bearer sp-YOUR_KEY
# or
X-API-Key: sp-YOUR_KEY

POST /search parameters

A single call runs retrieval aggregation → full-text extraction → LLM reranking → (optional) AI answer. Parameters are identical to the MCP tool searchpipe_search.

Parameter	Type	Default	Description
`query` required	string	—	Search question or keywords
`max_results`	int	5	Number of results (1–20)
`include_answer`	bool	false	Generate a cited AI answer
`include_raw_content`	bool	false	Return the full extracted page body
`search_depth`	string	basic	Search depth (basic / advanced); affects credit cost

Response shape

The response is structured JSON; every result carries a 0–1 relevance score and results are sorted by relevance, highest first:

{
  "query": "How to deploy FastAPI",
  "answer": "FastAPI is typically served with uvicorn,
    often behind gunicorn…[0][2][3]",
  "ai_generated": true,
  "results": [
    {
      "url": "https://…",
      "title": "…",
      "content": "Body snippet…",
      "score": 0.98,
      "raw_content": "Full page body (only when include_raw_content=true)"
    }
  ]
}

When the answer is enabled the response includes ai_generated: true to flag AI-generated content.

Usage examples

curl

curl -X POST https://searchpipe.tech/search \
  -H "Authorization: Bearer sp-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"FastAPI tutorial","max_results":5,"include_answer":true}'

Python

import httpx

resp = httpx.post(
    "https://searchpipe.tech/search",
    headers={"Authorization": "Bearer sp-YOUR_KEY"},
    json={"query": "FastAPI tutorial", "max_results": 5, "include_answer": True},
    timeout=60,
)
data = resp.json()
print(data["answer"])
for r in data["results"]:
    print(r["score"], r["title"], r["url"])

JavaScript

const resp = await fetch("https://searchpipe.tech/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sp-YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "FastAPI tutorial", max_results: 5, include_answer: true }),
});
const data = await resp.json();

Error codes

Status	Meaning	What to do
`400`	Input/output content violation	Adjust the query; output violations are auto-refunded
`401`	Missing or invalid credentials	Check that the API key is correct and not revoked
`402`	Insufficient credits	Recharge and retry
`429`	Rate limited	Lower concurrency; retry after the `Retry-After` header
`502`	Upstream retrieval failure	Auto-refunded; safe to retry

Rate limits & billing

Rate limiting: Redis sliding window, default 100 requests/min with a burst of 20; over-limit requests get 429 plus a Retry-After header; admin accounts are exempt.
Billing: basic search costs 1 credit per call, advanced search 2 credits; failures are never charged — any deducted credit is idempotently refunded.
Cache: identical query and parameters within the cache TTL (default 300s) hit the cache and skip the pipeline.
Credit sources: signup grant, recharge (never expires), monthly subscription (valid 30 days) — see Pricing.

MCP setup guide: Claude Code / Cursor configuration and troubleshooting
Pricing: credit system, recharge tiers and monthly plans
FAQ: billing, rate limits, result usage and more

API Docs