Call Service

The primary endpoint for using UCM services. Atomically purchases access, calls the upstream API, and returns the result. Credits are automatically refunded if the upstream call fails.

Request

POST /v1/call

Auth: API Key (Authorization: Bearer ucm_key_...)

Body

Field	Type	Required	Description
service_id	string	Yes	Service to call, e.g. "ucm/web-search"
endpoint	string	Yes	Endpoint name, e.g. "search", "generate", "execute"
body	object	No	Parameters for the API call

Example

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

Response

200 OK

{
  "tx_id": "uuid-here",
  "amount_charged": "0.01",
  "credits_remaining": "0.99",
  "result": {
    "results": [
      {
        "title": "...",
        "url": "...",
        "content": "..."
      }
    ]
  }
}

On Upstream Failure (Auto-Refund)

If the upstream API returns an error (5xx, 429, or 422 from source), credits are refunded:

{
  "tx_id": "uuid-here",
  "amount_charged": "0",
  "credits_remaining": "1.00",
  "error": "upstream service returned 503"
}

Errors

Code	HTTP	Description
INVALID_REQUEST	400	Missing service_id or endpoint
SERVICE_NOT_FOUND	404	Service does not exist
INVALID_ENDPOINT	400	Endpoint doesn't exist on this service
INSUFFICIENT_CREDITS	402	Not enough credits
AGENT_NOT_CLAIMED	403	Email service requires agent to be claimed via dashboard

Examples by Service

Web Search ($0.01)

{
  "service_id": "ucm/web-search",
  "endpoint": "search",
  "params": { "query": "AI news", "limit": 5 }
}

Image Generation ($0.05)

{
  "service_id": "ucm/image-generation",
  "endpoint": "generate",
  "params": { "prompt": "a cat wearing a hat", "width": 1024, "height": 1024 }
}

Code Sandbox ($0.03)

{
  "service_id": "ucm/code-sandbox",
  "endpoint": "execute",
  "params": { "language": "python", "code": "print(2 + 2)" }
}

Text-to-Speech ($0.01)

{
  "service_id": "ucm/text-to-speech",
  "endpoint": "synthesize",
  "params": { "input": "Hello, world!" }
}

US Stock Quote ($0.01)

{
  "service_id": "ucm/us-stock",
  "endpoint": "quote",
  "params": { "symbol": "AAPL" }
}