Skip to main content

OpenAPI to Endpoints

This walkthrough turns an existing OpenAPI 3.0 or 3.1 spec into a set of paid ampersend hosted endpoints. Every path + method pair becomes one endpoint; the proxy forwards paid calls to your upstream and returns the response verbatim.

Prerequisites​

  • An agent account and active local config. Follow the SDK quick start and run ampersend setup if you haven't already.
  • ampersend v0.0.20 or later (ampersend --version).
  • A JSON OpenAPI 3.0 or 3.1 file for the API you want to monetize. Swagger 2.x specs must be upgraded to OpenAPI 3 first (any swagger2openapi-style tool works).

1. Inspect the spec​

endpoint import reads from a local JSON file — YAML is not parsed. If your source is YAML, convert it once before importing, for example with any yaml → json tool.

Every operation becomes an endpoint using these defaults, unless overridden by vendor extensions (see below):

  • Base URL — servers[0].url. Override with --base-url.
  • Name — summary → operationId → METHOD /path, in that order.
  • Description — description → summary.
  • Allowed method — the operation's method.
  • Price — x-ampersend-price if present, otherwise the --default-price you pass on the CLI. If you omit --default-price, it silently defaults to 0.01 USD — always pass an explicit value for production imports.

2. Dry-run the import​

Start with --dry-run to verify the spec parses and the endpoint list looks right. No endpoints are created.

ampersend endpoint import ./openapi.json \
  --default-price 0.001 \
  --dry-run

The command returns the parsed endpoint list:

{
  "ok": true,
  "data": {
    "dryRun": true,
    "count": 12,
    "endpoints": [
      {
        "name": "Get weather",
        "price_usd": 0.001,
        "proxy_url": "https://api.example.com/v1/weather",
        "allowed_methods": ["GET"]
      }
    ]
  }
}

Scan the output for:

  • Endpoints you do not want to expose for payment (internal or free routes).
  • Paths that need a different price.
  • Missing / wrong proxy_url (fix by passing --base-url).

3. Fine-tune with vendor extensions​

To customize per-operation settings without CLI flags, add extensions directly in the spec:

ExtensionTypeEffect
x-ampersend-pricenumberPer-call price in USD
x-ampersend-namestringEndpoint display name override
x-ampersend-descriptionstringDescription override
x-ampersend-rate-limitintegerRate limit per minute

Example:

{
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get weather",
        "x-ampersend-price": 0.002,
        "x-ampersend-rate-limit": 60
      }
    }
  }
}

Re-run the dry-run until the output matches what you want to publish.

4. Create the endpoints​

Drop the --dry-run flag to actually create them:

ampersend endpoint import ./openapi.json \
  --default-price 0.001 \
  --timeout 10000

The response includes the number created and the list of new endpoint records:

{
  "ok": true,
  "data": {
    "dryRun": false,
    "count": 12,
    "created": 12,
    "endpoints": [
      /* ... */
    ]
  }
}

5. Verify​

List and test:

ampersend endpoint list
ampersend endpoint test <id>

endpoint test sends a synthetic request through the proxy so you can confirm the upstream is reachable with the current proxy_url and headers.

6. Add upstream credentials (optional)​

If your upstream needs an API key, attach it as a proxy header. The value is stored encrypted and included on every proxied request:

ampersend endpoint headers add-proxy <id> \
  --name "Authorization" \
  --value "Bearer <upstream-key>"

Use remove-proxy to clear it, or rotate-secret to roll the per-endpoint signing secret upstreams use to verify ampersend-originated traffic.

Troubleshooting​

SymptomFix
Could not resolve a base URLPass --base-url https://...
Resolved base URL must be http(s)The spec's base URL is invalid; override with --base-url
Invalid price for METHOD /path: must be > 0Add x-ampersend-price to the operation or raise --default-price
Endpoint created but calls fail with 5xxendpoint test <id>; check proxy_url and any upstream auth header