API Reference

API Introduction

Learn how to authenticate and use the Faurya public API.

API Introduction

Use the Faurya public API to read analytics data, inspect visitors, and send server-side conversion or revenue events.

Base URL

All endpoints use this base URL:

https://api.faurya.com

Authentication

All API requests require Bearer Token authentication.

Add your API key in the Authorization header:

Authorization: Bearer YOUR_FAURYA_API_KEY

Content type

Send JSON request bodies with:

Content-Type: application/json

Available endpoints

GET /api/v1/analytics/timeseries and GET /api/v1/analytics/goals currently return 501 Not Implemented.

The billing endpoints have their own response envelope, error catalogue and rate limit, described in the Billing API overview. The notes below describe the other endpoints.

Common response behavior

  • 200 OK: Request accepted and recorded.
  • 400 Bad Request: Invalid payload (missing required fields, invalid field format, or bot visitor).
  • 401 Unauthorized: Missing or invalid Bearer Token.
  • 404 Not Found: Resource context missing (for example, creating a goal for a visitor with no prior pageviews).
  • 429 Too Many Requests: Account event limit reached.
  • 501 Not Implemented: Endpoint exists but is not implemented yet.
  • 500 Internal Server Error: Unexpected server issue.

Field naming and validation notes

  • Payments require a unique transaction_id.
  • Goal and payment metadata must be a JSON object with a maximum of 10 primitive values.
  • If available, always send faurya_visitor_id to improve attribution quality.

Best practices

  • Send events server-side after the action is confirmed (successful checkout, confirmed signup, etc.).
  • Retry safely on transient errors, but avoid duplicate sends for the same event.
  • Log response status and payload in your backend for debugging.

Next steps

  • Start with Create a goal to track non-payment conversions.
  • Use Create a payment to attribute revenue from any payment provider.
  • Use the Billing API when you need subscriptions, invoices, refunds and MRR rather than single payments.