Publish from OpenAPI

This example walks through publishing an API with the Ozma CLI. You need an email-verified key or session (provider:write scope).

npx @ozma_app/cli login --email [email protected]

1. Import OpenAPI

npx @ozma_app/cli provider create ./openapi.yaml --json
# or from URL:
npx @ozma_app/cli provider create https://example.com/openapi.json --json

Save the returned api_id (e.g. api_01J…).

2. Patch metadata (optional)

npx @ozma_app/cli provider patch api_01J… \
  --name "My Weather API" \
  --summary "Hourly forecasts" \
  --category weather \
  --json

3. Store upstream credentials

Use the correct flags — secret value, injection type, and header/query name:

npx @ozma_app/cli provider credentials api_01J… \
  --secret "sk_upstream_secret_here" \
  --injection header \
  --injection-name "X-Api-Key" \
  --json

Other injection modes: bearer, query (with --injection-name as the query param key).

Secrets are AES-GCM encrypted at rest and never returned via API.

4. Smoke-test upstream

npx @ozma_app/cli provider verify api_01J… --json

Verify requires 2xx responses from GET endpoints. Fix credentials or base URL if this fails.

5. Set endpoint pricing

Per-endpoint cents — use --endpoint-id and --price-cents:

# List endpoints from provider get
npx @ozma_app/cli provider get api_01J… --json

npx @ozma_app/cli provider pricing api_01J… \
  --endpoint-id ep_01J… \
  --price-cents 5 \
  --json

Free endpoints: --price-cents 0. Bulk pricing via --file pricing.json.

6. Stripe Connect (paid APIs only)

If any endpoint is paid, complete Connect before publish:

npx @ozma_app/cli provider connect --json
# Human completes KYC in browser — payouts_enabled + transfers must be active

Free-only APIs skip this step.

7. Publish (Ozma reseller attestation)

--accept-terms is required — attests to Ozma platform/reseller terms, not your consumer-facing API terms:

npx @ozma_app/cli provider publish api_01J… --accept-terms --json

Production paid publish re-runs upstream verify unless you have an admin skip (not available to normal providers).

8. Optional provider documents / terms

After publish, attach legal documents for consumers:

# Draft terms (display-only — shown on listing, no gateway gate)
npx @ozma_app/cli provider documents create \
  --kind terms \
  --source hosted \
  --version 1.0.0 \
  --markdown ./terms.md \
  --api-id api_01J… \
  --acceptance-mode display_only \
  --json

# Activate (draft → active)
npx @ozma_app/cli provider documents activate doc_01J… --json

For required acceptance (gateway 428 until accepted):

npx @ozma_app/cli provider documents create \
  --kind terms \
  --source hosted \
  --version 1.0.0 \
  --markdown ./terms.md \
  --api-id api_01J… \
  --acceptance-mode required \
  --json

npx @ozma_app/cli provider documents activate doc_01J… --json

Consumers accept via session: ozma terms accept <slug> --yes.

Other kinds: privacy, aup, dpa (see CLI help).

9. Confirm live

npx @ozma_app/cli inspect my-api-slug --json
curl "https://api.ozma.app/v1/apis/my-api-slug/openapi"

Listing appears at https://ozma.app/apis/my-api-slug.

Related

• Publish & verify guide
• Pricing & payouts
• Provider quickstart