Xplorr API Reference

Xplorr API Reference

The Xplorr API is a REST API served over HTTPS. All endpoints require authentication unless noted otherwise. Base URL: https://api.xplorr.io/api/v1.

Authentication

All requests must include a Bearer token in the Authorization header:

curl -H "Authorization: Bearer xplorr_your_token" \
  https://api.xplorr.io/api/v1/costs

Get your API token from Settings → API in the console. See the Authentication guide for detailed setup.

---

Auth Endpoints

Method	Path	Rate Limit	Description
POST	/auth/login	20/15min	Log in with email + password. Returns access + refresh tokens.
POST	/auth/signup	20/15min	Register a new account with business email.
POST	/auth/refresh	—	Exchange refresh token for new access token.
POST	/auth/logout	—	Revoke the current refresh token.
GET	/auth/me	—	Get current user profile.
POST	/auth/forgot-password	20/15min	Send password reset email.
POST	/auth/reset-password	5/30min	Reset password with token.
POST	/auth/change-password	—	Change password (authenticated).
POST	/auth/verify-email	—	Verify email address with token.
POST	/auth/resend-verification	20/15min	Resend verification email.
POST	/auth/invite	—	Invite user to org (admin only).
GET	/auth/invitation/:token	—	Check invitation status.
POST	/auth/accept-invitation	—	Accept invite and create account.

Two-Factor Authentication

Method	Path	Rate Limit	Description
POST	/auth/2fa/setup	—	Start TOTP 2FA setup. Returns QR code.
POST	/auth/2fa/confirm	—	Confirm TOTP code to enable 2FA.
POST	/auth/2fa/authenticate	10/15min	Verify TOTP code during login.
POST	/auth/2fa/disable	5/15min	Disable 2FA.

WebAuthn / Passkeys

Method	Path	Description
GET	/auth/webauthn/register/options	Get registration challenge.
POST	/auth/webauthn/register/verify	Verify and register credential.
GET	/auth/webauthn/authenticate/options	Get authentication challenge.
POST	/auth/webauthn/authenticate/verify	Authenticate with passkey.
GET	/auth/webauthn/credentials	List registered security keys.
DELETE	/auth/webauthn/credentials/:id	Remove a security key.

SSO / SAML

Method	Path	Description
GET	/auth/sso/check?email=...	Check if SSO is required for email domain.
GET	/auth/saml/init?org_slug=...	Start SAML authentication flow.
POST	/auth/saml/acs	SAML Assertion Consumer Service callback.
GET	/auth/saml/metadata/:org_slug	Get SP metadata XML.
GET	/auth/sso/config	Get org SSO configuration (admin).
PATCH	/auth/sso/config	Configure SSO (admin).
DELETE	/auth/sso/config	Disable SSO (admin).

---

Costs

Method	Path	Rate Limit	Description
GET	/costs	30/min	Cost breakdown with grouping.
GET	/costs/trend	30/min	Daily cost trend over time range.

Query parameters for /costs:

Parameter	Type	Description
startDate	string	Start date (YYYY-MM-DD). Default: 30 days ago.
endDate	string	End date (YYYY-MM-DD). Default: today.
provider	string	Filter: aws, azure, or gcp.
accountId	string	Filter to a specific cloud account.
groupBy	string	Group by: provider, service, region, date, account.

---

Cloud Accounts

Method	Path	Rate Limit	Description
GET	/cloud-accounts	—	List all connected cloud accounts.
POST	/cloud-accounts	20/hour	Connect a new cloud account (admin).
GET	/cloud-accounts/:id	—	Get account details.
PATCH	/cloud-accounts/:id	—	Update account credentials (admin).
DELETE	/cloud-accounts/:id	—	Disconnect a cloud account (admin).
GET	/cloud-accounts/server-aws-config	—	Check if server-level AWS credentials are configured.

---

Sync

Method	Path	Rate Limit	Description
POST	/sync/all	10/hour	Trigger full sync for all accounts (admin).
POST	/sync/:accountId	10/hour	Trigger sync for one account (admin).
GET	/sync/status	—	Get last sync status for all accounts.
GET	/sync/jobs	—	List sync jobs (paginated). Query: limit, offset.

---

Resource Inventory

Method	Path	Description
GET	/inventory	Query resources with filters (paginated).
GET	/inventory/filters	Get distinct filter values for dropdowns.
GET	/inventory/export	Export inventory as CSV (max 50,000 rows).

Query parameters for /inventory:

Parameter	Type	Description
accountId	string	Filter by cloud account.
provider	string	Filter: aws, azure, gcp.
region	string	Filter by region.
type	string	Filter by resource type (e.g., EC2 Instance).
status	string	Filter by status (e.g., Running, Stopped).
search	string	Free-text search across name and ID.
page	number	Page number (default: 1).
limit	number	Results per page (max: 100).

---

Anomalies

Method	Path	Description
GET	/anomalies	List cost anomalies. Query: status, severity, limit, accountId.
PATCH	/anomalies/:id	Update anomaly status. Body: { "status": "acknowledged" } or "resolved".

---

Recommendations

Method	Path	Description
GET	/recommendations	List recommendations with filters.
PATCH	/recommendations/:id	Update recommendation status.
POST	/recommendations/:id/snooze	Snooze a recommendation until a date.
GET	/ai-recommendations	Get AI-generated recommendations.

Query parameters for /recommendations:

Parameter	Type	Description
status	string	open, in_progress, applied, dismissed.
type	string	Recommendation type filter.
provider	string	aws, azure, gcp.
accountId	string	Filter by cloud account.
category	string	Category filter.
limit	number	Max results (default: 50).
offset	number	Pagination offset.
includeSnoozed	boolean	Include snoozed recommendations.

---

Budgets

Method	Path	Rate Limit	Description
GET	/budgets	—	List all budgets with current spend.
POST	/budgets	30/min	Create a budget.
PATCH	/budgets/:id	30/min	Update a budget.
DELETE	/budgets/:id	—	Delete a budget.

Request body for POST /budgets:

{
  "name": "AWS Production",
  "amount": 5000,
  "currency": "USD",
  "cloud_account_id": "uuid-optional",
  "alert_at_80": true,
  "alert_at_100": true
}

---

Alerts

Method	Path	Rate Limit	Description
GET	/alerts	—	List all alert rules.
POST	/alerts	30/min	Create an alert rule.
GET	/alerts/:id	—	Get alert rule details.
PATCH	/alerts/:id	30/min	Update an alert rule.
DELETE	/alerts/:id	—	Delete an alert rule.

Request body for POST /alerts:

{
  "name": "Daily AWS > $500",
  "metric": "daily_spend",
  "conditionOp": ">",
  "threshold": 500,
  "currency": "USD",
  "notifyEmails": ["[email protected]"],
  "serviceFilter": "Amazon EC2",
  "regionFilter": "us-east-1",
  "cloudAccountId": "uuid-optional",
  "slackWebhookUrl": "https://hooks.slack.com/..."
}

---

Approval Workflows

Method	Path	Description
GET	/approvals	List approval requests. Query: status, limit, offset.
GET	/approvals/:id	Get approval details.
POST	/approvals	Create approval request. Body: { "recommendation_id": "uuid" }.
PATCH	/approvals/:id	Approve or reject. Body: { "status": "approved" } or "rejected".

---

Tagging Policies

Method	Path	Rate Limit	Description
GET	/tagging-policies	—	List all tagging policies.
POST	/tagging-policies	30/min	Create a tagging policy (admin).
DELETE	/tagging-policies/:id	30/min	Delete a tagging policy (admin).
GET	/tagging-policies/violations	—	Get resources violating tagging policies (max 200).

Request body for POST /tagging-policies:

{
  "tag_key": "team",
  "required": true,
  "allowed_values": ["api", "data", "frontend"],
  "applies_to": "all"
}

Valid applies_to values: all, ec2, rds, s3, compute, storage.

---

Cost Allocation Rules

Method	Path	Rate Limit	Description
GET	/allocation-rules	—	List cost allocation rules.
POST	/allocation-rules	30/min	Create allocation rule (admin).
PATCH	/allocation-rules/:id	30/min	Update allocation rule.
DELETE	/allocation-rules/:id	—	Delete allocation rule.

---

Unit Economics

Method	Path	Rate Limit	Description
GET	/unit-economics	—	Get cost per unit over date range. Query: startDate, endDate, metricName.
POST	/unit-economics/metrics	30/min	Ingest a unit metric data point.

Request body for POST /unit-economics/metrics:

{
  "name": "Active Customers",
  "metric_type": "customers",
  "value": 1247,
  "date": "2026-03-21"
}

Valid metric_type values: api_calls, transactions, customers, requests, custom.

---

Reports

Method	Path	Rate Limit	Description
GET	/reports	10/15min	Get report data as JSON. Query: startDate, endDate, accountId, format.
GET	/reports/pdf	10/15min	Generate and download PDF report.
GET	/reports/excel	10/15min	Generate and download Excel report.
GET	/reports/cost-summary	—	Get cost summary data.

---

Scheduled Reports

Method	Path	Rate Limit	Description
GET	/scheduled-reports	—	List scheduled reports.
POST	/scheduled-reports	30/min	Create a scheduled report (admin).
GET	/scheduled-reports/:id	—	Get scheduled report details.
PATCH	/scheduled-reports/:id	30/min	Update a scheduled report.
DELETE	/scheduled-reports/:id	—	Delete a scheduled report.

Request body for POST /scheduled-reports:

{
  "name": "Monthly CFO Report",
  "frequency": "monthly",
  "day_of_month": 1,
  "recipients": ["[email protected]", "[email protected]"],
  "cloud_account_id": null,
  "format": "pdf",
  "is_active": true
}

---

Commitment Analysis

Method	Path	Description
GET	/commitments/analysis	Get RI/SP coverage analysis with AI advice.

---

Network Costs

Method	Path	Description
GET	/network/summary	Get network cost summary. Query: account_id, days.

---

Users

Method	Path	Description
GET	/users	List org users (admin: all, member: self).
GET	/users/:id	Get user details.
PATCH	/users/:id	Update user profile or role.
DELETE	/users/:id	Deactivate user (admin).
GET	/users/available-accounts	Get accounts available for invite modal (admin).
GET	/users/invitations/list	List pending invitations (admin).
GET	/users/:id/accounts	List user’s cloud account access (admin).
POST	/users/:id/accounts	Grant account access (admin).
DELETE	/users/:id/accounts/:accountId	Revoke account access (admin).
GET	/users/notification-preferences	Get notification settings.
PATCH	/users/notification-preferences	Update notification settings.

---

Organizations

Method	Path	Description
GET	/organizations/current	Get current organization.
PATCH	/organizations/current	Update org name (admin).
GET	/organizations/stats	Get org statistics (admin).
DELETE	/organizations/close	Close org and delete all data (admin). Requires x-confirm-close: DELETE_MY_ORGANIZATION header.
PATCH	/organizations/require-2fa	Enforce mandatory 2FA (admin).

---

Audit Logs

Method	Path	Description
GET	/audit	List audit logs (admin). Query: page, limit, action, user_email, from, to.
GET	/audit/actions	Get distinct action types for filter dropdown.
GET	/audit/export	Export audit logs as CSV (max 10,000 rows).

---

API Tokens

Method	Path	Rate Limit	Description
GET	/tokens	—	List API tokens.
POST	/tokens	—	Create API token.
DELETE	/tokens/:id	—	Revoke API token.
POST	/tokens/exchange	30/15min	Exchange xplorr_ token for JWT (used by MCP server).

---

Slack & Teams Integration

Method	Path	Description
GET	/slack/install	Start Slack OAuth flow (admin).
GET	/slack/oauth_redirect	Slack OAuth callback.
GET	/slack/installation	Get Slack installation status.
DELETE	/slack/installation	Disconnect Slack (admin).
GET	/teams/install	Start Teams OAuth flow (admin).
GET	/teams/oauth_redirect	Teams OAuth callback.
GET	/teams/installation	Get Teams installation status.
DELETE	/teams/installation	Disconnect Teams (admin).

---

Channel Configuration

Method	Path	Description
GET	/channels	List Slack channel configs (admin).
POST	/channels	Create channel config (admin).
PATCH	/channels/:id	Update channel config (admin).
DELETE	/channels/:id	Delete channel config (admin).

---

Digest Settings

Method	Path	Description
GET	/digest-settings	List digest schedules (admin).
POST	/digest-settings	Create digest schedule (admin).
PATCH	/digest-settings/:id	Update digest schedule (admin).
DELETE	/digest-settings/:id	Delete digest schedule (admin).

---

Settings

Method	Path	Description
GET	/settings	Get org-level settings.
PATCH	/settings	Update settings (admin).
POST	/settings/slack/test	Send test Slack message (admin).

---

Error Format

All errors follow a consistent format:

{
  "error": {
    "code": "BUDGET_NOT_FOUND",
    "message": "Budget with ID 'abc123' not found.",
    "status": 404
  }
}

Common error codes: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), RATE_LIMITED (429), INTERNAL_ERROR (500).

Pagination

List endpoints support page-based pagination:

GET /api/v1/recommendations?page=2&limit=25

Response includes pagination metadata:

{
  "data": [...],
  "total": 142,
  "page": 2,
  "limit": 25
}

Rate Limiting

Rate limits vary by endpoint type:

Endpoint Type	Limit
Login / Auth	20 requests per 15 minutes
Cost Queries	30 requests per minute
Sync Triggers	10 requests per hour
Write Operations	30 requests per minute
Report Generation	10 requests per 15 minutes
Token Exchange	30 requests per 15 minutes

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.