coal
coal

OpenAPI Import

Paste an OpenAPI / Swagger spec, hit Preview, confirm, and Coal creates one bundle plus one paywall per endpoint. The highest-leverage path for sellers with existing API documentation.

Supported specs

  • OpenAPI 3.0 and 3.1
  • Swagger 2.0 (auto-converted via @apidevtools/swagger-parser)
  • YAML or JSON
  • Up to 200 endpoints per import

Walkthrough

1. Open the Paywalls page, click New Paywall ▾ → Manage upstream bundles, then Import from OpenAPI, name your bundle, submit.

2. On the next screen, paste your spec URL or upload the YAML/JSON file (max 1 MB).

3. Coal returns a preview table:

MethodPathSuggested nameSuggested price
GET/user/{username}Fetch user$0.05
GET/user/{username}/tweetsList user tweets$0.05
GET/searchSearch tweets$0.05

4. Edit per-row: change names, adjust prices, remove rows you do not want to monetize.

5. Fill in:

  • Origin URL — pre-filled from spec.servers[0] if present; otherwise paste manually
  • Origin auth headers (optional) — e.g. x-rapidapi-key for RapidAPI passthroughs

6. Click Create N paywalls. You land on the bundle detail view with every endpoint live at https://api.usecoal.xyz/p/{bundle-slug}/{path}.

RapidAPI shortcut

If your API is listed on RapidAPI, paste the listing URL and Coal extracts the spec URL automatically. Confirms in the same preview table.

The RapidAPI extraction is best-effort — if it 404s, paste the spec URL directly. Most RapidAPI listings expose their spec via the documented "Code Snippets → cURL" pane.

What gets created

For a spec with N endpoints:

  • One ApiBundle row keyed by slug, with originUrl set
  • N Paywall rows, each with bundleId, methodHint, pathTemplate, slug, price, proxyEnabled: true
  • forwardQuery: true, forwardBody: true, forwardCookies: false by default — toggle per-paywall in the detail view if you need cookies forwarded

Slug collisions across merchants are handled by the slug reservation system: a generated slug like twitter-aio-user becomes twitter-aio-user-2 if taken.

Limits

  • 200 endpoints per spec. Above that the preview returns too_many_endpoints — split the spec.
  • 1 MB inline upload, 4 MB via URL fetch.
  • Unsupported HTTP methods (HEAD, OPTIONS, TRACE) are silently skipped.
  • The parser walks $refs and inlines them; circular refs throw.

API equivalents

If you prefer to script this:

bash
1# Preview
2curl -X POST https://api.usecoal.xyz/api/console/api-bundles/openapi-preview \
3  -H "Authorization: Bearer <session>" \
4  -H "Content-Type: application/json" \
5  -d '{"specUrl": "https://api.example.com/openapi.json"}'
6

7# Import (after merchant edits)
8curl -X POST https://api.usecoal.xyz/api/console/api-bundles/openapi-import \
9  -H "Authorization: Bearer <session>" \
10  -H "Content-Type: application/json" \
11  -d @import-payload.json

The session bearer is whatever Privy hands you in the browser — same auth as the console.