{"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. Returns 402 when the wallet is short — top up at POST /wallet/topups.","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."},"402":{"description":"Insufficient wallet balance — buy credit at POST /wallet/topups and retry."},"422":{"description":"Invalid request, or the carrier refused the order."},"503":{"description":"The eSIM provider is not configured."}}}},"/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 — buy credit at POST /wallet/topups and retry."},"422":{"description":"Invalid request, or the carrier refused the order."},"503":{"description":"The eSIM provider is not configured."}}}}}}