API Reference

Base URLs

The API explorer sends browser requests to the same-origin docs proxy:

Environment	Docs URL	API explorer base URL
spark-dev1	https://docs.spark-test.newtoncelestial.com	/api/crm-events
spark-prod-mexico1	https://docs.prod-na-01.nwt-spark.net	/api/crm-events

Example:

curl -sS \
  "https://docs.prod-na-01.nwt-spark.net/api/crm-events/api/v1/overview?tenant_id=..."

docs_ui forwards /api/crm-events/* to the in-cluster crm-events-svc.spark-ai.svc.cluster.local service and marks those forwarded requests as docs-proxy traffic. The docs_ui proxy adds Authorization from its CRM_EVENTS_API_BEARER_TOKEN environment variable, and CRM Events validates the same token from its own CRM_EVENTS_API_BEARER_TOKEN environment variable.

Other in-cluster callers can use http://crm-events-svc.spark-ai.svc.cluster.local without bearer auth. The spark-dev1 direct CRM Events ingress is disabled.

Read-only endpoints:

• GET /health
• GET /api/v1/overview
• GET /api/v1/campaigns
• GET /api/v1/campaigns/:campaign_id
• GET /api/v1/live-events

spark-dev1 and spark-prod-mexico1 require bearer auth only on requests that come through the docs UI proxy.

Errors use a stable JSON envelope:

• All documented API errors return {"error":"..."}.
• Validation, auth, and not-found responses use public messages that are safe to expose.
• Unexpected backend failures return {"error":"internal server error"} while full details stay in server logs.

Response notes:

• GET /api/v1/campaigns/:campaign_id returns the campaign detail object directly.
• GET /api/v1/campaigns/:campaign_id accepts optional tenant_id so detail reads can stay aligned with list scope.
• Pagination uses page and page_size, with totals in total_items and total_pages.
• Campaign list responses include a summary block with overview counters for the applied filters, plus status_counts buckets for suggestions, running, paused, and ended.
• Campaign rows and campaign detail include additive campaign_origin and ui_status fields.
• Campaign rows are metadata-only. Campaign detail adds description, offering, and players_engaged.
• overview.support_cases_total counts Lumio chat conversations only.
• Campaign list and live-event list responses include applied_filters echoing the resolved query parameters.
• Campaign detail does not include applied_filters.
• Every response includes X-Request-Id. Send your own header value to reuse an upstream trace id, or read the generated value from the response.

Endpoint data docs

For the endpoint-by-endpoint data lineage and field mapping, see:

• GET /health
• GET /api/v1/overview
• GET /api/v1/campaigns
• GET /api/v1/campaigns/:campaign_id
• GET /api/v1/live-events

:::tip Interactive reference Browse and call every endpoint in the CRM Events API Explorer. Live "Try it" is available for CRM Events through the docs proxy. :::

Deployments can require bearer auth for docs-proxy traffic with configuration. See Configuration & Secrets.