Docs - Semantic API

⚡ Quick Start

Get up and running in 30 seconds. Use the MCP CLI or call the API directly.

Option A: MCP CLI

Terminal

pip install semanticapi-mcp

Then add it to Claude Desktop or any MCP client and start asking for APIs in natural language.

Option B: cURL

cURL

# Search 570+ APIs with natural language
curl -X POST https://semanticapi.dev/api/query \
  -H "X-API-Key: sapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{"q": "send email"}'

Option C: Free endpoints (no key needed)

cURL

# Browse the catalog — no auth required
curl https://semanticapi.dev/api/catalog?limit=5
curl https://semanticapi.dev/api/catalog/stats
curl https://semanticapi.dev/api/catalog/categories

🔐 Authentication

There are two ways to authenticate with Semantic API:

1. API Key (recommended)

Sign up at semanticapi.dev/demo, then find your API key in the dashboard. Pass it as a header:

HTTP Header

X-API-Key: sapi_your_key_here

2. x402 Micropayments (no signup)

Pay per request with USDC on Base. No account needed — just send an X-Payment header with a signed payment. See x402 Payments for details.

ℹ️ Catalog endpoints (/api/catalog, /api/catalog/stats, /api/catalog/categories) are free and require no authentication.

🔍 POST /api/query

Semantic search across 570+ API providers. Describe what you want in natural language and get matching API capabilities with ready-to-use endpoint details.

Parameter	Type	Description
`q`	string required	Natural language query
`limit`	integer optional	Max results (default 5)
`auto_discover`	boolean optional	Discover new providers if none match

cURL

curl -X POST https://semanticapi.dev/api/query \
  -H "X-API-Key: sapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{"q": "get current weather for a city"}'

Response

{
  "results": [
    {
      "provider": "openweathermap",
      "capability": "Current Weather",
      "description": "Get current weather conditions for a location",
      "score": 0.94,
      "endpoint": {
        "method": "GET",
        "path": "/data/2.5/weather",
        "base_url": "https://api.openweathermap.org"
      },
      "auth_type": "api_key",
      "user_has_key": false,
      "ready_to_use": false
    }
  ]
}

🔮 POST /api/discover/search

Deep semantic discovery — finds the best matching providers for a given intent and returns full capability details with auth instructions.

Parameter	Type	Description
`q`	string required	What you want to do
`limit`	integer optional	Max results (default 5)

cURL

curl -X POST https://semanticapi.dev/api/discover/search \
  -H "X-API-Key: sapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{"q": "send SMS messages"}'

📦 GET /api/catalog

Browse all providers in the catalog. Supports pagination and filtering. No auth required.

Parameter	Type	Description
`limit`	integer optional	Results per page (default 20)
`offset`	integer optional	Pagination offset
`auth_type`	string optional	Filter by auth type (none, api_key, bearer, oauth2)
`free_tier`	boolean optional	Filter to free-tier only
`search`	string optional	Text search on name/description

cURL

# Browse providers — no auth needed
curl "https://semanticapi.dev/api/catalog?limit=5&auth_type=none"

Response

{
  "providers": [
    {
      "provider_id": "openweathermap",
      "name": "OpenWeatherMap",
      "description": "Weather data API for current conditions, forecasts...",
      "auth_type": "api_key",
      "free_tier": true,
      "capabilities_count": 5,
      "categories": ["weather", "forecast", "current"]
    }
  ]
}

📋 GET /api/catalog/{provider_id}

Get full details for a specific provider including all capabilities, auth instructions, and endpoint specs. No auth required.

cURL

curl https://semanticapi.dev/api/catalog/openweathermap

Response

{
  "provider_id": "openweathermap",
  "name": "OpenWeatherMap",
  "base_url": "https://api.openweathermap.org",
  "auth": {
    "type": "api_key",
    "signup_url": "https://home.openweathermap.org/users/sign_up",
    "free_tier": true,
    "signup_steps": [
      "Visit signup_url",
      "Create account with email",
      "Go to API Keys section",
      "Copy default key (active in ~2 hours)"
    ],
    "time_to_key": "< 2 hours"
  },
  "capabilities": [
    {
      "id": "current",
      "name": "Current Weather",
      "endpoint": { "method": "GET", "path": "/data/2.5/weather" }
    }
  ]
}

📊 GET /api/catalog/stats

Public statistics about the catalog. No auth required.

cURL

curl https://semanticapi.dev/api/catalog/stats

Response

{
  "total_providers": 1142,
  "total_capabilities": 2473,
  "auth_type_breakdown": {
    "none": 200,
    "api_key": 223,
    "bearer": 84,
    "oauth2": 51
  },
  "free_tier_count": 565
}

🏷️ GET /api/catalog/categories

List all capability categories across providers. No auth required.

cURL

curl https://semanticapi.dev/api/catalog/categories

Response

{
  "categories": [
    { "name": "weather", "count": 12 },
    { "name": "email", "count": 8 },
    { "name": "search", "count": 130 }
  ]
}

🔑 Key Vault

Store your third-party API keys securely. When you query Semantic API, it automatically uses your stored keys to make API calls on your behalf.

Store a key

cURL

curl -X POST https://semanticapi.dev/vault/keys \
  -H "X-API-Key: sapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "openweathermap",
    "api_key": "your_openweathermap_key_here"
  }'

List stored keys

cURL

curl https://semanticapi.dev/vault/keys \
  -H "X-API-Key: sapi_your_key"

Get a specific key

cURL

curl https://semanticapi.dev/vault/keys/openweathermap \
  -H "X-API-Key: sapi_your_key"

Delete a key

cURL

curl -X DELETE https://semanticapi.dev/vault/keys/openweathermap \
  -H "X-API-Key: sapi_your_key"

How user_has_key and ready_to_use work

When you search for APIs via /api/query, each result includes:

user_has_key — true if you have a key stored in the vault for this provider
ready_to_use — true if the provider requires no auth OR you already have a key stored

💡 Store keys for your favorite providers, then every query result will show ready_to_use: true — meaning the API can be called immediately without any setup.

💸 x402 Payments

Pay per request with USDC on Base. No signup, no API key — just attach a signed payment to your request.

How it works

Call any paid endpoint without auth
You get back HTTP 402 Payment Required with pricing details in the response headers
Sign a USDC payment on Base for the specified amount
Retry the request with the X-Payment header containing your signed payment
Payment is settled only if the request succeeds (deferred settlement)

Pricing

Endpoint	Price (USDC)
`POST /api/query`	$0.01
`POST /api/query/agentic`	$0.01
`POST /api/query/preflight`	$0.01
`POST /api/query/batch`	$0.05
`POST /api/discover/search`	$0.05
`POST /api/discover/from-url`	$0.10

ℹ️ Catalog endpoints, stats, and categories are always free — no auth or payment needed.

🤖 MCP CLI

Use Semantic API as an MCP server in Claude Desktop, Cursor, or any MCP-compatible client.

Installation

Terminal

pip install semanticapi-mcp

Claude Desktop config

claude_desktop_config.json

{
  "mcpServers": {
    "semanticapi": {
      "command": "semanticapi-mcp",
      "env": {
        "SEMANTIC_API_KEY": "sapi_your_key"
      }
    }
  }
}

Available Tools (7)

semantic_query

Search for APIs using natural language

semantic_discover

Deep discovery of a provider by name

semantic_discover_url

Analyze any API from its docs URL

semantic_catalog

Browse & filter the full provider catalog

semantic_provider_detail

Get full details for a specific provider

semantic_catalog_stats

Public catalog statistics

semantic_categories

List all provider categories

💡 The 3 catalog tools (stats, detail, categories) work without an API key — great for free exploration.

⌨️ CLI Tool

Query APIs, discover providers, and test integrations from your terminal. Zero dependencies.

Installation

Terminal

pip install semanticapi-cli

Quick Start

Terminal

# Save your API key
semanticapi config set-key sapi_your_key

# Query any API
semanticapi query "send an SMS via Twilio"

# Pre-check what you'll need (free)
semanticapi preflight "send an email"

# Discover a provider
semanticapi discover stripe

# Batch queries
semanticapi batch "send email" "upload file" "translate text"

Commands

query

Natural language API query

batch

Multiple queries in one call

preflight

Pre-check (free, identifies needed auth)

discover

Look up a provider by name

discover-url

Discover provider from docs URL

status

Show config and API health

config

Manage API key and settings

📦 PyPI · GitHub

🦜 LangChain Integration

Native LangChain tools for API discovery. Drop into any LangChain agent.

Installation

Terminal

pip install semanticapi-langchain

Quick Start

Python

from semanticapi_langchain import SemanticAPIToolkit

toolkit = SemanticAPIToolkit(api_key="sapi_your_key")
tools = toolkit.get_tools()

# Use directly
result = tools[0].run("send an SMS")

With a LangChain Agent

Python

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from semanticapi_langchain import SemanticAPIToolkit

toolkit = SemanticAPIToolkit()
tools = toolkit.get_tools()
llm = ChatOpenAI(model="gpt-4o-mini")

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
response = executor.invoke({"input": "How do I send an email?"})

Tools

semanticapi_query

Find the best API for a task in plain English

semanticapi_search

Search and discover available API capabilities

📦 PyPI · GitHub

⚡ Agent Skill (Autonomous Agents)

For autonomous agents that can't install packages — a SKILL.md file that teaches any agent how to use Semantic API natively. No dependencies, just read and go.

Installation

Terminal

# Clone the skill
git clone https://github.com/peter-j-thompson/semantic-api-skill.git

# Or add to your agent's skills directory
cp -r semantic-api-skill/SKILL.md your-agent/skills/semantic-api/

What It Does

The skill teaches agents to use Semantic API endpoints natively — discovery, execution, batch queries, preflight checks, and x402 micropayments. No wrapper code needed.

Supported Endpoints

POST /api/query

Discovery — natural language → matched API

POST /api/query/agentic

Execution — natural language → actual API response

POST /api/query/batch

Batch up to 10 queries

POST /api/query/preflight

Free pre-check

POST /api/discover/search

Deep provider discovery

POST /api/discover/from-url

Analyze API from URL

⚡ GitHub · Submitted as PR to Conway-Research/automaton

🔮 Auto-Discover

Don't see a provider in our catalog? Semantic API can discover new providers on demand — from any URL or just a description of what you need.

From a URL

Point us at any API's docs or base URL, and we'll scrape, analyze, and generate a full provider config in real-time.

curl

curl -X POST https://semanticapi.dev/api/discover/from-url \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.quotable.io", "user_intent": "get random quotes"}'

Inline with Queries

Set auto_discover: true on any query, and if no built-in provider matches, we'll search the web and discover one automatically.

curl

curl -X POST https://semanticapi.dev/api/query \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "get air quality index for Tokyo", "auto_discover": true}'

Auto-Discover Capabilities

Even for providers already in our catalog, auto-discover can find new capabilities you didn't know existed. If your query matches a known provider but no existing capability, we'll scrape their current docs and discover the right endpoint.

curl

curl -X POST https://semanticapi.dev/api/query \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "create a Stripe subscription with metered billing", "auto_discover": true}'

Even though Stripe is in the catalog, "metered billing subscriptions" might not be. Auto-discover finds and adds it.

💡 Auto-discovered providers and capabilities are added to the catalog for everyone. The more people use Semantic API, the smarter it gets.

🩺 Auto-Heal

APIs break — endpoints move, versions deprecate, base URLs change. Semantic API detects and fixes these issues automatically, so your integration never breaks.

How It Works

1. Detect

API returns 404, 410, or deprecation errors — indicators of a stale config

2. Diagnose

LLM analyzes the error to infer the correct base URL, or re-discovers from current docs

3. Patch

Updates the provider config on disk — the fix is permanent, not just for your request

4. Retry

Retries the original request with the healed config — all in one round trip

What Triggers Auto-Heal

HTTP 404 — Endpoint not found (URL probably changed)
HTTP 410 — Gone (endpoint deprecated)
HTTP 405 — Method not allowed (API restructured)
Deprecation keywords — "deprecated", "no longer available", "moved permanently"

🛡️ Auto-heal works transparently. You never see the broken response — just the successful retry. Enable it by setting auto_discover: true on your queries.

🔌 Provider Auth Guides

Every provider in the catalog includes structured auth metadata — signup URL, step-by-step instructions, and time estimates. No more hunting through docs.

Example: Auth metadata in provider response

{
  "auth": {
    "type": "api_key",
    "signup_url": "https://home.openweathermap.org/users/sign_up",
    "free_tier": true,
    "free_tier_limits": "1000 calls/day, 60 calls/min",
    "signup_steps": [
      "Visit signup_url",
      "Create account with email",
      "Go to API Keys section",
      "Copy default key (active in ~2 hours)"
    ],
    "requires": ["email"],
    "time_to_key": "< 2 hours"
  }
}

This metadata is available for all 570+ providers. Use GET /api/catalog/{provider_id} to see the full auth guide for any provider, or browse the catalog →