FreeTransit

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

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:

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:

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.