Your first API call

Call a free catalog API through the Ozma gateway and read the response envelope.

This walkthrough uses Frankfurter Exchange Rates (frankfurter) — a free platform catalog API (price_cents = 0). No credit card required.

1. Get an API key

Option A — agent auto-register (0 credits, free APIs only):

npx @ozma_app/cli register --json
# save api_key to ~/.ozma/config.json or export OZMA_API_KEY

Option B — human signup ($1 trial after email verify):

export OZMA_API_KEY=ozma_live_xxxxxxxxxxxxxxxxxxxxxxxx

2. Inspect the listing

npx @ozma_app/cli inspect frankfurter --schema --json

Note the proxy path: GET /latest with query params from, to.

3. Call through the gateway

curl -s -H "Authorization: Bearer $OZMA_API_KEY" \
  "https://gateway.ozma.app/v1/proxy/frankfurter/latest?from=USD&to=EUR" | jq

Or with the CLI:

npx @ozma_app/cli call frankfurter /latest --query from=USD --query to=EUR --json

4. Read the envelope

{
  "ok": true,
  "data": {
    "amount": 1.08,
    "base": "USD",
    "date": "2026-07-22",
    "rates": { "EUR": 0.92 }
  },
  "meta": {
    "request_id": "req_01J…",
    "cost_cents": 0,
    "price_cents_effective": 0,
    "credit_applied_cents": 0,
    "billable_cents": 0
  }
}

ok — success vs failure
data — upstream JSON body
meta.request_id — support correlation id
meta.cost_cents — what this call would cost (0 for free APIs)

Alternative: httpbin.org

For a request-echo example:

curl -s -H "Authorization: Bearer $OZMA_API_KEY" \
  "https://gateway.ozma.app/v1/proxy/httpbin-org/get?hello=ozma" | jq '.data'

Free vs paid

	Free (`price_cents = 0`)	Paid
Card required	No	Yes (after credits)
Register-only key	Works	Blocked at 402
`meta.billable_cents`	0	May be > 0 postpaid

Some APIs require provider terms acceptance before calls succeed (HTTP 428). Frankfurter and httpbin currently have no required terms.

Next steps