# Publish & verify an API

Publishing turns a draft API into a live marketplace listing proxied through `https://gateway.ozma.app`.

Surfaces: [Provider wizard](https://ozma.app/provider/new), CLI `ozma provider *`, MCP `provider_*` tools.

## Prerequisites

- Email-verified account (`provider:write` scope)
- OpenAPI spec (file or URL)
- Upstream API credentials (if required)

## Flow

### 1. Import draft

```bash
npx @ozma_app/cli provider create ./openapi.yaml --json
```

### 2. Store credentials

```bash
npx @ozma_app/cli provider credentials api_123 \
  --secret "YOUR_UPSTREAM_SECRET" \
  --injection header \
  --injection-name "X-Api-Key"
```

Injection options: `header`, `bearer`, `query` (with `--injection-name`).

### 3. Verify upstream (2xx required)

```bash
npx @ozma_app/cli provider verify api_123 --json
```

Smoke-tests GET endpoints without billing. Sets `verifiedAt` on success. Publish in production re-runs verify unless skipped (restricted for paid APIs).

### 4. Set pricing

```bash
npx @ozma_app/cli provider pricing api_123 \
  --endpoint-id ep_456 \
  --price-cents 5
```

### 5. Stripe Connect (paid APIs)

Production paid publish requires Connect with **`payouts_enabled`** + **`transfers` active**:

```bash
npx @ozma_app/cli provider connect
```

Free-only APIs (`price_cents = 0` everywhere) skip Connect.

### 6. Publish — Ozma reseller attestation

```bash
npx @ozma_app/cli provider publish api_123 --accept-terms
```

`--accept-terms` maps to `{ "accept_terms": true }` — attests to **Ozma platform/reseller terms** (`provider_terms_accepted_at`). Distinct from optional provider-authored consumer terms below.

## Optional provider documents / terms

After publish, providers may attach legal documents:

```bash
npx @ozma_app/cli provider documents create \
  --kind terms \
  --source hosted \
  --version 1.0.0 \
  --markdown ./terms.md \
  --api-id api_123 \
  --acceptance-mode display_only

npx @ozma_app/cli provider documents activate doc_123
```

| `acceptance_mode` | Effect |
|-------------------|--------|
| `display_only` | Shown on listing and `/apis/{slug}/terms`; gateway unaffected |
| `required` | Gateway **428** until consumer org owner/admin accepts via session |

Activate moves `draft` → `active` (supersedes prior active doc same scope/kind).

Consumer acceptance:

```bash
ozma login --email you@example.com
ozma terms accept my-api-slug --yes
```

## Production gates summary

| Gate | Applies to |
|------|------------|
| Verify 2xx | All publish (re-run on publish) |
| `--accept-terms` | All publish |
| Connect KYC | Paid APIs in prod |
| Health probe | Live APIs (auto-suspend after 3 failures) |

## Unpublish

```bash
npx @ozma_app/cli provider unpublish api_123
```

Returns listing to draft — removed from public catalog.

## Related

- [Publish from OpenAPI example](/docs/examples/publish-openapi)
- [Pricing & payouts](/docs/guides/pricing-payouts)
- [Provider quickstart](/docs/getting-started/quickstart-provider)