REST API | Installation | Spectacle Docs

Spectacle REST API

The Spectacle HTTP Tracking API allows you to record analytics data from any website or application.

Authentication

You can authenticate with the API using your workspace id by including it in the request body.

curl --location 'https://api.spectacle.com/tracking/track' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event": "Trial Started",
    "email": "user@example.org",
    "userId": "123",
    "workspaceId": "ws_example"
}'

Content-Type

All data sent to Spectacle’s HTTP API must set a content-type header to 'application/json'.

Identify

Identify links a user to actions they perform and records user traits like email, name, or industry.

Spectacle recommends calling Identify once when a user account is created, and only again if traits change.

Example Identify Call:

POST https://api.spectacle.com/tracking/identify

{
  "userId": "user_123",
  "anonymousId": "1234-5678-8910",
  "traits": {
    "email": "user@example.org",
    "name": "John Doe",
    "industry": "Technology"
  },
  "timestamp": "2024-12-09T00:30:08.276Z",
  "workspaceId": "YOUR_WORKSPACE_ID"
}

Fields

userId: The unique identifier for the user in your database. (String, required)
anonymousId: Can be obtained from JS. Please reach out to support to help you set this up. (String, required)
workspaceId: Can be found in your workspace settings. (String, required)
timestamp: Optional. Defaults to current time in ISO-8601 format. (Date)
traits: Optional. User details like email or name. (Object)

Special Traits

email: Email address of the user
firstName: First name of the user
lastName: Last name of the user
companyId: Company ID of the user
companyName: Company name of the user

Track

The Track method lets you capture specific actions users perform. Each action is recorded as an “event” and may include properties associated with that event, such as revenue or name.

Example Track Call:

POST https://api.spectacle.com/tracking/track

{
  "userId": "user_123",
  "event": "Charged",
  "properties": {
    "revenue": 1599
  },
  "timestamp": "2012-12-02T00:30:12.984Z",
  "workspaceId": "YOUR_WORKSPACE_ID"
}

Fields

userId: The unique identifier for the user in your database. (String, required)
event: The name of the action performed by the user. (String, required)
workspaceId: Can be found in your workspace settings. (String, required)
timestamp: Optional, defaults to current time in ISO-8601 format. (Date)
properties: Custom data associated with the event (e.g., revenue). (Object)

Special properties

revenue: Revenue in the smallest currency unit.
currency: The three-letter ISO code of the revenue's currency
plan: The customer's plan.
mrr: The current mrr for the customer. Every time mrr is passed, it overwrites the previous mrr.
arr: The current arr for the customer. Every time arr is passed, it overwrites the previous arr.

Page

The Page method allows you to record page views on a website, along with optional data about the page being viewed, such as URL and title.

Example Page Call:

POST https://api.spectacle.com/tracking/page

{
  "userId": "user_123",
  "timestamp": "2012-12-02T00:31:29.738Z",
  "workspaceId": "YOUR_WORKSPACE_ID"
}

Fields

anonymousId: Required if userId is not set. A unique identifier for users without a userId. (String)
userId: Required if anonymousId is not set. The unique identifier for the user in your database. (String)
workspaceId: Can be found in your workspace settings. (String, required)
timestamp: Optional, defaults to current time in ISO-8601 format. (Date)