> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookpulse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API documentation for Hookpulse

## 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`).

<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/openapi.json">
  Download the complete OpenAPI specification file
</Card>

## 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:

```bash theme={null}
x-hookpulse-api-key: YOUR_API_KEY
x-brand-uuid: YOUR_BRAND_UUID
```

<Warning>
  **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.
</Warning>

### Getting your credentials

#### Brand UUID (`x-brand-uuid`)

1. Log in to your [Hookpulse dashboard](https://hookpulse.io/signin)
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](https://hookpulse.io/signin)
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

<Note>
  Both the API key and brand UUID are required for all API requests. Make sure to include both headers in every request.
</Note>

## 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

```json theme={null}
{
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

### Error response

All endpoints use a consistent error format:

```json theme={null}
{
  "success": false,
  "error": "ERROR_MESSAGE_HERE"
}
```

<Card title="Error Handling Guide" icon="exclamation-triangle" href="/api-reference/error-handling">
  Learn how to handle errors, implement retry logic, and follow best practices
</Card>

## 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:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

## 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:

```bash theme={null}
GET /v1/api/get_secrets_paginated/?page=1
```

Response includes pagination metadata in the `meta` object:

```json theme={null}
{
  "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

| Field         | Type    | Description                                |
| ------------- | ------- | ------------------------------------------ |
| `page`        | integer | Current page number (starts from 1)        |
| `total_count` | integer | Total number of items across all pages     |
| `per_page`    | integer | Number of items per page (typically 20)    |
| `total_pages` | integer | Total number of pages                      |
| `has_next`    | boolean | Whether there is a next page available     |
| `has_prev`    | boolean | Whether 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:

```json theme={null}
{
  "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](/api-reference/endpoint/webhook) for setup instructions.