REST

API Documentation

REST reference — search tools, call tools, handle errors.

Quick Start

Uno has two endpoints. That's it.

1. Search Tools

GET/v1/tools
http
GET /v1/tools?q=weather&limit=5&mode=hybrid
Authorization: Bearer <API_KEY>

Returns tools with input_schema (JSON Schema) so you know exactly what arguments to pass.

Query params: q (keyword), category, server (server slug filter), mode=keyword|semantic|hybrid (default hybrid), limit (≤50), offset. Search is public — Bearer token is optional and only used to log usage.

json
{
  "tools": [
    {
      "tool": "weather-free.get_current_weather",
      "name": "get_current_weather",
      "desc": "Get current weather for a city",
      "desc_en": "Get current weather for a city",
      "input_schema": { "type": "object", "properties": { "location": { "type": "string" } }, "required": ["location"] },
      "server": "weather-free",
      "server_name": "Weather Free",
      "category": "weather",
      "auth_required": false,
      "stats": { "avg_ms": 234, "calls_7d": 1200, "success_rate": 0.99, "rating": 4.5 },
      "pricing": { "mode": "per_call", "cost": 1.0 }
    }
  ],
  "total": 1,
  "mode": "hybrid"
}

2. Call a Tool

POST/v1/call
http
POST /v1/call
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"tool": "amap-maps.weather", "arguments": {"city": "北京"}}
JSON

Response Format

json
{
  "data": {"temperature": "22C", "weather": "晴"},
  "error": null,
  "meta": {
    "latency_ms": 234,
    "credits_used": 1.0,
    "rating_hint": "如果结果符合预期，建议调用 POST /v1/rate 对 tool 评分（0-5）"
  }
}

More Endpoints

Beyond search & call, these are the endpoints agents and SDKs use most. All require a Bearer token except where noted.

GET /v1/serversList hosted servers with tool counts, grouped by category (public)
GET /v1/tools/{tool_slug}Single tool detail with full pricing & stats (public)
POST /v1/rateRate a tool 0.0–5.0; upserts your rating and updates aggregates
GET /v1/auth/meCurrent user info — credits, plan, balance
GET /v1/auth/keysList your API keys
POST /v1/auth/keysCreate a new API key (returns raw key once)

MCP & SDK

Connect Claude Desktop, Cursor, or any MCP client to use all Uno tools — no code needed. Or integrate with Python SDK for programmatic access.

Claude Desktop / Cursor

json
{
  "mcpServers": {
    "uno": {
      "url": "https://clawdtools.uno/mcp"
    }
  }
}

OAuth login opens automatically in your browser. After authorization, tools are available instantly.

Python SDK

python
from uno_sdk import Uno

uno = Uno(api_key="uk-xxx")

# Sync call with retry + per-call timeout
result = uno.call(
    "weather-free.get_current_weather",
    {"location": "Beijing"},
    retry=3, timeout=30,
)

# Validate args against the tool's JSON Schema before sending
tools = uno.search("weather")
uno.call_tool(tools[0], {"location": "Beijing"})  # validates by default

pip install uno-sdk

Async · Batch · Long-running jobs

python
from uno_sdk import AsyncUno

async with AsyncUno(api_key="uk-xxx") as uno:
    # Concurrent batch with concurrency cap & order preservation
    results = await uno.call_batch([
        ("tikhub-douyin.fetch_video_stats", {"aweme_id": "aaa"}),
        ("tikhub-douyin.fetch_video_stats", {"aweme_id": "bbb"}),
    ], max_concurrency=10, return_exceptions=True)

    # Submit + poll long-running jobs to completion (transcription, etc.)
    transcript = await uno.call_async(
        "qingdou-video-text.qingdou_submit",
        {"urls": "https://v.douyin.com/xxx/"},
        "qingdou-video-text.qingdou_result",
        max_wait=180,
    )

Authentication

Tool calls, ratings and account endpoints require a Bearer token (API Key). Search & browse are public. Get a key from the API Keys page.

For CLI Agents (Device Code Flow)

shell
# 1. Request device code
curl -s -X POST https://clawdtools.uno/oauth/device/code \
  -H "Content-Type: application/json" \
  -d '{"client_id":"my-agent"}'

# 2. User authorizes, then poll for token
curl -s -X POST https://clawdtools.uno/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"device_code":"DEVICE_CODE","client_id":"my-agent"}'

Agent Integration (skill.md)

Any agent can integrate Uno with a single command:

shell
curl -s https://clawdtools.uno/v1/skill.md

This returns a Markdown guide that agents can follow to search and call tools.

Error Handling

errorMeaning
tool_not_foundTool slug doesn't exist
auth_requiredTool needs OAuth — check auth_url in response
insufficient_creditsOut of credits — check recharge_url
rate_limit_exceededRate limit exceeded — retry after retry_after_seconds
tool_disabled / server_disabledTool or server is marked inactive
invalid_argumentsArguments failed JSON Schema validation (client-side)
upstream_timeout / upstream_cancelledUpstream timed out / connection cancelled — auto-retryable

Pricing

  • Free: 500 credits daily, auto-reset
  • Most tools: 1 credit per call
  • AI generation tools: 5-10 credits per call
  • per_token pricing (LLM tools): credits = (request + response chars / 4) × token_price