REST API

QueryWise exposes a full REST API under /api/v1/. Everything the dashboard does, the API does — same endpoints, same data, same authorization model. The interactive OpenAPI schema is served at /docs on every QueryWise instance.

Authentication

Two paths:

1. Session cookie + JWT — what the dashboard uses. Auth0-issued RS256 tokens, validated on every request.
2. API key — for programmatic access, CI/CD, integrations. Generate from Settings → API Keys.

API key requests:

curl -H "Authorization: Bearer qw_live_..." https://app.querywise.io/api/v1/recommendations

API keys are scoped to a tenant and a role (typically editor or viewer). They never expire automatically; you can rotate or revoke from the same page.

Rate limits

The default rate limit is 120 requests per minute per tenant. Exceeded requests get HTTP 429 with a Retry-After header. Higher limits are available on enterprise plans.

The middleware order is:

CORS → Rate Limit → Auth → Tenant Resolution → Audit

Tenant resolution sets the PostgreSQL search_path to the tenant's schema, so every downstream query is automatically scoped.

Major endpoint groups

The API has 26+ endpoint groups. The ones most teams use:

Costs & analytics

• GET /api/v1/costs/summary — top-level cost summary
• GET /api/v1/costs/breakdown — by vendor, service, tag, or cost center
• GET /api/v1/costs/trends — time series with forecast
• GET /api/v1/costs/forecast — 30/60/90-day projections
• GET /api/v1/analytics/cost-drivers — what drove month-over-month change
• GET /api/v1/focus-export — FOCUS-standard export (JSON or CSV)

Recommendations

• GET /api/v1/recommendations — list with filters (severity, category, vendor, status)
• GET /api/v1/recommendations/{id} — detail with evidence + remediation
• POST /api/v1/recommendations/{id}/apply — execute apply workflow
• GET /api/v1/recommendations/{id}/impact — before/after comparison
• POST /api/v1/recommendations/{id}/analyze — trigger AI deep analysis

Cloud accounts

• GET /api/v1/accounts — list connected accounts
• POST /api/v1/accounts — connect new vendor (validated against tag policy)
• POST /api/v1/accounts/{id}/test — connection test
• POST /api/v1/accounts/{id}/sync — trigger on-demand sync
• GET /api/v1/accounts/{id}/schema-metadata — table/column inventory

Budgets & alerts

• GET /api/v1/budgets — list budgets
• POST /api/v1/budgets — create budget with thresholds
• GET /api/v1/alerts — alert feed
• POST /api/v1/alerts/{id}/acknowledge — acknowledge alert

Tags & allocation

• GET /api/v1/tags/discovery — coverage and cardinality per tag
• GET /api/v1/tags/allocation — cost broken down by tag
• GET /api/v1/cost-centers — list cost centers
• POST /api/v1/cost-centers — create cost center
• GET /api/v1/cost-centers/{id}/chargeback — chargeback report

Queries

• GET /api/v1/queries — top queries by cost, duration, or count
• GET /api/v1/queries/{hash} — query detail with plan and anti-pattern matches
• GET /api/v1/queries/{hash}/plans — execution plan history

Reports

• GET /api/v1/reports — saved reports
• POST /api/v1/reports/{id}/share — generate shareable read-only link
• GET /reports/share/{token} — public-readable shared report

Integrations

• POST /api/v1/integrations/jira/connect — JIRA OAuth flow start
• POST /api/v1/integrations/servicenow/connect — ServiceNow OAuth (with instance_url)
• POST /api/v1/integrations/slack/test — test Slack webhook

Response shape

All list endpoints return the same envelope:

{
  "items": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}

All detail endpoints return the resource directly. Errors are RFC 7807 Problem JSON.

Pagination

Cursor-based pagination is supported on heavy endpoints (recommendations, queries, audit):

GET /api/v1/recommendations?limit=50&cursor=eyJpZCI6IjE...

The response includes next_cursor if there are more pages.

Audit logging

Every API write is logged in audit_logs with the actor, tenant, action, target, and request payload (sanitized). Reads are sampled. The audit feed is available at GET /api/v1/audit/events and on the Activity Log dashboard page.

OpenAPI schema

For the full reference, hit /docs on your QueryWise instance — it serves Swagger UI generated from the live FastAPI schema. The raw OpenAPI JSON is at /openapi.json.

Where to next

• Recommendations Engine — what the recommendations API actually returns.
• Workflows & Integrations — how to wire JIRA, ServiceNow, and Slack.