GET /v1/version
Which version answers this account
Headers
Telyne-VersionOmit to use the version pinned to this account at its first call.
Telyne API reference
One API across every capability. REST over HTTPS, JSON in and out, no envelope. A test key reaches simulated resources and cannot reach live ones; the platform enforces that boundary rather than trusting you to.
Base URL and version
| Field | Notes |
|---|---|
| Base URL | https://api.telyne.com |
| Version | 2026-09-01 |
| Specification | https://api.telyne.com/v1/openapi.json |
Environments
| Environment | Key prefix |
|---|---|
test |
sk_test_ |
live |
sk_live_ |
Authentication
An API key. sk_test_ reaches simulated resources; sk_live_ reaches live ones.
| Field | Notes |
|---|---|
| Scheme | http bearer |
| Header | Authorization: Bearer <key> |
Rate limit
| Field | Notes |
|---|---|
| Requests per minute | 120 |
Endpoints
14 operations across 12 paths.
GET
GET /v1/event_types
Every event type the platform emits
Responses
GET /v1/error_codes
Every error code and its shape
Responses
GET /v1/esim/bundles
Bundles available to buy
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
countries |
query | string (pattern ^[A-Za-z]{2}(,[A-Za-z]{2})*$) |
|
region |
query | string |
Responses
GET /v1/esim
eSIMs on this account
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
cursor |
query | string | |
limit |
query | integer (min 1, max 100, default 20) |
Responses
POST /v1/esim
Buy an eSIM
Headers
Idempotency-Keyrequired Required on every call that changes something. The result is stored against it and a repeat returns the original response.
Request body
| Field | Type | Notes |
|---|---|---|
bundle required |
string | |
quantity |
integer (min 1, max 10, default 1) |
Responses
201The order and what it created400unsupported_version, missing_parameter, invalid_parameter, idempotency_key_required Error401key_missing, key_invalid, key_revoked Error402balance_insufficient Error403key_out_of_scope, verification_required Error409idempotency_key_reused, capability_not_orderable Error429rate_limited Error500internal_error Error503supplier_refused Error
GET /v1/esim/{id}
One eSIM, by id or ICCID
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id required |
path | string |
Responses
PATCH /v1/esim/{id}
Change an eSIM's state
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id required |
path | string |
Headers
Idempotency-Keyrequired Required on every call that changes something. The result is stored against it and a repeat returns the original response.
Request body
| Field | Type | Notes |
|---|---|---|
state required |
"released" or "installed" or "active" or "suspended" or "expired" |
Responses
200The eSIM after the change Esim400unsupported_version, missing_parameter, invalid_parameter, idempotency_key_required Error401key_missing, key_invalid, key_revoked Error403key_out_of_scope, test_key_live_resource, live_key_test_resource Error404resource_not_found Error409invalid_state_transition, capability_not_orderable Error429rate_limited Error500internal_error Error
GET /v1/events
Events on this account, newest first
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
cursor |
query | string | |
limit |
query | integer (min 1, max 100, default 20) |
Responses
POST /v1/events/replay
Deliver past events again, with the same event ids
Headers
Idempotency-Keyrequired Required on every call that changes something. The result is stored against it and a repeat returns the original response.
Request body
| Field | Type | Notes |
|---|---|---|
since |
integer | |
event |
string |
Responses
GET /v1/api_keys
Keys on this account. Never their secrets.
Responses
POST /v1/test/usage
Drive usage against a simulated resource. Test keys only.
Headers
Idempotency-Keyrequired Required on every call that changes something. The result is stored against it and a repeat returns the original response.
Request body
| Field | Type | Notes |
|---|---|---|
esim required |
string | |
bytes required |
integer (min 1) |
Responses
200The resource after the usage Esim400unsupported_version, missing_parameter, invalid_parameter, idempotency_key_required Error401key_missing, key_invalid, key_revoked Error403key_out_of_scope, live_key_test_resource Error404resource_not_found Error429rate_limited Error500internal_error Error
POST /v1/test/error
Return any documented error deliberately. Test keys only.
Headers
Idempotency-Keyrequired Required on every call that changes something. The result is stored against it and a repeat returns the original response.
Request body
| Field | Type | Notes |
|---|---|---|
code required |
"missing_parameter" or "invalid_parameter" or "unsupported_version" or "idempotency_key_required" or "body_not_json" or "key_missing" or "key_invalid" or "key_revoked" or "key_out_of_scope" or "test_key_live_resource" or "live_key_test_resource" or "verification_required" or "balance_insufficient" or "resource_not_found" or "no_such_route" or "idempotency_key_reused" or "already_exists" or "invalid_state_transition" or "rate_limited" or "capability_not_live" or "capability_not_orderable" or "pricing_unavailable" or "supplier_unavailable" or "supplier_refused" or "internal_error" |
|
param |
string | |
message |
string |
Responses
GET /v1/openapi.json
This specification
Responses
200The specification
Objects
Error
| Field | Type | Notes |
|---|---|---|
error required |
object |
Esim
| Field | Type | Notes |
|---|---|---|
object required |
"esim" |
|
id required |
string | |
iccid required |
string (pattern ^[0-9]{19}$) |
|
state required |
"released" or "installed" or "active" or "suspended" or "expired" |
|
bundle |
string or null | |
data_used_bytes |
integer (min 0) | |
data_limit_bytes |
integer or null | |
activation_code |
string or null | The LPA string, as encoded by the install QR code: LPA:1$<smdp_address>$<matching_id>. On a sandbox profile the host is sandbox.telyne.com and the matching id begins TEST-, so it cannot install on a handset. |
smdp_address |
string or null | |
matching_id |
string or null | |
expires_at |
integer or null | When the bundle runs out, derived from its duration. Null when the bundle is not one with a stated duration. |
created_at required |
integer | |
updated_at |
integer | |
simulated |
boolean | true for a sandbox resource. A live resource reports false. |
Bundle
| Field | Type | Notes |
|---|---|---|
object required |
"bundle" |
|
name required |
string | |
description |
string | |
data_mb |
integer or null | |
unlimited |
boolean | |
duration_days |
integer | |
countries |
array of string (at least 2 characters, at most 2 characters) | |
price_cents required |
integer (min 0) | |
currency required |
"USD" |
|
simulated |
boolean | |
rated |
boolean | false in the sandbox: nothing there is rated or invoiced. |
Event
| Field | Type | Notes |
|---|---|---|
object required |
"event" |
|
id required |
string | |
type required |
"esim.released" or "esim.installed" or "esim.activated" or "esim.suspended" or "esim.expired" or "esim.usage.threshold" or "api_key.issued" or "api_key.first_used" or "api_key.revoked" |
|
time required |
string | |
created_at |
integer | |
data required |
object | |
environment |
"test" or "live" |
Event types
9 event types.
esim.releasedesim.installedesim.activatedesim.suspendedesim.expiredesim.usage.thresholdapi_key.issuedapi_key.first_usedapi_key.revoked
Error codes
25 codes. Every error carries the code, a message, the parameter at fault and a link to its own page.
| Code | Type | HTTP | Page |
|---|---|---|---|
missing_parameter |
invalid_request | 400 | missing_parameter |
invalid_parameter |
invalid_request | 400 | invalid_parameter |
unsupported_version |
invalid_request | 400 | unsupported_version |
idempotency_key_required |
invalid_request | 400 | idempotency_key_required |
body_not_json |
invalid_request | 400 | body_not_json |
key_missing |
authentication | 401 | key_missing |
key_invalid |
authentication | 401 | key_invalid |
key_revoked |
authentication | 401 | key_revoked |
key_out_of_scope |
permission | 403 | key_out_of_scope |
test_key_live_resource |
permission | 403 | test_key_live_resource |
live_key_test_resource |
permission | 403 | live_key_test_resource |
verification_required |
permission | 403 | verification_required |
balance_insufficient |
permission | 402 | balance_insufficient |
resource_not_found |
not_found | 404 | resource_not_found |
no_such_route |
not_found | 404 | no_such_route |
idempotency_key_reused |
conflict | 409 | idempotency_key_reused |
already_exists |
conflict | 409 | already_exists |
invalid_state_transition |
conflict | 409 | invalid_state_transition |
rate_limited |
rate_limit | 429 | rate_limited |
capability_not_live |
capability | 409 | capability_not_live |
capability_not_orderable |
capability | 409 | capability_not_orderable |
pricing_unavailable |
capability | 503 | pricing_unavailable |
supplier_unavailable |
supplier | 503 | supplier_unavailable |
supplier_refused |
supplier | 503 | supplier_refused |
internal_error |
internal | 500 | internal_error |