API Reference

Overview

The Pulse API is organized around REST. All endpoints accept and return JSON. The public API is available at the base URL below. Every request is scoped to a specific project via the :slugpath parameter, which is your project’s unique URL slug.

For example, if your project slug is my-app, all requests will be prefixed with https://pulse.g8n.ai/api/v1/projects/my-app.

Authentication

The public API endpoints documented on this page resolve projects by their URL slug and do not require API key authentication. They are designed to be called from client-side code, such as the embeddable widget.

Admin API (Bearer Token)

The Admin API at /api/v1/admin/* requires an API key. Generate keys from your project settings in the Pulse dashboard. Keys are prefixed with plsk_ and authenticated via SHA-256 hash comparison using timing-safe equality.

Include your API key in the Authorization header:

curl -H "Authorization: Bearer plsk_your_api_key_here" \
  https://pulse.g8n.ai/api/v1/admin/changelog

Visitor Identification

Several endpoints require an x-pulse-user-id header to identify the visitor. This is an anonymous UUID generated client-side (similar to an analytics anonymous ID). It is not an authenticated user credential. It must be a valid UUID v4.

x-pulse-user-id: 550e8400-e29b-41d4-a716-446655440000

API Key Scopes

Admin API keys include scopes that determine what operations are permitted. The scopes are stored alongside the key and returned during validation. Common scopes include read, write, and module-specific scopes. Expired keys are automatically rejected.

Rate Limiting

All API requests are rate-limited using an in-memory sliding window. Limits are applied per endpoint group and per identifier (project slug or user ID).

When the rate limit is exceeded, the API returns a 429 Too Many Requests response:

{
  "data": null,
  "error": "Rate limit exceeded"
}

Response Format

All responses follow a consistent JSON envelope with two fields: data and error. On success, error is null. On failure, data is null.

Success Response

{
  "data": [ ... ],
  "error": null
}

Error Response

{
  "data": null,
  "error": "Human-readable error message"
}

CORS

All responses include permissive CORS headers to allow requests from any origin. The allowed headers are: Content-Type, Authorization, x-api-key, and x-pulse-user-id.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Changelog

Retrieve published changelog entries, check for unseen entries, and mark entries as viewed. Entries are returned in reverse chronological order by publication date.

{
  "data": [
    {
      "id": "uuid",
      "version": "1.2.0",
      "title": "New Dashboard Layout",
      "summary": "Redesigned the main dashboard...",
      "content": "<p>Full HTML content...</p>",
      "type": "feature",
      "category": "ui",
      "is_highlight": true,
      "ai_summary": "AI-generated summary text",
      "published_at": "2025-03-15T10:00:00Z",
      "created_at": "2025-03-14T08:30:00Z"
    }
  ],
  "error": null
}

{
  "data": {
    "unseen_count": 3,
    "unseen_ids": [
      "uuid-1",
      "uuid-2",
      "uuid-3"
    ]
  },
  "error": null
}

{
  "data": {
    "viewed": true
  },
  "error": null
}

Roadmap

Retrieve published roadmap entries and submit votes. Entries are ordered by milestone number (ascending) then sort order (ascending).

{
  "data": [
    {
      "id": "uuid",
      "milestone_number": 1,
      "milestone_name": "v2.0 Launch",
      "feature_name": "Dark Mode Support",
      "feature_status": "in_progress",
      "user_friendly_description": "Full dark mode theme...",
      "target_date": "2025-06-01",
      "category": "ui",
      "tags": ["theme", "accessibility"],
      "sort_order": 1,
      "is_highlight": false,
      "vote_count": 42,
      "published_at": "2025-03-01T00:00:00Z"
    }
  ],
  "error": null
}

{
  "data": {
    "vote_count": 43,
    "user_vote": "up"
  },
  "error": null
}

Feedback

Submit user feedback, retrieve feedback history for a user, and add messages to existing feedback threads. Feedback submission uses the stricter feedback rate limit (10 requests per minute).

{
  "data": {
    "id": "uuid"
  },
  "error": null
}

{
  "data": [
    {
      "id": "uuid",
      "title": "Button not working on mobile",
      "category": "bug",
      "status": "new",
      "priority": "medium",
      "created_at": "2025-03-15T10:00:00Z"
    }
  ],
  "error": null
}

{
  "data": {
    "id": "uuid",
    "feedback_id": "uuid",
    "message": "Here is additional context...",
    "sender_role": "user",
    "sender_id": "visitor-uuid",
    "is_public": true,
    "created_at": "2025-03-15T11:00:00Z"
  },
  "error": null
}

Notifications

Retrieve notifications for a visitor and mark them as read. Returns up to 50 notifications per request, ordered by creation date descending.

{
  "data": {
    "notifications": [
      {
        "id": "uuid",
        "type": "changelog",
        "title": "New version released",
        "message": "Version 2.1 is now available",
        "link": "/changelog/v2.1",
        "metadata": {},
        "read_at": null,
        "created_at": "2025-03-15T10:00:00Z"
      }
    ],
    "unreadCount": 1
  },
  "error": null
}

{
  "data": {
    "read": true
  },
  "error": null
}

Announcements

Retrieve active announcements and dismiss them. Announcements support time-based scheduling (starts_at / ends_at) and are automatically filtered to show only currently active entries, ordered by priority descending.

{
  "data": [
    {
      "id": "uuid",
      "title": "Scheduled Maintenance",
      "message": "We will be performing maintenance on March 20th.",
      "type": "warning",
      "banner_color": "#d97706",
      "is_dismissible": true,
      "priority": 10,
      "starts_at": "2025-03-18T00:00:00Z",
      "ends_at": "2025-03-21T00:00:00Z"
    }
  ],
  "error": null
}

{
  "data": {
    "dismissed": true
  },
  "error": null
}

Embeddable Widget

Pulse provides a drop-in JavaScript widget that adds a feedback button, changelog panel, and announcement banners to any website. The widget renders inside a Shadow DOM to avoid CSS conflicts with your site.

Installation

Add the following script tag to your HTML. Replace your-project-slugwith your project’s slug.

<script
  src="https://pulse.g8n.ai/api/widget/widget.js"
  data-pulse-project="your-project-slug"
  data-pulse-user="optional-uuid-for-visitor"
  data-pulse-theme="light"
  data-pulse-position="bottom-right"
  data-pulse-features="feedback,changelog,announcements"
  defer
></script>

Configuration Attributes

How the Widget Uses the API

On initialization, the widget makes the following API calls based on enabled features:

Visitor ID Pattern

The data-pulse-user attribute (sent as the x-pulse-user-id header) serves as an anonymous visitor identifier. It is analogous to an analytics anonymous ID and is not an authenticated user credential.

If you have authenticated users, you can pass a stable identifier (or a UUID derived from their user ID) to enable per-user features like unseen changelog counts, vote tracking, and announcement dismissals. If you do not provide a visitor ID, the widget will still work for features that do not require it (viewing changelogs, viewing announcements, submitting feedback).

// Generate and persist a visitor ID
function getVisitorId() {
  let id = localStorage.getItem('pulse-visitor-id');
  if (!id) {
    id = crypto.randomUUID();
    localStorage.setItem('pulse-visitor-id', id);
  }
  return id;
}