DOCS

REST API reference

Complete endpoint inventory, authentication methods, request/response shapes, and versioning rules.

Base URL

All endpoints are under:

https://api.example.com/api/v1/

Versioning

Current version: v1 (URL-prefixed /api/v1/)
Non-breaking additions (new fields, new endpoints) ship without a version bump.
Breaking changes require a v2 prefix; a 90-day deprecation window applies.

Authentication

Method	Used by	How to pass
Session cookie	Web platform and admin UI	`xinex_session` HttpOnly Secure cookie (set by login response)
Bearer API token	Scripts, CI, integrations	`Authorization: Bearer xinex_<64-hex>`
Bearer JWT	Mobile app, server-to-server	`Authorization: Bearer <jwt>`
Prober token	Prober agent	`Authorization: Bearer <prober_token>`

Public endpoints (/api/v1/public/*, /health) require no authentication.

Common request headers

Header	When to send
`Authorization: Bearer <token>`	All authenticated requests
`Content-Type: application/json`	POST / PUT with a body
`Idempotency-Key: <uuid>`	Optional; POST / PUT; safe to retry on network failure
`If-None-Match: <etag>`	GET; server returns 304 if resource unchanged

Common response headers

Header	Meaning
`X-Request-Id`	Unique request identifier for tracing
`X-RateLimit-Limit`	Allowed requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`ETag`	Hash for conditional GET
`Cache-Control: no-store`	Present on session-sensitive responses

Response shapes

List response

Every list endpoint returns a paginated envelope. A bare array is never returned.

{
  "items": [...],
  "total": 142,
  "page": 1,
  "per_page": 25,
  "total_pages": 6
}

Default: page=1, per_page=25. Maximum per_page: 100.

Detail response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "...",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-13T08:22:15Z"
}

Create (201) / Update (200) response

Returns the complete object. Not just {"id": "..."}.

Delete response

204 No Content, empty body.

Error response

{
  "error": "Maximum 3 monitors allowed on free tier",
  "code": "TIER_LIMIT_EXCEEDED",
  "details": { "current_count": 3, "tier_limit": 3, "tier": "free" }
}

See API errors reference for the full code catalog.

Endpoint groups

Group	Purpose	Mobile
`POST /api/v1/auth/login`	Password login	Yes
`POST /api/v1/auth/register`	Create account	Yes
`POST /api/v1/auth/logout`	Invalidate session	Yes
`POST /api/v1/auth/password-reset`	Initiate password reset	Yes
`POST /api/v1/auth/password-reset/confirm`	Complete password reset	Yes
`POST /api/v1/auth/verify-email`	Verify email address	Yes
`GET /api/v1/auth/oauth/providers`	List enabled OAuth providers	Yes
`GET /api/v1/auth/oauth/{provider}`	Start OAuth flow (google, github, microsoft, apple)	Yes
`GET /api/v1/auth/oauth/{provider}/callback`	OAuth callback handler	Yes
`POST /api/v1/auth/oauth/apple/native`	Apple native sign-in with `id_token`	Yes
`GET /api/v1/oauth/authorize`	PKCE authorization endpoint	Yes
`POST /api/v1/oauth/token`	Token + refresh endpoint	Yes
`GET /api/v1/sso/login`	SAML SP-initiated SSO	No
`GET /api/v1/me`	Current authenticated user	Yes
`PUT /api/v1/me`	Update profile	Yes
`GET /api/v1/sessions`	List active sessions	Yes
`DELETE /api/v1/sessions/{id}`	Revoke a session	Yes
`GET /api/v1/monitors`	List monitors (paginated)	Yes
`POST /api/v1/monitors`	Create monitor	Yes
`GET /api/v1/monitors/{id}`	Get monitor	Yes
`PUT /api/v1/monitors/{id}`	Update monitor	Yes
`DELETE /api/v1/monitors/{id}`	Delete monitor	Yes
`GET /api/v1/monitors/{id}/status`	Current monitor status	Yes
`GET /api/v1/heartbeats`	List heartbeats	Yes
`POST /api/v1/heartbeats`	Create heartbeat	Yes
`GET /api/v1/heartbeats/{id}`	Get heartbeat	Yes
`PUT /api/v1/heartbeats/{id}`	Update heartbeat	Yes
`DELETE /api/v1/heartbeats/{id}`	Delete heartbeat	Yes
`POST /api/v1/hb/{slug}`	Heartbeat ping endpoint	Yes
`GET /api/v1/ai-heartbeats`	List AI heartbeats	No
`POST /api/v1/ai-heartbeats`	Create AI heartbeat	No
`POST /api/v1/ai-heartbeats/{id}/run`	Post AI heartbeat event	No
`GET /api/v1/incidents`	List incidents (paginated)	Yes
`GET /api/v1/incidents/{id}`	Get incident	Yes
`POST /api/v1/incidents/{id}/ack`	Acknowledge incident	Yes
`POST /api/v1/incidents/{id}/resolve`	Resolve incident	Yes
`GET /api/v1/correlation-groups`	List correlation groups	Yes
`GET /api/v1/alerts`	List alert records	Yes
`GET /api/v1/alert-routing-rules`	List routing rules	Yes
`POST /api/v1/alert-routing-rules`	Create routing rule	Yes
`PUT /api/v1/alert-routing-rules/{id}`	Update routing rule	Yes
`DELETE /api/v1/alert-routing-rules/{id}`	Delete routing rule	Yes
`GET /api/v1/escalation-policies`	List escalation policies	Yes
`POST /api/v1/escalation-policies`	Create policy	Yes
`PUT /api/v1/escalation-policies/{id}`	Update policy	Yes
`DELETE /api/v1/escalation-policies/{id}`	Delete policy	Yes
`GET /api/v1/schedules`	List on-call schedules	Yes
`POST /api/v1/schedules`	Create schedule	Yes
`PUT /api/v1/schedules/{id}`	Update schedule	Yes
`DELETE /api/v1/schedules/{id}`	Delete schedule	Yes
`POST /api/v1/schedules/{id}/overrides`	Create schedule override	Yes
`GET /api/v1/notification-channels`	List notification channels	Yes
`POST /api/v1/notification-channels`	Create channel	Yes
`PUT /api/v1/notification-channels/{id}`	Update channel	Yes
`DELETE /api/v1/notification-channels/{id}`	Delete channel	Yes
`POST /api/v1/notification-channels/{id}/test`	Send test notification	Yes
`GET /api/v1/notification-log`	Sent notification history	No
`GET /api/v1/notifications/feed`	Per-user in-app feed (paginated + `unread_count`)	Yes
`GET /api/v1/notifications/feed/unread-count`	Unread count	Yes
`POST /api/v1/notifications/feed/{id}/read`	Mark one as read	Yes
`POST /api/v1/notifications/feed/read-all`	Mark all as read	Yes
`GET /api/v1/users/me/notification-prefs`	Get notification preferences	Yes
`PUT /api/v1/users/me/notification-prefs`	Update notification preferences	Yes
`GET /api/v1/status-pages`	List status pages	Partial
`POST /api/v1/status-pages`	Create status page	Partial
`PUT /api/v1/status-pages/{id}`	Update status page	Partial
`DELETE /api/v1/status-pages/{id}`	Delete status page	Partial
`GET /api/v1/maintenance-windows`	List maintenance windows	Yes
`POST /api/v1/maintenance-windows`	Create maintenance window	Yes
`PUT /api/v1/maintenance-windows/{id}`	Update maintenance window	Yes
`DELETE /api/v1/maintenance-windows/{id}`	Delete maintenance window	Yes
`GET /api/v1/analytics/uptime`	Uptime stats	Partial
`GET /api/v1/analytics/response-time`	Response time stats	Partial
`GET /api/v1/billing/subscription`	Current subscription	Yes
`POST /api/v1/billing/create-checkout-session`	Start Stripe checkout	Yes
`POST /api/v1/billing/downgrade`	Schedule downgrade `{target_tier}`	Yes
`DELETE /api/v1/billing/downgrade`	Cancel scheduled downgrade	Yes
`POST /api/v1/billing/interval`	Switch billing interval `{interval}`	Yes
`GET /api/v1/billing/invoices`	List invoices (paginated)	Yes
`GET /api/v1/billing/tax-info`	Get tax ID	Yes
`PUT /api/v1/billing/tax-info`	Set tax ID `{country, tax_id, tax_id_type}`	Yes
`GET /api/v1/billing/currencies`	Supported billing currencies	Yes
`GET /api/v1/account/export`	Request data export	Yes
`GET /api/v1/audit-log`	Tenant audit log (paginated)	No
`GET /api/v1/feature-flags`	Active feature flags for tenant	Yes
`GET /api/v1/feature-gates`	List feature gates	Yes
`GET /api/v1/onboarding`	Onboarding step status	Yes
`POST /api/v1/onboarding/{step}/complete`	Mark step complete	Yes
`GET /api/v1/push-tokens`	List push tokens	Yes
`POST /api/v1/push-tokens`	Register device push token	Yes
`DELETE /api/v1/push-tokens/{token}`	Unregister device	Yes
`GET /api/v1/public/brand-settings`	Public brand config	—
`GET /api/v1/public/status-pages/{slug}`	Public status page	—
`GET /api/v1/public/status-pages/{slug}/incidents`	Public status page incidents	—
`POST /api/v1/public/status-pages/{slug}/subscribe`	Subscribe to status page	—
`GET /api/v1/public/tier-info`	Public tier limits	—
`GET /api/v1/public/tiers`	All tier configs with pricing	—
`GET /api/v1/public/tier-comparison`	Tier comparison matrix	—
`GET /api/v1/public/billing/currencies`	Supported currencies (public)	—
`GET /health`	Health check	—
`WSS /api/v1/ws`	WebSocket real-time events (token query param)	Yes

WebSocket

WSS /api/v1/ws?token=<access_token>

The WebSocket connection streams real-time incident and monitor status events. See the Concepts section for event payload shapes.

Rate limits

See Rate limits reference.