Skip to main content

​
Overview

Welcome to the Hookpulse API reference. This documentation provides detailed information about all available endpoints, request/response formats, and authentication methods. The Hookpulse API is RESTful and uses JSON for request and response payloads. All API requests must be authenticated using custom headers (x-hookpulse-api-key and x-brand-uuid).

OpenAPI Specification

Download the complete OpenAPI specification file

​
Base URL

All API requests should be made to: 
https://api.hookpulse.io

​
Authentication

All API endpoints require authentication using two custom headers. Include both headers in every request: 
x-hookpulse-api-key: YOUR_API_KEY
x-brand-uuid: YOUR_BRAND_UUID
Never share these credentials with anyone. Keep your API key and brand UUID secure. Never expose them in client-side code or commit them to version control. If your credentials are compromised, regenerate them immediately from your dashboard.

​
Getting your credentials

​
Brand UUID (x-brand-uuid)

  1. Log in to your Hookpulse dashboard
  2. Add a brand (if you haven’t already)
  3. The brand UUID will be displayed in the UI
  4. Copy and securely store your brand UUID

​
API Key (x-hookpulse-api-key)

  1. Log in to your Hookpulse dashboard
  2. Select your brand from the dashboard
  3. Navigate to API Keys section
  4. Click Create API Key
  5. Add a node and you will receive your API Key
  6. The API Key will be displayed on the same card - click View to see it
  7. Copy and securely store your API key
Both the API key and brand UUID are required for all API requests. Make sure to include both headers in every request.

​
Rate limits

API requests are rate-limited to ensure fair usage:
  • Standard tier: 1000 requests per hour
  • Pro tier: 10000 requests per hour
  • Enterprise: Custom limits
Rate limit information is included in response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Response format

All API responses follow a consistent format:

​
Success response

{
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

​
Error response

All endpoints use a consistent error format: 
{
  "success": false,
  "error": "ERROR_MESSAGE_HERE"
}

Error Handling Guide

Learn how to handle errors, implement retry logic, and follow best practices

​
Timezone

All timestamps in API responses are returned according to your brand’s selected timezone. HookPulse supports all IANA timezone identifiers, allowing you to configure your brand’s timezone preference in the dashboard.

​
How it works

  • Brand Timezone: Each brand can set its preferred timezone in the HookPulse dashboard
  • Response Format: All timestamp fields in API responses (e.g., inserted_at, created_at, updated_at, last_run_at) are returned in ISO 8601 format with the timezone offset matching your brand’s selected timezone
  • Timezone Field: Many API responses include a timezone field at the root level indicating the IANA timezone identifier used for the timestamps
  • IANA Support: HookPulse supports all 500+ IANA timezone identifiers (e.g., America/New_York, Europe/London, Asia/Kolkata, UTC)

​
Example

If your brand’s timezone is set to Asia/Kolkata (UTC+5:30), timestamps will be returned like: 
{
  "data": [...],
  "timezone": "Asia/Kolkata",
  "inserted_at": "2026-01-20T21:39:24+05:30"
}
The timezone offset (+05:30) indicates that the timestamp is in your brand’s selected timezone.
You can change your brand’s timezone preference at any time in the HookPulse dashboard. All future API responses will reflect the new timezone setting.

​
HTTP status codes

The API uses standard HTTP status codes:
  • 200 - Success
  • 201 - Created
  • 204 - No Content
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Too Many Requests
  • 500 - Internal Server Error

​
Pagination

List endpoints support page-based pagination using the page query parameter: 
GET /v1/api/get_secrets_paginated/?page=1
Response includes pagination metadata in the meta object: 
{
  "data": [...],
  "meta": {
    "page": 1,
    "total_count": 100,
    "per_page": 20,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  },
  "success": true,
  "timezone": "Asia/Kolkata"
}

​
Pagination Fields

FieldTypeDescription
pageintegerCurrent page number (starts from 1)
total_countintegerTotal number of items across all pages
per_pageintegerNumber of items per page (typically 20)
total_pagesintegerTotal number of pages
has_nextbooleanWhether there is a next page available
has_prevbooleanWhether there is a previous page available

​
Error Handling

If you request a page that doesn’t exist (out of range), you’ll receive an error response: 
{
  "success": false,
  "timezone": "{{timezone}}",
  "error": "Page out of range",
  "meta": {
    "page": {{page}},
    "total_count": {{total_count}},
    "per_page": {{per_page}},
    "total_pages": {{total_pages}},
    "has_next": {{has_next}},
    "has_prev": {{has_prev}}
  }
}

​
Webhooks

Hookpulse supports webhooks for real-time event notifications. See the webhook documentation for setup instructions.