{"openapi":"3.1.0","info":{"title":"PilotEsim API","version":"2.0.0","description":"Provision eSIMs, load data credit onto them, and read metered usage.\n\nAuthenticate with `Authorization: Bearer sk_live_…`. POSTs accept an `Idempotency-Key`\nheader; list endpoints accept `limit` and `offset`.\n\n**Two kinds of money.** Your *wallet* holds credit you have bought. Loading credit onto\nan eSIM (`fund_usd` / `amount_usd`) MOVES wallet credit onto the carrier — it takes no\npayment and cannot create balance, and returns 402 if your wallet is short. To BUY\ncredit you need a card, so `POST /wallet/topups` returns a hosted checkout URL rather\nthan charging anything; the wallet is credited once the payment settles."},"servers":[{"url":"https://www.pilotesim.com/api/v1"},{"url":"http://localhost:3000/api/v1"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}}},"security":[{"BearerAuth":[]}],"paths":{"/coverage":{"get":{"summary":"List coverage & rates","x-scope":"coverage:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"A page of covered countries."}}}},"/wallet":{"get":{"summary":"Get wallet balance","x-scope":"esims:read","responses":{"200":{"description":"The caller's spendable balance."}}}},"/wallet/topups":{"post":{"summary":"Buy wallet credit (returns a checkout URL)","description":"Does NOT charge anything. Returns a hosted-checkout URL; the wallet is credited by webhook once the customer completes payment. Poll GET /wallet or subscribe to `topup.succeeded` to see the credit land.","x-scope":"esims:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_usd"],"properties":{"amount_usd":{"type":"number","minimum":4,"maximum":1000}}}}}},"responses":{"201":{"description":"A pending top-up with a `checkout_url` to send the customer to."},"503":{"description":"Payments are not configured."}}}},"/esims":{"get":{"summary":"List eSIMs","x-scope":"esims:read","responses":{"200":{"description":"A page of the caller's eSIMs."}}},"post":{"summary":"Provision an eSIM and load data credit onto it","description":"`fund_usd` is taken from the caller's wallet and loaded onto the eSIM at the carrier. If the carrier call fails, the money is returned to the wallet.","x-scope":"esims:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country","fund_usd"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2","example":"JP"},"fund_usd":{"type":"number","minimum":4,"maximum":1000,"description":"Data credit to load, taken from your wallet balance."}}}}}},"responses":{"201":{"description":"The provisioned eSIM + LPA install string."},"422":{"description":"Insufficient balance, or the carrier refused the order."}}}},"/esims/{id}/usage":{"get":{"summary":"Get usage & what's left on the eSIM","description":"Syncs from the carrier before responding, so the figures are current.","x-scope":"esims:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Carrier usage, remaining credit and wallet balance."}}}},"/esims/{id}/topups":{"post":{"summary":"Load more data credit onto an eSIM","description":"Moves credit from the caller's wallet onto the eSIM at the carrier. Takes no payment. Returns 402 when the wallet is short — top up at POST /wallet/topups.","x-scope":"esims:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_usd"],"properties":{"amount_usd":{"type":"number","minimum":4,"maximum":1000}}}}}},"responses":{"201":{"description":"Updated eSIM funding + wallet balance."},"402":{"description":"Insufficient wallet balance."}}}}}}