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

# Add Schedule Rule

> Add a rule to an existing schedule to control execution conditions, exclusions, and termination criteria

Add a rule to an existing schedule to control execution conditions, exclusions, and termination criteria. Rules allow you to create complex scheduling patterns with time windows, calendar restrictions, exclusions, and automatic termination.

## Base URL

All API requests should be made to:

```
https://api.hookpulse.io
```

## Example request

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.hookpulse.io/v1/api/add_schedule_rule/" \
    -H "x-hookpulse-api-key: {{x-hookpulse-api-key}}" \
    -H "x-brand-uuid: {{x-brand-uuid}}" \
    -H "Content-Type: application/json" \
    -d '{
      "schedule_uuid": "{{schedule_uuid}}",
      "rule_type": "{{rule_type}}",
      "start_time": "{{start_time}}",
      "end_time": "{{end_time}}",
      "timezone": "{{timezone}}",
      "allow_days": {{allow_days}},
      "allow_months": {{allow_months}},
      "exclusion_dates": {{exclusion_dates}},
      "solar_start_event": "{{solar_start_event}}",
      "solar_end_event": "{{solar_end_event}}",
      "solar_lat": "{{solar_lat}}",
      "solar_long": "{{solar_long}}",
      "max_run_to_terminate_after": {{max_run_to_terminate_after}},
      "expire_at": {{expire_at}}
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.hookpulse.io/v1/api/add_schedule_rule/', {
    method: 'POST',
    headers: {
      'x-hookpulse-api-key': '{{x-hookpulse-api-key}}',
      'x-brand-uuid': '{{x-brand-uuid}}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      schedule_uuid: '{{schedule_uuid}}',
      rule_type: '{{rule_type}}',
      start_time: '{{start_time}}',
      end_time: '{{end_time}}',
      timezone: '{{timezone}}',
      allow_days: {{allow_days}},
      allow_months: {{allow_months}},
      exclusion_dates: {{exclusion_dates}},
      solar_start_event: '{{solar_start_event}}',
      solar_end_event: '{{solar_end_event}}',
      solar_lat: '{{solar_lat}}',
      solar_long: '{{solar_long}}',
      max_run_to_terminate_after: {{max_run_to_terminate_after}},
      expire_at: {{expire_at}}
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = 'https://api.hookpulse.io/v1/api/add_schedule_rule/'
  headers = {
      'x-hookpulse-api-key': '{{x-hookpulse-api-key}}',
      'x-brand-uuid': '{{x-brand-uuid}}',
      'Content-Type': 'application/json'
  }
  payload = {
      'schedule_uuid': '{{schedule_uuid}}',
      'rule_type': '{{rule_type}}',
      'start_time': '{{start_time}}',
      'end_time': '{{end_time}}',
      'timezone': '{{timezone}}',
      'allow_days': {{allow_days}},
      'allow_months': {{allow_months}},
      'exclusion_dates': {{exclusion_dates}},
      'solar_start_event': '{{solar_start_event}}',
      'solar_end_event': '{{solar_end_event}}',
      'solar_lat': '{{solar_lat}}',
      'solar_long': '{{solar_long}}',
      'max_run_to_terminate_after': {{max_run_to_terminate_after}},
      'expire_at': {{expire_at}}
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  uri = URI('https://api.hookpulse.io/v1/api/add_schedule_rule/')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['x-hookpulse-api-key'] = '{{x-hookpulse-api-key}}'
  request['x-brand-uuid'] = '{{x-brand-uuid}}'
  request['Content-Type'] = 'application/json'
  request.body = {
    schedule_uuid: '{{schedule_uuid}}',
    rule_type: '{{rule_type}}',
    start_time: '{{start_time}}',
    end_time: '{{end_time}}',
    timezone: '{{timezone}}',
    allow_days: {{allow_days}},
    allow_months: {{allow_months}},
    exclusion_dates: {{exclusion_dates}},
    solar_start_event: '{{solar_start_event}}',
    solar_end_event: '{{solar_end_event}}',
    solar_lat: '{{solar_lat}}',
    solar_long: '{{solar_long}}',
    max_run_to_terminate_after: {{max_run_to_terminate_after}},
    expire_at: {{expire_at}}
  }.to_json

  response = http.request(request)
  puts JSON.parse(response.body)
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api.hookpulse.io/v1/api/add_schedule_rule/";
  $data = [
      'schedule_uuid' => '{{schedule_uuid}}',
      'rule_type' => '{{rule_type}}',
      'start_time' => '{{start_time}}',
      'end_time' => '{{end_time}}',
      'timezone' => '{{timezone}}',
      'allow_days' => {{allow_days}},
      'allow_months' => {{allow_months}},
      'exclusion_dates' => {{exclusion_dates}},
      'solar_start_event' => '{{solar_start_event}}',
      'solar_end_event' => '{{solar_end_event}}',
      'solar_lat' => '{{solar_lat}}',
      'solar_long' => '{{solar_long}}',
      'max_run_to_terminate_after' => {{max_run_to_terminate_after}},
      'expire_at' => {{expire_at}}
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-hookpulse-api-key: {{x-hookpulse-api-key}}',
      'x-brand-uuid: {{x-brand-uuid}}',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```
</RequestExample>

## Request body

| Field                        | Type           | Required    | Description                                                                                             |
| ---------------------------- | -------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `schedule_uuid`              | string         | Yes         | UUID of the schedule to add the rule to                                                                 |
| `rule_type`                  | string         | Yes         | Type of rule: `"time_window"`, `"calendar_window"`, `"solar_window"`, `"exclusion"`, or `"termination"` |
| `start_time`                 | string         | Conditional | Start time for time window rules (format: `"HH:mm:ss"`)                                                 |
| `end_time`                   | string         | Conditional | End time for time window rules (format: `"HH:mm:ss"`)                                                   |
| `timezone`                   | string         | Conditional | Timezone for time window rules (IANA timezone identifier)                                               |
| `allow_days`                 | array          | Conditional | Array of day numbers (1-31) for calendar window rules                                                   |
| `allow_months`               | array          | Conditional | Array of month numbers (1-12) for calendar window rules                                                 |
| `exclusion_dates`            | array          | Conditional | Array of dates to exclude (format: `"YYYY-MM-DD"`) for exclusion rules                                  |
| `solar_start_event`          | string         | Conditional | Solar event for start of solar window (e.g., `"sunrise"`, `"sunset"`)                                   |
| `solar_end_event`            | string         | Conditional | Solar event for end of solar window                                                                     |
| `solar_lat`                  | string         | Conditional | Latitude for solar window rules (decimal degrees)                                                       |
| `solar_long`                 | string         | Conditional | Longitude for solar window rules (decimal degrees)                                                      |
| `max_run_to_terminate_after` | integer        | Conditional | Maximum number of runs before termination (for termination rules)                                       |
| `expire_at`                  | string \| null | Conditional | ISO 8601 datetime when schedule should expire (for termination rules)                                   |

## Example response

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "details": "Schedule rule added successfully"
  }
  ```
</ResponseExample>

## Response fields

| Field     | Type    | Description                                  |
| --------- | ------- | -------------------------------------------- |
| `success` | boolean | Indicates if the rule was added successfully |
| `details` | string  | Success message                              |

## Rule Types

### 1. Time Window Rule

Restrict execution to specific time ranges:

**Required Fields:**

* `rule_type`: `"time_window"`
* `start_time`: Start time (e.g., `"09:00:00"`)
* `end_time`: End time (e.g., `"17:00:00"`)
* `timezone`: IANA timezone identifier

**Example:**

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "time_window",
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "timezone": "America/New_York",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### 2. Calendar Window Rule

Restrict execution to specific days and months:

**Required Fields:**

* `rule_type`: `"calendar_window"`
* `allow_days`: Array of day numbers (1-31), e.g., `[1, 15]` for 1st and 15th
* `allow_months`: Array of month numbers (1-12), optional

**Example:**

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "calendar_window",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [1, 15],
  "allow_months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### 3. Solar Window Rule

Restrict execution to solar event windows:

**Required Fields:**

* `rule_type`: `"solar_window"`
* `solar_start_event`: Solar event for start (e.g., `"civil_dawn"`)
* `solar_end_event`: Solar event for end (e.g., `"civil_dusk"`)
* `solar_lat`: Latitude in decimal degrees
* `solar_long`: Longitude in decimal degrees

**Example:**

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "solar_window",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "civil_dawn",
  "solar_end_event": "civil_dusk",
  "solar_lat": "40.7128",
  "solar_long": "-74.0060",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### 4. Exclusion Rule

Exclude specific dates from execution:

**Required Fields:**

* `rule_type`: `"exclusion"`
* `exclusion_dates`: Array of dates in `"YYYY-MM-DD"` format

**Example:**

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "exclusion",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": ["2024-12-25", "2025-01-01"],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### 5. Termination Rule

Automatically stop schedule after conditions are met:

**Required Fields:**

* `rule_type`: `"termination"`
* Either `max_run_to_terminate_after` OR `expire_at` (or both)

**Example (Max Runs):**

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "termination",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": 100,
  "expire_at": null
}
```

**Example (Expiration Date):**

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "termination",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": "2025-12-31T23:59:59Z"
}
```

**Example (Both):**

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "termination",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": 5,
  "expire_at": null
}
```

## Solar Event Options

For solar window rules, valid solar events are:

* `"sunrise"` - When the sun appears above the horizon
* `"sunset"` - When the sun disappears below the horizon
* `"civil_dawn"` - Morning when the sun is 6° below the horizon
* `"civil_dusk"` - Evening when the sun is 6° below the horizon
* `"nautical_dawn"` - Morning when the sun is 12° below the horizon
* `"nautical_dusk"` - Evening when the sun is 12° below the horizon
* `"astronomical_dawn"` - Morning when the sun is 18° below the horizon
* `"astronomical_dusk"` - Evening when the sun is 18° below the horizon

## Use Cases

* **Business Hours**: Use time window rules to execute only during business hours
* **Monthly Billing**: Use calendar window rules to execute on specific days (e.g., 1st and 15th)
* **Holiday Exclusions**: Use exclusion rules to skip execution on holidays
* **Daylight Operations**: Use solar window rules for operations that should only run during daylight
* **Limited Runs**: Use termination rules to automatically stop after N executions
* **Temporary Schedules**: Use expiration rules to automatically stop schedules at specific dates

## Examples

### Business Hours Only (Time Window)

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "time_window",
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "timezone": "America/New_York",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### Monthly on 1st and 15th (Calendar Window)

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "calendar_window",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [1, 15],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### Exclude Holidays (Exclusion)

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "exclusion",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": ["2024-12-25", "2025-01-01", "2025-07-04"],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### Daylight Hours Only (Solar Window)

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "solar_window",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "civil_dawn",
  "solar_end_event": "civil_dusk",
  "solar_lat": "40.7128",
  "solar_long": "-74.0060",
  "max_run_to_terminate_after": null,
  "expire_at": null
}
```

### Stop After 100 Runs (Termination)

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "termination",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": 100,
  "expire_at": null
}
```

### Expire at Year End (Termination)

```json theme={null}
{
  "schedule_uuid": "{{schedule_uuid}}",
  "rule_type": "termination",
  "start_time": "",
  "end_time": "",
  "timezone": "",
  "allow_days": [],
  "allow_months": [],
  "exclusion_dates": [],
  "solar_start_event": "",
  "solar_end_event": "",
  "solar_lat": "",
  "solar_long": "",
  "max_run_to_terminate_after": null,
  "expire_at": "2025-12-31T23:59:59Z"
}
```

## Related Documentation

* [Scheduling Overview](/docs/api-reference/scheduling/overview) - Learn about scheduling types and rule engine
* [Add Interval Schedule](/docs/api-reference/scheduling/add-interval-schedule) - Create interval-based schedules
* [Add Cron Schedule](/docs/api-reference/scheduling/add-cron-schedule) - Create cron-based schedules
* [Get Active Schedules (Paginated)](/docs/api-reference/scheduling/get-schedules-paginated) - View all schedules with filters


## OpenAPI

````yaml POST /v1/api/add_schedule_rule/
openapi: 3.0.3
info:
  title: Hookpulse API
  description: >-
    Complete API documentation for Hookpulse. Build powerful integrations with
    our RESTful API.
  version: 1.0.0
  contact:
    name: Hookpulse Support
    email: care@hookpulse.io
    url: https://hookpulse.io
servers:
  - url: https://api.hookpulse.io
    description: Production server
security:
  - apiKeyAuth: []
    brandUuidAuth: []
paths:
  /v1/api/add_schedule_rule/:
    post:
      description: >-
        Add a rule to an existing schedule to control execution conditions,
        exclusions, and termination criteria
      requestBody:
        description: Schedule rule configuration
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddScheduleRuleRequest'
      responses:
        '200':
          description: Rule added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AddScheduleRuleRequest:
      required:
        - schedule_uuid
        - rule_type
      type: object
      properties:
        schedule_uuid:
          type: string
          description: UUID of the schedule to add the rule to
        rule_type:
          type: string
          enum:
            - time_window
            - calendar_window
            - solar_window
            - exclusion
            - termination
          description: Type of rule
        start_time:
          type: string
          format: time
          description: 'Start time for time window rules (format: HH:mm:ss)'
        end_time:
          type: string
          format: time
          description: 'End time for time window rules (format: HH:mm:ss)'
        timezone:
          type: string
          description: Timezone for time window rules (IANA timezone identifier)
        allow_days:
          type: array
          items:
            type: integer
            minimum: 1
            maximum: 31
          description: Array of day numbers (1-31) for calendar window rules
        allow_months:
          type: array
          items:
            type: integer
            minimum: 1
            maximum: 12
          description: Array of month numbers (1-12) for calendar window rules
        exclusion_dates:
          type: array
          items:
            type: string
            format: date
          description: 'Array of dates to exclude (format: YYYY-MM-DD) for exclusion rules'
        solar_start_event:
          type: string
          enum:
            - sunrise
            - sunset
            - civil_dawn
            - civil_dusk
            - nautical_dawn
            - nautical_dusk
            - astronomical_dawn
            - astronomical_dusk
          description: Solar event for start of solar window
        solar_end_event:
          type: string
          enum:
            - sunrise
            - sunset
            - civil_dawn
            - civil_dusk
            - nautical_dawn
            - nautical_dusk
            - astronomical_dawn
            - astronomical_dusk
          description: Solar event for end of solar window
        solar_lat:
          type: string
          description: Latitude for solar window rules (decimal degrees)
        solar_long:
          type: string
          description: Longitude for solar window rules (decimal degrees)
        max_run_to_terminate_after:
          type: integer
          description: Maximum number of runs before termination (for termination rules)
        expire_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 datetime when schedule should expire (for termination
            rules)
    ScheduleResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the schedule was created successfully
        details:
          type: string
          description: Success message
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-hookpulse-api-key
      description: >-
        API key for authentication. Get this from your dashboard by selecting a
        brand and going to API Keys section.
    brandUuidAuth:
      type: apiKey
      in: header
      name: x-brand-uuid
      description: >-
        Brand UUID for authentication. Get this from your dashboard after adding
        a brand - it will be displayed in the UI.

````