Traxo API Reference

The Traxo REST API lets you programmatically manage AI/LLM monitoring, cost tracking, token analytics, uptime monitors, incidents, status pages, alert channels, and maintenance windows.

Secure by Default

Bearer token authentication on every request.

RESTful Design

Predictable resource-oriented URLs and standard HTTP methods.

JSON Responses

All responses are wrapped in a { data } envelope.

Base URL

text

https://api.traxo.dev

Response Envelope

All successful responses wrap the result in a data property. List endpoints may include a pagination object.

json

{
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 120,
    "totalPages": 3
  }
}

Authentication

Authenticate every API request by including your API key in the Authorization header as a Bearer token.

API keys can be created from the Settings page in the Traxo dashboard. Keys use the traxo_ prefix format.

bash

curl https://api.traxo.dev/api/monitors \
  -H "Authorization: Bearer traxo_abc123def456..."
  -H "Content-Type: application/json"

Keep your API keys safe

Your API key carries the same privileges as your user account. Do not share it in publicly accessible areas such as GitHub, client-side code, or public repositories.

Rate Limits

The API enforces rate limits to ensure fair usage and service stability. Limits vary by plan:

Plan	Price	Rate Limit	Monitors	Min Interval
Free	$0/mo	60 req/min	5	5 min
Pro	$29/mo	300 req/min	50	1 min
Business	$79/mo	1,000 req/min	200	30 sec
Enterprise	Custom	5,000 req/min	Unlimited	15 sec

When you exceed the rate limit, the API responds with 429 Too Many Requests. The Retry-After header indicates how many seconds to wait.

Need higher limits? Sign up or upgrade your plan.

Errors

The API uses conventional HTTP status codes. Errors return a JSON body with an error field.

json

{
  "error": "Monitor not found"
}

Status	Meaning
`400`	Bad Request -- Invalid parameters or validation failed.
`401`	Unauthorized -- Missing or invalid API key.
`403`	Forbidden -- Plan limit reached or insufficient permissions.
`404`	Not Found -- Resource does not exist.
`409`	Conflict -- Resource already exists (e.g. duplicate slug).
`429`	Too Many Requests -- Rate limit exceeded.
`500`	Internal Server Error -- Something went wrong on our end.

AI Monitoring

Track LLM usage, costs, and performance for AI-powered applications. Create an LLM-type monitor, then use the @traxodev/ai SDK or the ingest API to report events.

POST/api/ai/ingest/:monitorId

Ingest an AI event for an LLM monitor. No authentication required — the monitor ID acts as the routing key. Supports CORS for client-side reporting.

Request Body

Parameter	Type	Required	Description
`provider`	string	Required	LLM provider name (e.g. "openai", "anthropic").
`model`	string	Required	Model identifier (e.g. "gpt-4o", "claude-sonnet-4-20250514").
`promptTokens`	number	Required	Input token count.
`completionTokens`	number	Required	Output token count.
`latencyMs`	number	Required	Total request latency in milliseconds.
`totalTokens`	number	Optional	Total token count. Defaults to promptTokens + completionTokens.
`statusCode`	number	Optional	HTTP status code from the LLM provider.
`error`	string	Optional	Error message if the request failed.
`promptHash`	string	Optional	Hash of the prompt for deduplication / caching detection.
`metadata`	object	Optional	Arbitrary metadata key-value pairs.
`ragDocsRetrieved`	number	Optional	Number of RAG documents retrieved.
`ragAvgRelevance`	number	Optional	Average relevance score (0-1) of retrieved documents.
`ragRetrievalMs`	number	Optional	RAG retrieval latency in milliseconds.
`ragContextTokens`	number	Optional	Token count of the RAG context injected into the prompt.

bash

curl -X POST https://api.traxo.dev/api/ai/ingest/mon_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o",
    "promptTokens": 150,
    "completionTokens": 80,
    "latencyMs": 1200
  }'

Response

json

{
  "data": {
    "id": "evt_abc123",
    "costUsd": 0.0035,
    "dailyEventsUsed": 42,
    "dailyEventsLimit": 10000
  }
}

GET/api/monitors/:id/ai-usage

Get aggregated AI usage statistics for an LLM monitor, including total events, costs, latency percentiles, top models, and RAG performance.

Query Parameters

Parameter	Type	Required	Description
`period`	string	Optional	Time period: "24h", "7d", or "30d". Defaults to "24h".

bash

curl https://api.traxo.dev/api/monitors/mon_abc123/ai-usage?period=7d \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "totalEvents": 1250,
    "totalTokens": 850000,
    "totalCost": 12.45,
    "avgLatency": 890,
    "p95Latency": 2100,
    "errorRate": 1.2,
    "topModels": [
      { "model": "gpt-4o", "count": 800, "totalCost": 9.60, "avgLatency": 920 },
      { "model": "gpt-4o-mini", "count": 450, "totalCost": 2.85, "avgLatency": 340 }
    ],
    "hourlyUsage": [
      { "hour": "2026-03-13T00:00:00Z", "events": 52, "tokens": 35000, "cost": 0.52 }
    ],
    "ragStats": {
      "totalRagEvents": 320,
      "avgRelevance": 0.82,
      "avgDocsRetrieved": 4.2,
      "avgRetrievalMs": 120
    }
  }
}

GET/api/monitors/:id/ai-events

Get paginated AI event history for an LLM monitor.

Query Parameters

Parameter	Type	Required	Description
`page`	number	Optional	Page number. Defaults to 1.
`limit`	number	Optional	Items per page. Defaults to 20.

bash

curl https://api.traxo.dev/api/monitors/mon_abc123/ai-events?page=1&limit=20 \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "evt_001",
      "monitorId": "mon_abc123",
      "provider": "openai",
      "model": "gpt-4o",
      "inputTokens": 150,
      "outputTokens": 80,
      "totalTokens": 230,
      "costUsd": 0.0035,
      "latencyMs": 1200,
      "status": "success",
      "errorMessage": null,
      "createdAt": "2026-03-13T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1250,
    "totalPages": 63
  }
}

GET/api/monitors/:id/insights

Get optimization insights and anti-pattern detections for an LLM monitor. Insights are generated by the worker based on usage patterns.

bash

curl https://api.traxo.dev/api/monitors/mon_abc123/insights \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "ins_001",
      "monitorId": "mon_abc123",
      "type": "model_downgrade",
      "severity": "warning",
      "title": "Consider using gpt-4o-mini",
      "description": "72% of your requests use fewer than 500 tokens. A smaller model could reduce costs.",
      "savings": 4.50,
      "metadata": {
        "recommendation": "Switch short prompts to gpt-4o-mini to save ~$4.50/day."
      },
      "dismissed": false,
      "createdAt": "2026-03-12T14:00:00Z"
    }
  ]
}

GET/api/monitors/:id/cost-alert

Get the cost alert configuration for an LLM monitor.

bash

curl https://api.traxo.dev/api/monitors/mon_abc123/cost-alert \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "id": "ca_001",
    "monitorId": "mon_abc123",
    "dailyBudgetUsd": 10.00,
    "monthlyBudgetUsd": 200.00,
    "alertEmails": "alice@example.com, bob@example.com",
    "lastDailyAlert": null,
    "lastMonthlyAlert": null
  }
}

PUT/api/monitors/:id/cost-alert

Create or update the cost alert for an LLM monitor. At least one budget (daily or monthly) must be set.

Request Body

Parameter	Type	Required	Description
`dailyBudget`	number \| null	Optional	Daily budget in USD. Set to null to disable daily alerts.
`monthlyBudget`	number \| null	Optional	Monthly budget in USD. Set to null to disable monthly alerts.
`alertEmails`	string	Required	Comma-separated list of email addresses to notify.

bash

curl -X PUT https://api.traxo.dev/api/monitors/mon_abc123/cost-alert \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyBudget": 10.00,
    "monthlyBudget": 200.00,
    "alertEmails": "alice@example.com"
  }'

Response

json

{
  "data": {
    "id": "ca_001",
    "monitorId": "mon_abc123",
    "dailyBudgetUsd": 10.00,
    "monthlyBudgetUsd": 200.00,
    "alertEmails": "alice@example.com"
  }
}

DELETE/api/monitors/:id/cost-alert

Delete the cost alert configuration for an LLM monitor.

bash

curl -X DELETE https://api.traxo.dev/api/monitors/mon_abc123/cost-alert \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "deleted": true
  }
}

Monitors

Monitors define the endpoints Traxo checks on a recurring schedule. Each monitor has a type (HTTP, TCP, PING, DNS, SSL, HEARTBEAT, BROWSER, LLM), a check interval, and one or more target regions. The BROWSER type requires a BUSINESS or ENTERPRISE plan.

GET/api/monitors

Retrieve all monitors for the authenticated organization, ordered by creation date (newest first). Each monitor includes its most recent check result.

bash

curl https://api.traxo.dev/api/monitors \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "cm1abc123",
      "name": "Production API",
      "url": "https://api.example.com/health",
      "type": "HTTP",
      "interval": 60,
      "isActive": true,
      "method": "GET",
      "timeout": 30,
      "regions": ["us-east-1"],
      "createdAt": "2025-06-15T10:30:00.000Z",
      "lastCheck": {
        "status": "UP",
        "responseTime": 142,
        "checkedAt": "2025-06-15T12:00:00.000Z"
      }
    }
  ]
}

POST/api/monitors

Create a new uptime monitor. Subject to plan limits on monitor count.

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Display name (max 100 chars).
`url`	string	Required	Valid URL to monitor.
`type`	string	Required	One of: HTTP, TCP, PING, DNS, SSL, HEARTBEAT, BROWSER. BROWSER requires BUSINESS or ENTERPRISE plan.
`interval`	number	Optional	Check interval in seconds (30-3600). Default: 60.
`method`	string	Optional	HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Default: GET.
`expectedStatus`	number	Optional	Expected HTTP status code (100-599).
`expectedKeyword`	string	Optional	Keyword to search for in response body (max 500 chars).
`timeout`	number	Optional	Timeout in seconds (1-60). Default: 30.
`regions`	string[]	Optional	Regions to check from. Default: ["us-east-1"].
`config`	object	Optional	Advanced configuration (HTTP method, headers, body, assertions). See below.

Config Object (Optional)

The config field allows advanced HTTP monitor configuration including custom headers, request bodies, and response assertions.

json

{
  "method": "POST",
  "headers": { "Authorization": "Bearer token" },
  "body": "{\"key\": \"value\"}",
  "assertions": [
    { "type": "status_code", "operator": "equals", "value": "200" },
    { "type": "response_time", "operator": "less_than", "value": "500" },
    { "type": "json_path", "path": "$.data.status", "operator": "equals", "value": "ok" },
    { "type": "header", "name": "content-type", "operator": "contains", "value": "json" }
  ]
}

Assertion Types

Type	Description	Operators
`status_code`	HTTP response status code	equals, not_equals, greater_than, less_than
`response_time`	Response time in milliseconds	less_than, greater_than
`json_path`	Value at a JSON path (e.g. $.data.status)	equals, not_equals, contains
`header`	Response header value (specify name field)	equals, not_equals, contains

bash

curl -X POST https://api.traxo.dev/api/monitors \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "url": "https://api.example.com/health",
    "type": "HTTP",
    "interval": 60,
    "method": "GET",
    "expectedStatus": 200,
    "timeout": 10,
    "regions": ["us-east-1", "eu-west-1"]
  }'

Response (201 Created)

json

{
  "data": {
    "id": "cm1abc123",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "type": "HTTP",
    "interval": 60,
    "isActive": true,
    "method": "GET",
    "expectedStatus": 200,
    "expectedKeyword": null,
    "timeout": 10,
    "regions": ["us-east-1", "eu-west-1"],
    "orgId": "org_xxx",
    "createdAt": "2025-06-15T10:30:00.000Z",
    "updatedAt": "2025-06-15T10:30:00.000Z"
  }
}

GET/api/monitors/:id

Get a single monitor with its last 50 check results and 10 most recent incidents.

bash

curl https://api.traxo.dev/api/monitors/cm1abc123 \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "id": "cm1abc123",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "type": "HTTP",
    "interval": 60,
    "isActive": true,
    "method": "GET",
    "expectedStatus": 200,
    "expectedKeyword": null,
    "timeout": 10,
    "regions": ["us-east-1"],
    "createdAt": "2025-06-15T10:30:00.000Z",
    "checks": [
      {
        "id": "chk_001",
        "status": "UP",
        "responseTime": 142,
        "statusCode": 200,
        "region": "us-east-1",
        "checkedAt": "2025-06-15T12:00:00.000Z"
      }
    ],
    "incidents": [
      {
        "id": "inc_001",
        "startedAt": "2025-06-14T08:00:00.000Z",
        "resolvedAt": "2025-06-14T08:15:00.000Z",
        "duration": 900,
        "cause": "Connection timeout"
      }
    ]
  }
}

PUT/api/monitors/:id

Update an existing monitor. All fields are optional -- only provided fields are updated.

Request Body

Parameter	Type	Required	Description
`name`	string	Optional	Display name (max 100 chars).
`url`	string	Optional	Valid URL to monitor.
`type`	string	Optional	One of: HTTP, TCP, PING, DNS, SSL, HEARTBEAT, BROWSER. BROWSER requires BUSINESS or ENTERPRISE plan.
`interval`	number	Optional	Check interval in seconds (30-3600).
`method`	string	Optional	HTTP method.
`expectedStatus`	number	Optional	Expected HTTP status code.
`expectedKeyword`	string	Optional	Keyword in response body.
`timeout`	number	Optional	Timeout in seconds (1-60).
`regions`	string[]	Optional	Regions to check from.
`config`	object	Optional	Advanced configuration (HTTP method, headers, body, assertions).

bash

curl -X PUT https://api.traxo.dev/api/monitors/cm1abc123 \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API (Updated)",
    "interval": 30
  }'

Response

json

{
  "data": {
    "id": "cm1abc123",
    "name": "Production API (Updated)",
    "url": "https://api.example.com/health",
    "type": "HTTP",
    "interval": 30,
    "isActive": true,
    "method": "GET",
    "timeout": 10,
    "regions": ["us-east-1"],
    "createdAt": "2025-06-15T10:30:00.000Z",
    "updatedAt": "2025-06-15T13:00:00.000Z"
  }
}

DELETE/api/monitors/:id

Permanently delete a monitor and all associated check results and incidents.

bash

curl -X DELETE https://api.traxo.dev/api/monitors/cm1abc123 \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "message": "Monitor deleted successfully"
}

POST/api/monitors/:id/pause

Pause a monitor. Checks will stop running until the monitor is resumed.

bash

curl -X POST https://api.traxo.dev/api/monitors/cm1abc123/pause \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "id": "cm1abc123",
    "name": "Production API",
    "isActive": false,
    ...
  },
  "message": "Monitor paused"
}

POST/api/monitors/:id/resume

Resume a paused monitor. Checks will begin running again on the configured interval.

bash

curl -X POST https://api.traxo.dev/api/monitors/cm1abc123/resume \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "id": "cm1abc123",
    "name": "Production API",
    "isActive": true,
    ...
  },
  "message": "Monitor resumed"
}

GET/api/monitors/:id/performance

Retrieve performance timing data for an HTTP monitor. Returns averages, p95 values, and time series data for DNS, TCP, TLS, TTFB, download, and total response times.

Query Parameters

Parameter	Type	Required	Description
`hours`	number	Optional	Time range in hours (1-168). Default: 24.

bash

curl "https://api.traxo.dev/api/monitors/cm1abc123/performance?hours=24" \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "averages": {
      "dns": 12.5,
      "tcp": 8.3,
      "tls": 22.1,
      "ttfb": 45.7,
      "download": 5.2,
      "total": 93.8,
      "size": 2048
    },
    "p95": {
      "dns": 28.0,
      "tcp": 15.6,
      "tls": 48.3,
      "ttfb": 112.4,
      "download": 12.8,
      "total": 217.1
    },
    "timeSeries": [
      {
        "timestamp": "2025-06-15T10:00:00.000Z",
        "dns": 11.2,
        "tcp": 7.8,
        "tls": 20.5,
        "ttfb": 42.3,
        "download": 4.9,
        "total": 86.7,
        "size": 2048
      }
    ],
    "sampleCount": 1440
  }
}

GET/api/monitors/:id/checks

Retrieve paginated check results for a monitor with optional date range filtering.

Query Parameters

Parameter	Type	Required	Description
`page`	number	Optional	Page number (default: 1).
`limit`	number	Optional	Items per page, 1-100 (default: 50).
`from`	string	Optional	ISO 8601 start date filter.
`to`	string	Optional	ISO 8601 end date filter.

bash

curl "https://api.traxo.dev/api/monitors/cm1abc123/checks?page=1&limit=20&from=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "chk_001",
      "monitorId": "cm1abc123",
      "status": "UP",
      "responseTime": 142,
      "statusCode": 200,
      "region": "us-east-1",
      "checkedAt": "2025-06-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 500,
    "totalPages": 25
  }
}

GET/api/monitors/:id/incidents

List all incidents for a specific monitor, ordered by start time (newest first).

bash

curl https://api.traxo.dev/api/monitors/cm1abc123/incidents \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "inc_001",
      "monitorId": "cm1abc123",
      "monitorName": "Production API",
      "startedAt": "2025-06-14T08:00:00.000Z",
      "resolvedAt": "2025-06-14T08:15:00.000Z",
      "duration": 900,
      "cause": "Connection timeout",
      "isActive": false
    }
  ]
}

Heartbeat

Heartbeat monitoring works in reverse: instead of Traxo polling your service, your service sends periodic pings to Traxo. If no ping is received within the configured grace period, an alert is triggered. This is ideal for cron jobs, background tasks, and scheduled processes.

GET/api/heartbeat/:token

Send a heartbeat ping. Accepts both GET and POST requests. This endpoint is public and does not require authentication — the unique token in the URL acts as the identifier.

No authentication required

The heartbeat token is generated when you create a HEARTBEAT monitor. Use it directly in the URL path. No Authorization header is needed.

GET Example

bash

curl https://api.traxo.dev/api/heartbeat/hb_abc123def456

POST Example

bash

curl -X POST https://api.traxo.dev/api/heartbeat/hb_abc123def456

Response

json

{
  "ok": true
}

Incidents

Incidents are automatically created when a monitor detects downtime (2 consecutive failures) and resolved when the monitor recovers.

GET/api/incidents

List all incidents for the organization with pagination and optional filters.

Query Parameters

Parameter	Type	Required	Description
`status`	string	Optional	Filter by status: "active" or "resolved". Omit for all.
`monitorId`	string	Optional	Filter by monitor ID.
`page`	number	Optional	Page number (default: 1).
`limit`	number	Optional	Items per page, 1-100 (default: 50).

bash

curl "https://api.traxo.dev/api/incidents?status=active&page=1&limit=20" \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "inc_001",
      "monitorId": "cm1abc123",
      "monitorName": "Production API",
      "monitorUrl": "https://api.example.com/health",
      "startedAt": "2025-06-14T08:00:00.000Z",
      "resolvedAt": null,
      "duration": null,
      "cause": "Connection timeout",
      "isActive": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Status Pages

Status pages provide a public-facing dashboard showing the health of your services. Each page is identified by a unique slug and includes one or more monitor components.

GET/api/status-pages

List all status pages for the authenticated organization, including their components.

bash

curl https://api.traxo.dev/api/status-pages \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "sp_001",
      "name": "Acme Status",
      "slug": "acme-status",
      "customDomain": null,
      "isPublic": true,
      "orgId": "org_xxx",
      "createdAt": "2025-06-10T09:00:00.000Z",
      "components": [
        {
          "id": "spc_001",
          "displayName": "Production API",
          "order": 0,
          "monitor": {
            "id": "cm1abc123",
            "name": "Production API",
            "url": "https://api.example.com/health"
          }
        }
      ]
    }
  ]
}

POST/api/status-pages

Create a new status page. The slug must be unique across all organizations.

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Page name (max 100 chars).
`slug`	string	Required	URL slug (lowercase, numbers, hyphens only; max 50 chars).
`description`	string	Optional	Page description (max 500 chars).
`customDomain`	string	Optional	Custom domain (e.g. status.example.com).
`monitors`	string[]	Required	Array of monitor IDs to include as components.
`hideBranding`	boolean	Optional	Hide "Powered by Traxo" footer. Requires BUSINESS or ENTERPRISE plan.
`customCss`	string	Optional	Custom CSS for the status page. Requires BUSINESS or ENTERPRISE plan.
`faviconUrl`	string	Optional	Custom favicon URL.

bash

curl -X POST https://api.traxo.dev/api/status-pages \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Status",
    "slug": "acme-status",
    "monitors": ["cm1abc123", "cm2def456"]
  }'

Response (201 Created)

json

{
  "data": {
    "id": "sp_001",
    "name": "Acme Status",
    "slug": "acme-status",
    "customDomain": null,
    "isPublic": true,
    "orgId": "org_xxx",
    "createdAt": "2025-06-10T09:00:00.000Z",
    "components": [
      {
        "id": "spc_001",
        "monitorId": "cm1abc123",
        "displayName": "Production API",
        "order": 0
      }
    ]
  }
}

GET/api/status-pages/:slug

Get a public status page by slug. Returns overall status, component health, and active incidents. This endpoint does not require authentication when the page is public.

bash

curl https://api.traxo.dev/api/status-pages/acme-status

Response

json

{
  "data": {
    "name": "Acme Status",
    "slug": "acme-status",
    "logoUrl": null,
    "overallStatus": "operational",
    "components": [
      {
        "name": "Production API",
        "status": "operational",
        "uptime90d": 99.98
      },
      {
        "name": "Web App",
        "status": "degraded",
        "uptime90d": 99.2
      }
    ],
    "activeIncidents": []
  }
}

PUT/api/status-pages/:slug

Update a status page. All fields are optional. If monitors are provided, the component list is replaced entirely.

Request Body

Parameter	Type	Required	Description
`name`	string	Optional	Page name.
`slug`	string	Optional	URL slug (must be unique).
`description`	string	Optional	Page description.
`customDomain`	string	Optional	Custom domain.
`monitors`	string[]	Optional	Replaces the entire component list.
`hideBranding`	boolean	Optional	Hide "Powered by Traxo" footer. Requires BUSINESS or ENTERPRISE plan.
`customCss`	string	Optional	Custom CSS for the status page. Requires BUSINESS or ENTERPRISE plan.
`faviconUrl`	string	Optional	Custom favicon URL.

bash

curl -X PUT https://api.traxo.dev/api/status-pages/acme-status \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Status (Updated)"
  }'

Response

json

{
  "data": {
    "id": "sp_001",
    "name": "Acme Status (Updated)",
    "slug": "acme-status",
    "customDomain": null,
    "isPublic": true,
    "components": [ ... ]
  }
}

DELETE/api/status-pages/:slug

Delete a status page and all associated components.

bash

curl -X DELETE https://api.traxo.dev/api/status-pages/acme-status \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "message": "Status page deleted successfully"
}

Domain Verification

Custom domains require DNS verification. Use these endpoints to initiate verification and check its status.

POST/api/status-pages/:slug/verify-domain

Initiate domain verification. Returns a verification token and DNS TXT record instructions.

bash

curl -X POST https://api.traxo.dev/api/status-pages/acme-status/verify-domain \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "verificationToken": "traxo-verify=abc123def456",
    "instructions": {
      "type": "TXT",
      "host": "_traxo-verification.status.example.com",
      "value": "traxo-verify=abc123def456",
      "ttl": 300
    }
  }
}

GET/api/status-pages/:slug/verify-domain

Check domain verification status. If the DNS TXT record is found, the domain is marked as verified.

bash

curl https://api.traxo.dev/api/status-pages/acme-status/verify-domain \
  -H "Authorization: Bearer traxo_xxx"

Response (verified)

json

{
  "data": {
    "domainVerified": true,
    "customDomain": "status.example.com",
    "verifiedAt": "2025-06-15T14:00:00.000Z"
  }
}

Response (not yet verified)

json

{
  "data": {
    "domainVerified": false,
    "customDomain": "status.example.com",
    "verifiedAt": null
  }
}

Alert Channels

Alert channels define where notifications are sent when a monitor goes down or recovers. Supported types: Email, Slack, Webhook, and PagerDuty.

GET/api/alert-channels

List all alert channels for the organization.

bash

curl https://api.traxo.dev/api/alert-channels \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "ac_001",
      "name": "Engineering Slack",
      "type": "SLACK",
      "config": {
        "webhookUrl": "https://hooks.slack.com/services/xxx"
      },
      "isActive": true,
      "orgId": "org_xxx",
      "createdAt": "2025-06-10T09:00:00.000Z"
    }
  ]
}

POST/api/alert-channels

Create a new alert channel. The config object structure depends on the channel type.

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Channel name (max 100 chars).
`type`	string	Required	One of: EMAIL, SLACK, WEBHOOK, PAGERDUTY.
`config`	object	Required	Channel-specific configuration (see examples below).
`enabled`	boolean	Optional	Whether the channel is active. Default: true.

Config Examples by Type

{ "recipients": ["ops@example.com"] }

SLACK

{ "webhookUrl": "https://hooks.slack.com/..." }

WEBHOOK

{ "url": "https://example.com/webhook", "secret": "..." }

PAGERDUTY

{ "routingKey": "xxx" }

bash

curl -X POST https://api.traxo.dev/api/alert-channels \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Slack",
    "type": "SLACK",
    "config": {
      "webhookUrl": "https://hooks.slack.com/services/xxx"
    }
  }'

Response (201 Created)

json

{
  "data": {
    "id": "ac_001",
    "name": "Engineering Slack",
    "type": "SLACK",
    "config": {
      "webhookUrl": "https://hooks.slack.com/services/xxx"
    },
    "isActive": true,
    "orgId": "org_xxx",
    "createdAt": "2025-06-10T09:00:00.000Z"
  }
}

DELETE/api/alert-channels/:id

Delete an alert channel. Any monitors using this channel will no longer send alerts to it.

bash

curl -X DELETE https://api.traxo.dev/api/alert-channels/ac_001 \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "message": "Alert channel deleted successfully"
}

Maintenance Windows

Maintenance windows suppress alerts for a monitor during scheduled downtime. They can optionally be tied to a specific monitor, or applied organization-wide.

GET/api/maintenance

List all maintenance windows, with optional filtering by status.

Query Parameters

Parameter	Type	Required	Description
`filter`	string	Optional	One of: "active", "upcoming", "past". Omit for all.

bash

curl "https://api.traxo.dev/api/maintenance?filter=active" \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "mw_001",
      "title": "Database upgrade",
      "description": "Upgrading PostgreSQL to v16",
      "monitorId": "cm1abc123",
      "monitorName": "Production API",
      "startsAt": "2025-06-20T02:00:00.000Z",
      "endsAt": "2025-06-20T04:00:00.000Z",
      "isActive": true
    }
  ]
}

POST/api/maintenance

Schedule a new maintenance window.

Request Body

Parameter	Type	Required	Description
`title`	string	Required	Window title.
`description`	string	Optional	Optional description.
`monitorId`	string	Optional	Specific monitor ID, or omit for org-wide.
`startsAt`	string	Required	ISO 8601 start time.
`endsAt`	string	Required	ISO 8601 end time (must be after startsAt).

bash

curl -X POST https://api.traxo.dev/api/maintenance \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database upgrade",
    "description": "Upgrading PostgreSQL to v16",
    "monitorId": "cm1abc123",
    "startsAt": "2025-06-20T02:00:00.000Z",
    "endsAt": "2025-06-20T04:00:00.000Z"
  }'

Response (201 Created)

json

{
  "data": {
    "id": "mw_001",
    "title": "Database upgrade",
    "description": "Upgrading PostgreSQL to v16",
    "monitorId": "cm1abc123",
    "monitorName": "Production API",
    "startsAt": "2025-06-20T02:00:00.000Z",
    "endsAt": "2025-06-20T04:00:00.000Z",
    "isActive": true
  }
}

PATCH/api/maintenance/:id

Update a maintenance window. All fields are optional.

Request Body

Parameter	Type	Required	Description
`title`	string	Optional	Window title.
`description`	string	Optional	Description.
`monitorId`	string	Optional	Monitor ID.
`startsAt`	string	Optional	ISO 8601 start time.
`endsAt`	string	Optional	ISO 8601 end time.
`isActive`	boolean	Optional	Enable or disable the window.

bash

curl -X PATCH https://api.traxo.dev/api/maintenance/mw_001 \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "endsAt": "2025-06-20T06:00:00.000Z"
  }'

Response

json

{
  "data": {
    "id": "mw_001",
    "title": "Database upgrade",
    "description": "Upgrading PostgreSQL to v16",
    "monitorId": "cm1abc123",
    "monitorName": "Production API",
    "startsAt": "2025-06-20T02:00:00.000Z",
    "endsAt": "2025-06-20T06:00:00.000Z",
    "isActive": true
  }
}

DELETE/api/maintenance/:id

Delete a maintenance window.

bash

curl -X DELETE https://api.traxo.dev/api/maintenance/mw_001 \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "message": "Maintenance window deleted successfully"
}

API Keys

Manage API keys for programmatic access to the Traxo API. Keys use the traxo_ prefix and are scoped to the authenticated user.

GET/api/api-keys

List all API keys for the authenticated user. Keys are returned with masked values -- only the prefix and last 4 characters are visible.

bash

curl https://api.traxo.dev/api/api-keys \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "key_001",
      "name": "CI/CD Pipeline",
      "key": "traxo_ab...ef12",
      "lastUsed": "2025-06-15T10:00:00.000Z",
      "createdAt": "2025-06-01T09:00:00.000Z",
      "expiresAt": null
    }
  ]
}

POST/api/api-keys

Generate a new API key. The full key is only returned once at creation time -- store it securely.

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Display name for the key (max 100 chars).

bash

curl -X POST https://api.traxo.dev/api/api-keys \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline"
  }'

Response (201 Created)

json

{
  "data": {
    "id": "key_001",
    "name": "CI/CD Pipeline",
    "key": "traxo_a1b2c3d4e5f6...",
    "lastUsed": null,
    "createdAt": "2025-06-15T10:00:00.000Z",
    "expiresAt": null
  }
}

Store the key immediately

The full API key is only shown once upon creation. Subsequent GET requests return a masked version. If you lose the key, you must revoke it and generate a new one.

DELETE/api/api-keys/:id

Permanently revoke an API key. Any requests using this key will immediately begin returning 401 Unauthorized.

bash

curl -X DELETE https://api.traxo.dev/api/api-keys/key_001 \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "message": "API key revoked successfully"
}

Team

Manage team members within your organization. Members can have one of three roles: OWNER, ADMIN, or VIEWER. Only owners and admins can invite or remove members.

GET/api/team

List all members of the authenticated user's organization, ordered by join date.

bash

curl https://api.traxo.dev/api/team \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": [
    {
      "id": "mem_001",
      "userId": "usr_001",
      "role": "OWNER",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "image": "https://example.com/avatar.png",
      "joinedAt": "2025-06-01T09:00:00.000Z"
    }
  ]
}

POST/api/team/invite

Invite a user to the organization by email. The user must already have a Traxo account. Requires OWNER or ADMIN role.

Request Body

Parameter	Type	Required	Description
`email`	string	Required	Email address of the user to invite.
`role`	string	Required	Role to assign: "ADMIN" or "VIEWER".

bash

curl -X POST https://api.traxo.dev/api/team/invite \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bob@example.com",
    "role": "ADMIN"
  }'

Response (201 Created)

json

{
  "data": {
    "id": "mem_002",
    "userId": "usr_002",
    "role": "ADMIN",
    "name": "Bob Smith",
    "email": "bob@example.com",
    "image": null,
    "joinedAt": "2025-06-15T10:00:00.000Z"
  },
  "message": "Team member invited successfully"
}

DELETE/api/team/:memberId

Remove a member from the organization. Requires OWNER or ADMIN role. You cannot remove yourself or the organization owner.

bash

curl -X DELETE https://api.traxo.dev/api/team/mem_002 \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "message": "Team member removed successfully"
}

Billing

Manage billing, subscriptions, and plan upgrades. Billing is powered by RevenueCat. Use these endpoints to check your current plan, get checkout info for client-side purchases, and fetch subscription details.

GET/api/billing

Get billing information for the authenticated organization, including the current plan and monitor usage.

bash

curl https://api.traxo.dev/api/billing \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "plan": "PRO",
  "monitorCount": 42,
  "monitorLimit": 100
}

POST/api/billing/checkout

Get RevenueCat product info for a plan upgrade. Returns the product ID and API key needed to initiate a client-side purchase via the RevenueCat web SDK.

Request Body

Parameter	Type	Required	Description
`plan`	string	Required	Plan to subscribe to: "PRO", "BUSINESS", or "ENTERPRISE".

bash

curl -X POST https://api.traxo.dev/api/billing/checkout \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "PRO"
  }'

Response

json

{
  "data": {
    "productId": "traxo_pro_monthly",
    "appUserId": "user_abc123",
    "apiKey": "rcb_..."
  }
}

POST/api/billing/portal

Fetch subscription details from RevenueCat for the authenticated user. Returns active subscriptions, entitlements, and a management URL (if available) for the user to manage their subscription.

bash

curl -X POST https://api.traxo.dev/api/billing/portal \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "subscriptions": { "traxo_pro_monthly": { "expires_date": "2026-04-11T00:00:00Z" } },
    "entitlements": { "pro": { "expires_date": "2026-04-11T00:00:00Z" } },
    "managementUrl": "https://apps.apple.com/account/subscriptions"
  }
}

Organization

Organizations are the top-level container for monitors, team members, and billing. Each user belongs to one organization.

GET/api/organization

Get the authenticated user's organization details.

bash

curl https://api.traxo.dev/api/organization \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "id": "org_001",
    "name": "Acme Inc",
    "slug": "acme-inc",
    "plan": "PRO",
    "createdAt": "2025-06-01T09:00:00.000Z"
  }
}

POST/api/organization

Create a new organization. The authenticated user becomes the owner. A user can only belong to one organization.

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Organization display name.
`slug`	string	Required	URL-friendly slug (must be unique).

bash

curl -X POST https://api.traxo.dev/api/organization \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc",
    "slug": "acme-inc"
  }'

Response (201 Created)

json

{
  "data": {
    "id": "org_001",
    "name": "Acme Inc",
    "slug": "acme-inc",
    "createdAt": "2025-06-15T10:00:00.000Z"
  }
}

PATCH/api/organization

Update the organization name or slug. All fields are optional.

Request Body

Parameter	Type	Required	Description
`name`	string	Optional	New organization name.
`slug`	string	Optional	New URL slug (must be unique).

bash

curl -X PATCH https://api.traxo.dev/api/organization \
  -H "Authorization: Bearer traxo_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation"
  }'

Response

json

{
  "data": {
    "id": "org_001",
    "name": "Acme Corporation",
    "slug": "acme-inc",
    "plan": "PRO"
  }
}

Dashboard Stats

Retrieve high-level statistics for the organization dashboard, including monitor counts, current downtime, average uptime over 30 days, and today's incident count.

GET/api/dashboard/stats

Get summary statistics for the organization's monitoring dashboard.

bash

curl https://api.traxo.dev/api/dashboard/stats \
  -H "Authorization: Bearer traxo_xxx"

Response

json

{
  "data": {
    "totalMonitors": 25,
    "currentlyDown": 1,
    "avgUptime": 99.87,
    "incidentsToday": 3
  }
}

Traxo

API Documentation

Need help? Contact support