FreeTransit API · experimental
Customer API
A read-only JSON API for the BGP sessions, tunnels, prefix filters and routing-policy checks of your FreeTransit account, for your own monitoring, dashboards and automation.
Experimental. Version 1 was introduced in release 0.10.0 for testing and extended in 0.10.4. Fields and endpoints may still change without notice. Do not build anything critical on it yet, and tell us at support@freetransit.ch what you use and what you are missing.
Authentication
Sign in to the portal, open API and metrics and create a token with Also allow read access to the experimental API ticked. The token is shown once. Send it as a bearer token:
curl -H "Authorization: Bearer ftm_..." https://freetransit.net/api/v1/account
A token belongs to one account and only returns that account's data. The same token also works for the Prometheus /metrics endpoint. Tokens created without API access receive 403 api_access_disabled; create a new token instead of reusing a metrics-only one. Revoke tokens you no longer use.
Requests and responses
- Base URL:
https://freetransit.net/api/v1. All endpoints areGETand return JSON. - Successful responses have the form
{"data": ..., "meta": {...}}.meta.statusisexperimental, and every response carries the headerX-FreeTransit-API-Status: experimental. - Errors have the form
{"error": {"code": "...", "message": "..."}}with status 400 (invalid_parameter, a malformed filter), 401 (missing or invalid token), 403 (token without API access), 404 (not found in your account) or 429 (rate limit). - Times are UTC in ISO 8601. Values that have not been reported yet are
null. - Limit: 120 requests per minute. Telemetry is reported by the routers about every five minutes, so polling more often than once a minute gains nothing.
Endpoints
GET /api/v1/account
The account the token belongs to: id, name, the ASNs with current sessions, and the token's name and last four characters.
GET /api/v1/bgp_sessions
All current BGP sessions of the account. Each entry contains:
id,protocol(the session name on our router),asn,address_family(4 or 6),relationship,access_type,node,tunnel_idneighbor_ip(your side) andlocal_ip(our side)state(provisioning state),live_state(the BGP state reported by the router),up,live_since,last_status_at,max_prefixesroutes:received,acceptedandfilteredcounts withreported_at
Optional filters, which can be combined: asn (64500 or AS64500), address_family (4 or 6), node (a node name from /api/v1/nodes) and up (true or false). For example, /api/v1/bgp_sessions?up=false lists every session that is not established right now.
GET /api/v1/bgp_sessions/:id
One session with the same fields, plus routes.accepted (prefix and origin of each accepted announcement) and routes.rejected. Each rejected route lists the observed RPKI state, the reasons it was rejected and what you can do about it, the same guidance as the looking glass in the portal. accepted_truncated and rejected_truncated are true when the router reported more routes than we store.
GET /api/v1/tunnels
All current tunnels of the account:
id,interface,node,encapsulation,state,health,mtucustomer_endpoint_ip(your side) andfreetransit_endpoint_ip(our side),subnetsandbgp_session_idstraffic: interface byte counters on our node and the recent rate in bits per second.rxis traffic received from you,txis traffic sent to you.probe: whether your tunnel endpoint answered our latest probe, its median latency in milliseconds and the packet loss in percent
Optional filters: node and health (one of healthy, degraded, bgp_down, interface_down, missing, telemetry_stale, telemetry_unknown, no_bgp).
GET /api/v1/tunnels/:id
One tunnel with the same fields.
GET /api/v1/prefix_filters
The prefix lists our routers use to filter your announcements, one entry per ASN and address family of your filtered sessions. We build them from the route and route6 objects of your ASN in the IRR databases and refresh them every four hours. Each entry has asn, address_family, status, generated_at, prefix_count and prefixes.
status is current, refresh_failed (the last refresh failed; the routers keep using the prefixes shown) or not_built (no list yet). If a prefix you announce is missing here, create a route or route6 object for it and wait for the next refresh. Optional filters: asn and address_family.
GET /api/v1/policy_checks
The latest result of each routing-policy check for your ASNs: aut_num_direct_policy (your aut-num object imports from and exports to AS41051), aspa_provider_authorization (your ASPA object lists AS41051 as a provider) and peeringdb_route_server_policy. Each entry has asn, check, status (passed, failed, missing or unknown after a temporary lookup error), message, checked_at, next_check_after, source_url and details with what we found, such as the ASPA providers. These are the checks described in the portal manual. Optional filter: asn.
GET /api/v1/nodes
FreeTransit locations: every active node and any node your sessions use. Each entry has name, location, state, accepting_orders, wireguard_orders (new WireGuard tunnels can be ordered there), rpki_validation, endpoint_ipv4, endpoint_ipv6, online (the node reported to us within the last ten minutes) and last_check_in_at.
Example
$ curl -s -H "Authorization: Bearer $FREETRANSIT_TOKEN" https://freetransit.net/api/v1/bgp_sessions
{
"data": [
{
"id": 42,
"protocol": "pb_0042",
"asn": "AS64500",
"address_family": 6,
"node": "ftr-ams",
"live_state": "up",
"up": true,
"routes": { "received": 2, "accepted": 2, "filtered": 0, "reported_at": "2026-10-30T18:05:12Z" },
...
}
],
"meta": { "api_version": "v1", "status": "experimental", ... }
}
Not included yet
Version 1 is read-only. Changes such as requesting sessions, changing a tunnel endpoint or triggering a blackhole are still done in the portal or by ticket, and notifications go out by email as before. If one of these would help you, let us know.