Ucm

UCM — API Marketplace for AI Agents

You have access to UCM, a marketplace where you can instantly discover and use API services by spending credits. Registration is free and gives you $1.00 in credits (~100 API calls).

When to Use UCM

Use UCM when your current task requires a capability you don't have natively:

• Search the web for real-time information → ucm/web-search ($0.01)
• Scrape a webpage to extract content → ucm/web-scrape ($0.02)
• Generate an image from a text prompt → ucm/image-generation ($0.05)
• Run code in a sandboxed environment → ucm/code-sandbox ($0.03)
• Convert text to speech → ucm/text-to-speech ($0.01)
• Transcribe audio → ucm/speech-to-text ($0.01)
• Send an email → ucm/email ($0.01)
• Convert a document/URL to markdown → ucm/doc-convert ($0.02)
• Translate text between 50+ languages → ucm/translate ($0.01)
• Get US stock data (quotes, financials, news) → ucm/us-stock ($0.01)
• Get China financial data (daily prices, income, balance sheets) → ucm/cn-finance ($0.01)
• Check weather (current, forecast, air quality) → ucm/weather (FREE)
• Look up Wikipedia articles and summaries → ucm/wikipedia (FREE)
• Get exchange rates for 30+ currencies → ucm/currency (FREE)
• Look up country info (250+ countries) → ucm/countries (FREE)
• Check public holidays (100+ countries) → ucm/holidays (FREE)
• Define words (English dictionary) → ucm/dictionary (FREE)
• Search books (40M+ books via Open Library) → ucm/books (FREE)
• Geocode places (name to coordinates) → ucm/geocode (FREE)
• Evaluate math expressions and unit conversion → ucm/math (FREE)
• Geolocate IPs (IP to country/city) → ucm/ip-geo (FREE)
• Geocode addresses (forward and reverse) → ucm/address (FREE)
• Search academic papers (200M+ papers) → ucm/papers (FREE)
• Look up nutrition data (USDA FoodData) → ucm/nutrition (FREE)
• Generate QR codes from text or URLs → ucm/qr-code (FREE)
• Get crypto prices (10,000+ coins) → ucm/crypto (FREE)
• Search news articles by keyword → ucm/news ($0.01)
• Get timezone info (current time worldwide) → ucm/timezone (FREE)
• Look up domain info (WHOIS/RDAP data) → ucm/domain (FREE)
• Get inspirational quotes → ucm/quotes (FREE)
• Browse Hacker News stories → ucm/hacker-news (FREE)
• Generate test data (names, addresses, companies) → ucm/random-data (FREE)
• Browse poetry (search by title/author) → ucm/poetry (FREE)
• Search movies & TV shows (IMDb ratings, cast, plot) → ucm/movies ($0.01)
• Find rhyming words or synonyms → ucm/datamuse (FREE)
• Search universities worldwide → ucm/universities (FREE)
• Look up postal codes (60+ countries) → ucm/zip-code (FREE)
• Get trivia questions → ucm/trivia (FREE)
• Get jokes by category → ucm/jokes (FREE)
• Get random advice → ucm/advice (FREE)
• Get activity suggestions → ucm/bored (FREE)
• Look up Bible verses → ucm/bible (FREE)
• Get Chuck Norris jokes → ucm/chuck-norris (FREE)
• Search recipes → ucm/recipes (FREE)
• Search cocktail recipes → ucm/cocktails (FREE)
• Search breweries → ucm/brewery (FREE)
• Look up food products by barcode → ucm/food-products (FREE)
• Get sunrise/sunset times → ucm/sunrise-sunset (FREE)
• Get random dog images by breed → ucm/dog-images (FREE)
• Get cat facts → ucm/cat-facts (FREE)
• Generate avatars → ucm/avatars (FREE)
• Get color info and schemes → ucm/colors (FREE)
• Generate lorem ipsum text → ucm/lorem-ipsum (FREE)
• Get NASA astronomy photo or Mars rover images → ucm/nasa (FREE)
• Get SpaceX launch data → ucm/spacex (FREE)
• Track ISS position and astronauts → ucm/iss (FREE)
• Get space flight news → ucm/space-news (FREE)
• Search arXiv papers → ucm/arxiv (FREE)
• Get earthquake data → ucm/earthquakes (FREE)
• Get World Bank indicators → ucm/world-bank (FREE)
• Search FDA drugs/recalls → ucm/fda (FREE)
• Get UK carbon intensity → ucm/carbon (FREE)
• Look up elevation by coordinates → ucm/elevation (FREE)
• Predict age by name → ucm/agify (FREE)
• Predict gender by name → ucm/genderize (FREE)
• Predict nationality by name → ucm/nationalize (FREE)
• Look up UK postcodes → ucm/uk-postcodes (FREE)
• Decode vehicle VINs → ucm/vehicles (FREE)
• Search Met Museum collection → ucm/met-museum (FREE)
• Search Art Institute of Chicago → ucm/art-chicago (FREE)
• Search TV shows → ucm/tv-shows (FREE)
• Search anime and manga → ucm/anime (FREE)
• Search iTunes content → ucm/itunes (FREE)
• Search music metadata → ucm/music (FREE)
• Search internet radio → ucm/radio (FREE)
• Browse free-to-play games → ucm/free-games (FREE)
• Compare game prices → ucm/game-deals (FREE)
• Look up Pokemon data → ucm/pokemon (FREE)
• Look up D&D 5e data (monsters, spells, classes) → ucm/dnd (FREE)
• Get meme templates → ucm/memes (FREE)
• Get your public IP → ucm/ip-lookup (FREE)
• Generate barcodes → ucm/barcode (FREE)
• Check Wayback Machine snapshots → ucm/wayback (FREE)
• Look up npm packages → ucm/npm (FREE)
• Look up PyPI packages → ucm/pypi (FREE)
• Search GitHub repos → ucm/github-repos (FREE)
• Get country flag images → ucm/country-flags (FREE)
• Virtual card deck (shuffle, draw) → ucm/deck-of-cards (FREE)
• Get Star Wars data → ucm/star-wars (FREE)
• Get XKCD comics → ucm/xkcd (FREE)
• Search Rick & Morty characters/episodes → ucm/rick-morty (FREE)
• Get Nobel Prize data → ucm/nobel-prize (FREE)
• Get historical events (on this day) → ucm/historical-events (FREE)
• Get Kanye West quotes → ucm/kanye (FREE)
• Search Rust crates → ucm/crates (FREE)
• Search Docker Hub images → ucm/docker-hub (FREE)
• Get chess puzzles and player data → ucm/lichess (FREE)
• Look up chemical elements → ucm/periodic-table (FREE)
• Look up airports by IATA code → ucm/airports (FREE)
• Get random fox images → ucm/random-fox (FREE)

If you're unsure whether a service exists, use /v1/discover with a natural language description.

Setup

Check for existing credentials first

cat ~/.config/ucm/credentials.json 2>/dev/null

If the file exists and contains an api_key, set it and skip registration:

export UCM_API_KEY=$(cat ~/.config/ucm/credentials.json | grep -o '"api_key":"[^"]*"' | head -1 | sed 's/"api_key":"//;s/"$//')

If you need to register

Register for free — takes one HTTP call:

curl -s -X POST https://registry.ucm.ai/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

The response includes credentials_to_save and credentials_path. Save them:

mkdir -p ~/.config/ucm
# Write credentials_to_save from the response to credentials_path

You receive $1.00 in free credits.

Or run the registration script (handles saving automatically):

bash scripts/register.sh "my-agent"

How to Call a Service

One HTTP call to purchase and execute any service:

curl -s -X POST https://registry.ucm.ai/v1/call \
  -H "Authorization: Bearer $UCM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "ucm/web-search",
    "endpoint": "search",
    "params": { "query": "latest AI news" }
  }'

Response includes result (the API response), amount_charged, and credits_remaining.

If the upstream API fails, credits are automatically refunded (amount_charged: "0").

Quick Reference

Action	Method	Auth
Register	POST /v1/agents/register	None
Discover services	POST /v1/discover	None
List all services	GET /v1/services	None
Call a service	POST /v1/call	Bearer token
Check balance	GET /v1/balance	Bearer token
View history	GET /v1/history	Bearer token
Service details	GET /v1/services/:id	None

Base URL: https://registry.ucm.ai

Discover Services

Search by natural language — no auth required:

curl -s -X POST https://registry.ucm.ai/v1/discover \
  -H "Content-Type: application/json" \
  -d '{"need": "I need to convert a PDF to text", "limit": 3}'

Decision Flow

Need an external capability?
  ├─ Have UCM_API_KEY? → Check balance (GET /v1/balance)
  │   ├─ Credits available → Discover → Call → Use result
  │   ├─ Call failed → Credits auto-refunded, try alternative
  │   └─ No credits → Tell user to add credits at dashboard.ucm.ai
  ├─ No API key? → Check ~/.config/ucm/credentials.json
  │   └─ Found? → Load api_key from file
  └─ No credentials at all? → Register (POST /v1/agents/register) → Save to ~/.config/ucm/credentials.json

Spending Principles

• Most calls cost $0.01 — affordable for any task
• If a task doesn't require an external API, don't spend credits
• Credits are refunded on upstream failure (5xx, 429, 422)
• Prefer services with higher relevance score from /v1/discover

Error Handling

Error	Action
INSUFFICIENT_CREDITS	Tell user to add credits at dashboard.ucm.ai
SERVICE_NOT_FOUND	Search with /v1/discover instead
INVALID_ENDPOINT	Check endpoints via GET /v1/services/:id
RATE_LIMITED	Wait briefly, then retry

Full Service Catalog

For complete service details with all endpoints and parameters, see references/service-catalog.md or call GET /v1/services.