---
title: "Preview a business calendar"
method: POST
path: "/calendars/{name}/preview"
tags: ["dags"]
---

# Preview a business calendar

`POST /calendars/{name}/preview`

## Request

- Base URL: `http://localhost/api/v1`
- URL: `http://localhost/api/v1/calendars/{name}/preview`
- Auth: one of:
  - HTTP bearer
  - HTTP basic
  - none

Checks unsaved calendar content and describes each date of a year under it, marking the dates that differ from the saved calendar. A built-in calendar is described as it is.

## Path parameters

- `name` string, required: Name of a business calendar: a built-in one, or the file <name>.yaml in paths.calendars_dir

## Query parameters

- `remoteNode` string

## Request body

- CalendarPreviewRequest
  - `spec` string, required: Unsaved calendar file content; ignored for a built-in calendar
  - `year` integer, required: Year whose dates are described

## Response `200`

The preview

- CalendarPreview: Unsaved calendar content checked and applied to the dates of a year
  - `errors` string[], required: Problems of the content, each starting with its [line:column] when it has one. The dates use the valid parts.
  - `warnings` string[], required
  - `year` integer, required
  - `today` string, date, required: Today in the server's time zone
  - `through` string, date: Last date the content's holidays are maintained for
  - `days` CalendarDay[], required: Each date of the year, in order. Empty when the content is not a calendar document.
    - `date` string, date, required
    - `status` 'business' | 'nonBusiness' | 'holiday' | 'extraBusinessDay', required: business: a business day by its weekday; nonBusiness: a weekday that is not a business day; holiday: a listed holiday; extraBusinessDay: a business day only because the calendar lists it
    - `holidayName` string: Name of the holiday listed on the date
    - `ordinal` integer: Position among the month's business days, where 1 is the first. Set on business days only.
    - `ordinalFromEnd` integer: Position among the month's business days from the end, where -1 is the last. Set on business days only.
    - `changed` boolean, required: Whether the saved calendar describes the date differently
  - `changes` CalendarChanges, required: How unsaved content differs from the saved calendar
    - `weekdaysAdded` CalendarWeekday[], required
    - `weekdaysRemoved` CalendarWeekday[], required
    - `dates` CalendarDateChange[], required: Listed dates, in order, whose status or holiday name changes
      - `date` string, date, required
      - `before` 'business' | 'nonBusiness' | 'holiday' | 'extraBusinessDay', required: business: a business day by its weekday; nonBusiness: a weekday that is not a business day; holiday: a listed holiday; extraBusinessDay: a business day only because the calendar lists it
      - `after` 'business' | 'nonBusiness' | 'holiday' | 'extraBusinessDay', required: business: a business day by its weekday; nonBusiness: a weekday that is not a business day; holiday: a listed holiday; extraBusinessDay: a business day only because the calendar lists it
      - `beforeHolidayName` string
      - `afterHolidayName` string

## Other responses

- `default`: Unexpected error

## Changes

> 208 revisions in range; 1 not diffed.

- **2026-11-01** (v1) `d6b5f3398212`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/dagucloud/apis/dagu/changes/calendars/:name/preview/post.md)

---

[API](https://skmtc.dev/dagucloud/apis/dagu.md) - [All operations](https://skmtc.dev/dagucloud/apis/dagu/llms.txt) - [OpenAPI document](https://skmtc.dev/dagucloud/apis/dagu/revisions/742c8ecb39ce?raw)