{"openapi":"3.1.0","info":{"title":"ESIM Go (BYOK) API","version":"0.1.0","description":"ESIM Go (BYOK) lets an AI assistant read your own ESIM Go data through the ESIM Go API with a key you supply (eSIM Go API key). Read-only: 11 tools (get_organisation, list_bundle_groups, list_catalogue, get_catalogue_bundle, list_esims, get_esim, list_esim_bundles, get_esim_history, get_bundle_inventory, list_networks, get_order). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-esim-go.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-esim-go/docs"},"termsOfService":"https://connectorbay.com/byok-esim-go/terms"},"servers":[{"url":"https://byok-esim-go.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-esim-go/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_organisation":{"post":{"operationId":"get_organisation","summary":"Show your eSIM Go organisation: name, currency, prepaid balance (which includes any test credit), test credit and its ex","description":"Show your eSIM Go organisation: name, currency, prepaid balance (which includes any test credit), test credit and its expiry, and bundle groups. Use for \"How much prepaid balance does my eSIM Go account have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_organisationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_bundle_groups":{"post":{"operationId":"list_bundle_groups","summary":"List the bundle groups your organisation can order from, with description and the URL of each group's price list. Use fo","description":"List the bundle groups your organisation can order from, with description and the URL of each group's price list. Use for \"Which eSIM Go bundle groups are available to my account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_bundle_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_catalogue":{"post":{"operationId":"list_catalogue","summary":"List bundles your organisation can order, with data amount, duration, speed and price. The vendor asks that the catalogu","description":"List bundles your organisation can order, with data amount, duration, speed and price. The vendor asks that the catalogue be fetched only when needed and kept for reuse rather than polled. Use for \"Which eSIM Go bundles cover Japan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"countries":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ISO country codes; bundles whose base country is any of them, for example 'GB,US'.","title":"Countries"},"region":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Region name such as 'Europe'; bundles with a base country in that region.","title":"Region"},"group":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact bundle group name, for example 'Standard Fixed Bundles'.","title":"Group"},"description":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Wildcard search text in the bundle description.","title":"Description"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction.","title":"Direction"},"order_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Name of the column to sort by.","title":"Order By"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Bundles per page, for example 50.","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_catalogueArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_catalogue_bundle":{"post":{"operationId":"get_catalogue_bundle","summary":"Get one catalogue bundle by its case-sensitive name, with the countries it covers and the mobile networks in each (name,","description":"Get one catalogue bundle by its case-sensitive name, with the countries it covers and the mobile networks in each (name, TADIG, MCC-MNC, speeds). Use for \"Which networks does the bundle esim_1GB_7D_IM_U use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Exact, case-sensitive bundle name, for example esim_1GB_7D_IM_U.","maxLength":200,"title":"Name","type":"string"}},"required":["name"],"title":"get_catalogue_bundleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_esims":{"post":{"operationId":"list_esims","summary":"List the eSIMs assigned to your organisation with ICCID, your reference, last action, state (active, suspended, deactiva","description":"List the eSIMs assigned to your organisation with ICCID, your reference, last action, state (active, suspended, deactivated) and assignment date. Use for \"Which of my eSIMs are suspended\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter_by":{"anyOf":[{"enum":["iccid","customerRef","lastAction","actionDate","assignedDate"],"type":"string"},{"type":"null"}],"default":null,"description":"Column to filter on: iccid, customerRef, lastAction, actionDate or assignedDate.","title":"Filter By"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Value to match in the filter_by column.","title":"Filter"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction.","title":"Direction"},"order_by":{"anyOf":[{"const":"iccid","type":"string"},{"type":"null"}],"default":null,"description":"Column to sort by; only iccid is supported.","title":"Order By"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"eSIMs per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_esimsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_esim":{"post":{"operationId":"get_esim","summary":"Get one eSIM's install status (Released, Installed, Downloaded, Unavailable or Deactivated), first install time, your re","description":"Get one eSIM's install status (Released, Installed, Downloaded, Unavailable or Deactivated), first install time, your reference and branding. PIN and PUK are not returned by this tool. Use for \"Has the eSIM with ICCID 8944123456789012000 been installed yet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"iccid":{"description":"ICCID of the eSIM, the 19 to 20 digit SIM identifier, for example 8944123456789012000.","maxLength":200,"title":"Iccid","type":"string"}},"required":["iccid"],"title":"get_esimArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_esim_bundles":{"post":{"operationId":"list_esim_bundles","summary":"List the bundles applied to one eSIM with their data, voice and SMS allowances, remaining amounts, start and end times. ","description":"List the bundles applied to one eSIM with their data, voice and SMS allowances, remaining amounts, start and end times. Use for \"How much data is left on the bundles of eSIM 8944123456789012000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"iccid":{"description":"ICCID of the eSIM, the 19 to 20 digit SIM identifier, for example 8944123456789012000.","maxLength":200,"title":"Iccid","type":"string"},"include_used":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include used and expired bundles as well.","title":"Include Used"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"Number of assignments to return, 1 to 200 (default 15).","title":"Limit"}},"required":["iccid"],"title":"list_esim_bundlesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_esim_history":{"post":{"operationId":"get_esim_history","summary":"List the lifecycle events of one eSIM (bundle applied, revoked and similar) with bundle name and time. Use for \"What hap","description":"List the lifecycle events of one eSIM (bundle applied, revoked and similar) with bundle name and time. Use for \"What happened on eSIM 8944123456789012000 recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"iccid":{"description":"ICCID of the eSIM, the 19 to 20 digit SIM identifier, for example 8944123456789012000.","maxLength":200,"title":"Iccid","type":"string"}},"required":["iccid"],"title":"get_esim_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_bundle_inventory":{"post":{"operationId":"get_bundle_inventory","summary":"List the bundles your organisation has bought but not yet applied, with remaining counts, expiry, countries and allowanc","description":"List the bundles your organisation has bought but not yet applied, with remaining counts, expiry, countries and allowances. Use for \"Which purchased eSIM Go bundles are still unused in my inventory\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_bundle_inventoryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_networks":{"post":{"operationId":"list_networks","summary":"List mobile networks per country (name, brand, MCC, MNC, TADIG, speeds). Set return_all or give countries or ISO codes. ","description":"List mobile networks per country (name, brand, MCC, MNC, TADIG, speeds). Set return_all or give countries or ISO codes. Use for \"Which mobile networks does eSIM Go reach in Turkey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"isos":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ISO country codes, for example 'GB,US'.","title":"Isos"},"countries":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated country names, for example 'United Kingdom,United States'.","title":"Countries"},"return_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return every country.","title":"Return All"}},"title":"list_networksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_order":{"post":{"operationId":"get_order","summary":"Get one order by its reference: status, total, currency, creation time and whether the bundle was assigned. Use for \"Wha","description":"Get one order by its reference: status, total, currency, creation time and whether the bundle was assigned. Use for \"What is the status of my eSIM Go order 1a2b3c4d\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_reference":{"description":"The order reference returned when the order was placed.","maxLength":200,"title":"Order Reference","type":"string"}},"required":["order_reference"],"title":"get_orderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}