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

# HookPulse Documentation

> Enterprise-grade serverless task scheduling infrastructure for modern developers

# HookPulse Overview

## What is HookPulse?

**HookPulse** is a production-ready, enterprise-grade serverless task scheduling infrastructure designed for modern developers building AI agents, event-driven systems, and SaaS applications. Built on **Elixir/OTP** for unmatched reliability and performance, HookPulse eliminates the need to build and maintain complex scheduling infrastructure like Celery, Redis, or Sidekiq.

### The Problem We Solve

Building reliable task scheduling infrastructure is hard. Most developers end up:

* Spending 20+ hours/month maintaining Redis, Celery, or Sidekiq workers
* Dealing with infrastructure complexity, scaling issues, and reliability concerns
* Paying high costs for self-hosted solutions (often 95% more expensive)
* Struggling with timezone handling, precise timing, and concurrency management

**HookPulse solves all of this** with a simple HTTP API that works with any programming language.

***

## Core Capabilities

### 🎯 **Precise Webhook & API Scheduling**

Schedule webhooks and API calls with **millisecond precision** using multiple scheduling strategies:

* **Interval Scheduling**: Run tasks every X seconds, minutes, hours, days, weeks, or months
* **Cron Scheduling**: Industry-standard cron expressions with IANA timezone support (500+ timezones)
* **Solar Scheduling**: Trigger tasks at sunrise, sunset, or other solar events using geographic coordinates
* **Clocked Scheduling**: One-time scheduled executions at specific dates/times
* **Debounce Scheduling**: Prevent rapid-fire executions with configurable debounce logic
* **Schedule Rules**: Advanced rule engine with time windows, calendar windows, exclusions, and termination conditions

**See [Scheduling Overview](/docs/api-reference/scheduling/overview)** for complete documentation.

### 🔄 **Advanced Workflow Orchestration**

Build complex, multi-step workflows with enterprise features:

* **Visual Workflow Builder**: Drag-and-drop interface for creating workflows
* **FIFO Sequential Mode**: Strict First-In-First-Out ordering for critical workflows with full variable support
* **Concurrent Mode**: Parallel execution for independent operations
* **Conditional Execution**: Route execution based on field values and operators (eq, ne, lt, gt, lte, gte, in, contains)
* **Failure Handling**: Stop on failure or continue execution with configurable retry strategies
* **Retry Strategies**: Retry from initial step or resume from failed step
* **Human Approval**: Pause workflows for manual approval steps with native support
* **Template Variables**: Dynamic variable substitution with system secrets (`{{ #key }}`), step responses (`{{ step.response.variable }}`), and initial context (`{{ initial.variable }}`)

**See [Workflow Template Overview](/docs/api-reference/workflow-template/overview)** for complete documentation.

### 🛡️ **Enterprise-Grade Features**

**Traffic Guard Layer** - Protect your infrastructure with built-in controls:

* **Rate Limiting**: Set max requests per second per domain (configurable on/off)
* **Concurrency Control**: Limit simultaneous executions to prevent overload (configurable on/off)
* **Domain Management**: Separate API to handle concurrency and rate limiting per domain
* **Backpressure Logic**: Automatically pause queues when limits are hit
* **Idempotency Keys**: Prevent duplicate executions from network retries

**See [Domain Setup Overview](/docs/api-reference/domain-setup/overview)** for complete documentation.

### 🔐 **System Secret Vault**

Enterprise-grade secret management for secure operations:

* **Encrypted Storage**: All secrets encrypted at rest using AES-256
* **Runtime Injection**: Secrets computed at execution time, never exposed in logs
* **Template Integration**: Use secrets in webhook/workflow templates with `{{ #key }}` syntax
* **Audit Trail**: Complete logging of secret access and usage
* **CRUD Operations**: Full API for adding, updating, retrieving, and deleting secrets

**See [System Secret Vault Overview](/docs/api-reference/system-secret-vault/overview)** for complete documentation.

### 📋 **Webhook Templates**

Reusable webhook configurations for efficient development:

* **Template System**: Create once, use many times with different variables
* **Variable Support**: Use `{{ variable }}` for dynamic values and `{{ #key }}` for system secrets
* **Reusability**: Use with webhook UUID in schedules and workflows
* **Visual Dashboard**: Create templates with visual tools in the dashboard or via API
* **Full CRUD**: Create, retrieve, update, and delete webhook templates via API

**See [Webhook Template Overview](/docs/api-reference/webhook-template/overview)** for complete documentation.

### 👥 **Human Approval Workflows**

Built-in human approval for critical workflow steps:

* **Native Support**: Pause workflows at any step for manual approval
* **Approval Dashboard**: View all pending approvals in one place
* **Approve/Reject Actions**: Simple API to approve or reject pending workflows
* **Automatic Resumption**: Workflows automatically continue after approval
* **Failure Path Routing**: Rejected workflows can route to failure paths

**See [Human Approval Overview](/docs/api-reference/human-approval/overview)** for complete documentation.

### 🌍 **Multi-Timezone Support**

* Full **IANA timezone** support (500+ timezones)
* **Timezone API**: Get complete list of all available timezones
* Automatic timezone conversion for all scheduled times
* Timezone-aware scheduling for global applications
* Automatic DST (Daylight Saving Time) handling

**See [Get Timezone Options](/docs/api-reference/scheduling/timezone-options)** for complete timezone list.

***

## Why Choose HookPulse?

### 🚀 **Save Development Time**

Stop spending 20+ hours/month maintaining scheduling infrastructure. Focus on building your product instead.

### 💰 **Cost Effective**

95% cheaper than self-hosting. Pay only for what you use with transparent, pay-as-you-go pricing.

### 🔧 **No Infrastructure**

No Redis, no Celery workers, no message queues to manage. Just HTTP API calls.

### 📈 **Scalable**

Built on Elixir/OTP for horizontal scaling. Handles millions of scheduled tasks without breaking a sweat.

### 🎯 **Production Ready**

Enterprise-grade features out of the box: rate limiting, concurrency control, FIFO queues, and idempotency.

### 🌐 **Global Ready**

Multi-timezone support with IANA timezone database. Perfect for global applications.

***

## Use Cases

### 🤖 **AI Agent Orchestration**

Schedule AI agent tasks, coordinate multi-agent workflows, and manage agent execution pipelines with precise timing and conditional logic.

### 📡 **Event-Driven Architectures**

Build event-driven systems with scheduled webhooks, delayed processing, and event coordination across multiple services.

### 🔔 **Notification Systems**

Send scheduled notifications, reminders, and alerts with timezone-aware scheduling and retry logic.

### 📊 **Data Processing Pipelines**

Process data on schedules, coordinate ETL jobs, and manage batch processing workflows.

### 🔄 **API Automation**

Automate API calls, sync data between services, and coordinate third-party integrations.

### 💼 **SaaS Applications**

Add scheduling capabilities to SaaS products without building infrastructure from scratch.

***

## Getting Started

1. **Sign Up**: Create an account at [hookpulse.io](https://hookpulse.io)
2. **Add a Brand**: Create a brand in your dashboard to get your brand UUID
3. **Get API Key**: Select your brand and generate an API key from the API Keys section
4. **Make Your First Request**: Schedule a webhook in under 5 minutes using both credentials
5. **Build Workflows**: Create complex workflows with our visual builder
6. **Scale**: Handle millions of scheduled tasks with confidence

***

## Need Help?

For support, questions, or assistance:

* **Email**: [care@hookpulse.io](mailto:care@hookpulse.io)
* **Phone**: +91 8076445044

Our support team is here to help you succeed with HookPulse.

***

# API Reference

## Overview

Welcome to the HookPulse API reference. This comprehensive documentation provides detailed information about all available endpoints, request/response formats, authentication methods, and best practices.

The HookPulse API is **RESTful** and uses **JSON** for all request and response payloads. All API requests must be authenticated using custom headers (`x-hookpulse-api-key` and `x-brand-uuid`). Built on **Elixir/OTP** for enterprise-grade reliability, the HookPulse API delivers 99.9% uptime SLA and handles millions of scheduled tasks effortlessly.

<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/openapi.json">
  Download the complete OpenAPI 3.0.3 specification file with all endpoints and schemas
</Card>

<Card title="Interactive API Playground" icon="play" href="/api-reference/domain-setup/add-domain">
  Try API calls directly in your browser with our interactive playground
</Card>

## API Sections

HookPulse provides comprehensive APIs organized into logical sections:

### 🔐 **System Secret Vault**

Enterprise-grade secret management with encrypted storage and runtime injection. Store API keys, tokens, and sensitive data securely.

* [System Secret Vault Overview](/docs/api-reference/system-secret-vault/overview)
* Add, retrieve, update, and delete secrets via API
* Use secrets in templates with `{{ #key }}` syntax

### 🌐 **Domain Setup**

Manage domains with rate limiting and concurrency control to protect your infrastructure.

* [Domain Setup Overview](/docs/api-reference/domain-setup/overview)
* Add domains with configurable rate limits and concurrency controls
* Retrieve domain information and UUIDs

### 📋 **Webhook Templates**

Create reusable webhook configurations with variable support and system secret integration.

* [Webhook Template Overview](/docs/api-reference/webhook-template/overview)
* Create, retrieve, update, and delete webhook templates
* Use templates in schedules and workflows

### 🔄 **Workflow Templates**

Build complex multi-step workflows with conditional execution, human approval, and advanced orchestration.

* [Workflow Template Overview](/docs/api-reference/workflow-template/overview)
* Create workflows with FIFO sequential or concurrent execution
* Add workflow steps with execution conditions
* Human approval support at any workflow step

### ⏰ **Scheduling**

Comprehensive scheduling API supporting interval, cron, clocked, solar, and debounce scheduling with advanced rule engine.

* [Scheduling Overview](/docs/api-reference/scheduling/overview)
* Get all available timezones (500+ IANA timezones)
* Create schedules with interval, cron, clocked, or solar timing
* Add schedule rules for time windows, exclusions, and termination
* Manage schedule status and retrieve schedule details

### 👥 **Human Approval**

Native human approval workflows with API support for managing pending approvals.

* [Human Approval Overview](/docs/api-reference/human-approval/overview)
* Get all pending approvals (paginated)
* Approve or reject pending workflow steps

### 📊 **Error Handling**

Consistent error handling across all endpoints with unified error response format.

* [Error Handling Guide](/docs/api-reference/error-handling)

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

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

Most list endpoints support pagination using `page` query parameter (1-based):

```bash theme={null}
GET https://api.hookpulse.io/v1/api/get_domain_paginated/?page=1
```

<Note>
  The base URL is `https://api.hookpulse.io`. All endpoints are prefixed with `/v1/api/` and include trailing slashes.
</Note>

Response includes pagination metadata:

```json theme={null}
{
  "data": [...],
  "meta": {
    "page": 1,
    "total_count": 100,
    "per_page": 20,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  },
  "success": true
}
```

## Code Examples

All API endpoints include code examples in multiple languages:

* **cURL**: Command-line examples for quick testing
* **JavaScript/TypeScript**: Modern JavaScript with fetch API
* **Python**: Using the `requests` library
* **Ruby**: Using `Net::HTTP` and `JSON`
* **PHP**: Using `curl` functions

<Card title="Multi-Language Support" icon="code">
  HookPulse works with any programming language that supports HTTP. All examples are provided in 5+ languages for easy integration.
</Card>

## Template Variables

HookPulse supports powerful template variables across webhook templates and workflow steps:

### System Secrets

Use `{{ #key }}` to inject secrets from the System Secret Vault at runtime:

```json theme={null}
{
  "headers": {
    "Authorization": "Bearer {{ #api_key }}"
  }
}
```

### Workflow Step Responses

Use `{{ step.response.variable }}` to access responses from previous workflow steps:

```json theme={null}
{
  "body": {
    "user_id": "{{ step.response.user_id }}"
  }
}
```

### Initial Context

Use `{{ initial.variable }}` to access variables passed when scheduling:

```json theme={null}
{
  "body": {
    "report_type": "{{ initial.report_type }}"
  }
}
```

**See individual overview pages** for detailed documentation on template variables.

## Best Practices

<Card title="API Best Practices" icon="lightbulb">
  * Always handle errors gracefully using the unified error format
  * Implement retry logic for transient failures
  * Use pagination for list endpoints
  * Store secrets in System Secret Vault instead of hardcoding
  * Use webhook/workflow templates for reusability
  * Set appropriate rate limits and concurrency controls per domain
</Card>