API Reference

The Axon Networks REST API gives you programmatic access to every platform capability — routes, gateway rules, observability data, and webhooks. Everything you can do in the dashboard, you can automate.

📖 The full OpenAPI 3.1 specification is available at https://api.axon.network/v1/openapi.json and can be imported into any OpenAPI-compatible client (Postman, Insomnia, Bruno, Hoppscotch).

Authentication

All API requests must include a Bearer token in the Authorization header. Tokens are scoped to a project and can be created in your dashboard under Settings → API Tokens.

# Pass your token in every request
curl https://api.axon.network/v1/routes \
  -H "Authorization: Bearer axn_live_k8xm2n9pQr4tYz..." \
  -H "Content-Type: application/json"
  -H "Axon-Project-ID: proj_k8xm2n9p"

Token prefix	Environment	Description
axn_live_	Production	Affects real traffic and billing. Keep secret.
axn_test_	Sandbox	Safe for testing. No real traffic or charges.
axn_ro_	Read-only	Scoped to GET requests only. Safe to share with monitoring tools.

Base URL & Versioning

All API calls use the following base URL. The current stable version is v1.

https://api.axon.network/v1

We use date-based versioning for breaking changes. Version v1 is stable and will not receive breaking changes. New capabilities are added in a backward-compatible way. Deprecated endpoints are announced 90 days in advance via the changelog.

Rate Limits

Plan	Read (GET)	Write (POST/PUT/DELETE)	Burst
Starter	60 req/min	20 req/min	10 req/sec
Growth	600 req/min	120 req/min	60 req/sec
Enterprise	Custom	Custom	Custom

Rate limit status is returned in every response via headers:

X-RateLimit-Limit:     600
X-RateLimit-Remaining: 583
X-RateLimit-Reset:     1716825600
Retry-After:           12  # only on 429 responses

Pagination

List endpoints return cursor-based pagination. Pass cursor from the previous response to get the next page.

# First page (default limit: 20, max: 100)
GET /v1/routes?limit=20

# Next page
GET /v1/routes?limit=20&cursor=cur_4xR8mNpQz

{
  "data":     [ /* array of objects */ ],
  "meta": {
    "count":      20,
    "total":      143,
    "hasMore":    true,
    "nextCursor": "cur_4xR8mNpQz",
    "prevCursor": null
  }
}

Error Handling

The API uses standard HTTP status codes. All errors return a JSON body with a machine-readable code field and a human-readable message.

{
  "error": {
    "code":      "route_not_found",
    "message":   "Route 'route_k8xm2n9p' does not exist or you lack access.",
    "status":    404,
    "requestId": "req_YZmk4xQnRp7tBv2"
  }
}

HTTP Status	Error code	Meaning
400	`invalid_request`	Missing or invalid parameters. Check the `fields` array for details.
401	`unauthenticated`	Missing or invalid API token.
403	`forbidden`	Token lacks permission for this action or resource.
404	`*_not_found`	Resource doesn't exist or isn't accessible with your token.
409	`conflict`	Resource already exists (duplicate name, etc.).
422	`unprocessable`	Request is well-formed but fails business logic validation.
429	`rate_limited`	Rate limit exceeded. See `Retry-After` header.
500	`internal_error`	Something went wrong on our end. We're automatically notified.
503	`unavailable`	Service temporarily unavailable. Retry with exponential backoff.

Routes

Routes define how traffic is distributed across your origins. Each route maps a public endpoint to one or more origin servers with a configurable routing strategy.

GET /v1/routes

List all routes

Returns a paginated list of all routes in the current project, ordered by creation date descending.

Query parameters

Name	Type	Required	Description
limit	integer	optional	Number of results per page. Default: `20`. Max: `100`.
cursor	string	optional	Pagination cursor from previous response.
status	string	optional	Filter by status: `active`, `inactive`, `deploying`.

curl https://api.axon.network/v1/routes \
  -H "Authorization: Bearer axn_live_..."

{
  "data": [
    {
      "id":        "route_k8xm2n9p",
      "name":      "api-prod",
      "endpoint":  "api-prod.axon.network",
      "routing":   "latency",
      "status":    "active",
      "origins":   2,
      "createdAt": "2025-03-12T09:41:00Z",
      "updatedAt": "2025-05-01T14:22:38Z"
    }
  ],
  "meta": { "count": 1, "total": 1, "hasMore": false }
}

POST /v1/routes

Create a route

Creates a new route and begins deploying it to all PoPs. Deployment typically completes in under 15 seconds.

Request body

Field	Type	Required	Description
name	string	required	Unique name within the project. Lowercase, hyphens allowed. Becomes part of your endpoint URL.
routing	string	required	Routing strategy: `latency`, `weighted`, `geo`, `failover`.
origins	array	required	Array of origin objects (min 1, max 20). See origin schema below.
healthCheck	object	optional	Health check configuration. Defaults: path `/`, interval `30s`, threshold `3`.
tls	object	optional	TLS settings. Default: `{ mode: "mutual", minVersion: "TLSv1.3" }`.
tags	object	optional	Key-value tags for filtering and billing allocation.

curl -X POST https://api.axon.network/v1/routes \
  -H "Authorization: Bearer axn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "api-prod",
    "routing": "latency",
    "origins": [
      {
        "id":      "us-east",
        "address": "api.us.internal:8080",
        "region":  "us-east-1",
        "weight":  60
      },
      {
        "id":      "eu-west",
        "address": "api.eu.internal:8080",
        "region":  "eu-west-1",
        "weight":  40
      }
    ],
    "healthCheck": {
      "path":      "/health",
      "interval":  10,
      "threshold": 2
    }
  }'

{
  "data": {
    "id":          "route_k8xm2n9p",
    "name":        "api-prod",
    "endpoint":    "api-prod.axon.network",
    "status":      "deploying",
    "routing":     "latency",
    "origins":     [ /* ... */ ],
    "deploymentId":"dep_9mPz3kQx",
    "createdAt":   "2025-05-16T10:00:00Z"
  }
}

GET /v1/routes/{route_id}

Get a route

Returns the full configuration and current status of a single route, including per-origin health check results and deployment status.

curl https://api.axon.network/v1/routes/route_k8xm2n9p \
  -H "Authorization: Bearer axn_live_..."

PUT /v1/routes/{route_id}

Update a route

Replaces the entire route configuration. This triggers a zero-downtime redeployment across all PoPs. Use PATCH for partial updates.

⚠️PUT replaces the entire resource. Omitting a field will reset it to its default. Use PATCH /v1/routes/{id} to update individual fields.

DELETE /v1/routes/{route_id}

Delete a route

Permanently deletes a route and removes it from all PoPs. Traffic to the route's endpoint will immediately return 404. This action cannot be undone.

curl -X DELETE https://api.axon.network/v1/routes/route_k8xm2n9p \
  -H "Authorization: Bearer axn_live_..."

# Returns 204 No Content on success

Gateway Rules

Gateway rules define authentication, rate limiting, and transformation logic applied at the edge before traffic reaches your origin.

GET/v1/gateway/rules

List gateway rules

Returns all gateway rules associated with the current project, ordered by priority.

curl https://api.axon.network/v1/gateway/rules \
  -H "Authorization: Bearer axn_live_..."

POST/v1/gateway/rules

Create a gateway rule

Adds a new rule to the gateway. Rules are evaluated in priority order (lowest number first).

curl -X POST https://api.axon.network/v1/gateway/rules \
  -H "Authorization: Bearer axn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":     "api-jwt-auth",
    "path":     "/api/v1/**",
    "priority": 10,
    "auth": {
      "type":   "jwt",
      "issuer": "https://auth.yourapp.com",
      "audience": "axon-api"
    },
    "rateLimit": {
      "requests": 1000,
      "window":   "1m",
      "keyBy":    "jwt.sub"
    }
  }'

Observe — Metrics & Logs

Query your infrastructure metrics, logs, and distributed traces programmatically. The Observe API is compatible with Prometheus query syntax for metrics.

GET/v1/metrics/query

Instant metric query

Evaluates a PromQL-compatible metric query at a single point in time.

Parameter	Type	Required	Description
query	string	required	PromQL-compatible expression. Example: `axon_request_rate{route="api-prod"}`
time	unix timestamp	optional	Evaluation time. Default: now.

curl "https://api.axon.network/v1/metrics/query?\
query=axon_latency_p99_ms%7Broute%3D%22api-prod%22%7D" \
  -H "Authorization: Bearer axn_live_..."

GET/v1/logs

Query logs

Full-text and structured search across all edge node logs. Supports LogQL-compatible filter expressions.

Parameter	Type	Required	Description
query	string	required	LogQL expression. Example: `{route="api-prod"} \|= "error"`
start	unix timestamp	required	Start of time range.
end	unix timestamp	required	End of time range. Max range: 24h.
limit	integer	optional	Max log lines to return. Default 100, max 5000.
direction	string	optional	`forward` (oldest first) or `backward` (newest first). Default: `backward`.

GET/v1/traces/{trace_id}

Get a distributed trace

Returns the complete span tree for a given trace ID, including timing data, tags, and log attachments for every span.

curl https://api.axon.network/v1/traces/4bf92f3577b34da6 \
  -H "Authorization: Bearer axn_live_..."

Webhooks

Webhooks notify your systems of platform events in real time. We deliver a signed POST request to your endpoint within 5 seconds of each event. Failed deliveries are retried up to 5 times with exponential backoff.

POST/v1/webhooks

Create a webhook

curl -X POST https://api.axon.network/v1/webhooks \
  -H "Authorization: Bearer axn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://hooks.yourapp.com/axon",
    "events": ["route.deployed", "route.failed", "origin.unhealthy"],
    "secret": "whsec_your_signing_secret"
  }'

Event types

Event	Triggered when
route.deployed	A route finishes deploying to all PoPs.
route.failed	A route deployment fails.
route.deleted	A route is deleted.
origin.unhealthy	An origin fails its health check.
origin.recovered	An unhealthy origin passes its health check.
gateway.rule.created	A gateway rule is created.
slo.breach	An SLO error budget drops below 10%.
alert.fired	An Observe alert fires.
alert.resolved	A previously fired alert resolves.

All webhook payloads are signed with HMAC-SHA256 using your secret. Verify the signature using the Axon-Signature header before processing:

import { createHmac } from 'crypto';

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}
// const sig = req.headers['axon-signature'];
// verifyWebhook(rawBody, sig, process.env.AXON_WEBHOOK_SECRET)

System & Regions

Utility endpoints for querying live system status and available edge regions. These endpoints do not require authentication.

GET/v1/status

System status

Returns current operational status of all platform components. Equivalent to the status page in machine-readable form.

curl https://api.axon.network/v1/status  # no auth required

{
  "status":      "operational",
  "updatedAt":   "2025-05-16T10:00:00Z",
  "components": [
    { "id": "fabric-core", "status": "operational", "uptime30d": 99.998 },
    { "id": "gateway",     "status": "operational", "uptime30d": 99.997 }
  ]
}

GET/v1/regions

List regions

Returns all available edge regions with their current status and latency measurements.

curl https://api.axon.network/v1/regions  # no auth required

← Back to Docs

Report an issue Get API access