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:

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

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.

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"