{
  "openapi": "3.0.3",
  "info": {
    "title": "Time Zone and Date Calculator API",
    "version": "1.5.1",
    "description": "Time zone conversion with daylight saving, timestamps, age, countdowns, work experience and cron descriptions. Convert a moment between IANA time zones with daylight saving taken from the platform time zone database (gaps and repeated hours are flagged; next clock change and shared working hours are optional), convert Unix timestamps and ISO dates, calculate age and the span between two dates in years, months and days, count down to or since a date, add up work experience across jobs, and explain a cron expression in plain words. Nothing you send is stored. One X-API-Key header authenticates every call, and the same key works across every FreeDailyPro API. Every 4xx response is documented and none of them is billed.",
    "contact": {
      "name": "FreeDailyPro",
      "url": "https://www.freedailypro.com/developers",
      "email": "support@freedailypro.com"
    },
    "termsOfService": "https://www.freedailypro.com/terms",
    "x-logo": {
      "url": "https://www.freedailypro.com/favicon.ico"
    }
  },
  "servers": [
    {
      "url": "https://api.freedailypro.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer hub, plans and MCP setup",
    "url": "https://www.freedailypro.com/developers"
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "Time Zones & Dates",
      "description": "Time zone conversion with daylight saving, timestamps, age, countdowns, work experience and cron descriptions."
    }
  ],
  "paths": {
    "/v1/security/timestamp": {
      "post": {
        "summary": "Convert a Unix timestamp or ISO date to Unix seconds, milliseconds, ISO and UTC text",
        "operationId": "securityTimestamp",
        "description": "Convert a Unix timestamp or ISO date to Unix seconds, milliseconds, ISO and UTC text. Send JSON with input (required). Returns JSON with unixSeconds, unixMilliseconds, iso, utc. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Time Zones & Dates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "A Unix timestamp (a number or digits; more than 1e12 is read as milliseconds, otherwise seconds) or a date text. ISO 8601 such as 2026-10-30, 2026-10-30T12:00:00Z or 2026-10-30T12:00:00+02:00 is checked part by part: a date that does not exist (2023-02-29, month 13, 25:00) is a 400 ({error, code: 'invalid_timestamp'}) instead of being moved to the next month. Other date formats are read by the JavaScript date parser."
                  }
                },
                "required": [
                  "input"
                ],
                "additionalProperties": false
              },
              "example": {
                "input": "2026-10-30T12:00:00Z"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Timestamp converter client and server side from freedailypro",
                  "unixSeconds": 1793361600,
                  "unixMilliseconds": 1793361600000,
                  "iso": "2026-10-30T12:00:00.000Z",
                  "utc": "Fri, 30 Oct 2026 12:00:00 GMT"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/age": {
      "post": {
        "summary": "Calculate age in years, months and days between two dates",
        "operationId": "convertersAge",
        "description": "Calculate age in years, months and days between two dates. Send JSON with startDate (required); optional: endDate. Returns JSON with years, months, days, totalDays. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Time Zones & Dates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "startDate": {
                    "type": "string"
                  },
                  "endDate": {
                    "type": "string"
                  }
                },
                "required": [
                  "startDate"
                ],
                "additionalProperties": false
              },
              "example": {
                "startDate": "1990-05-17",
                "endDate": "2026-10-30"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Age calculator client and server side from freedailypro",
                  "years": 36,
                  "months": 5,
                  "days": 13,
                  "totalDays": 13315
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/security/cron": {
      "post": {
        "summary": "Explain a cron expression in plain words and validate it",
        "operationId": "securityCron",
        "description": "Explain a cron expression in plain words and validate it. Send JSON with expression (required). Returns JSON with valid, expression, description, fields. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Time Zones & Dates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "A 5-field cron expression: minute (0-59), hour (0-23), day-of-month (1-31), month (1-12 or JAN-DEC), day-of-week (0-7 or SUN-SAT; 0 and 7 are Sunday). Fields accept * , ranges (1-5), lists (1,15), steps (*/5, 10-30/5) and names in any case; '?' is allowed in the two day fields. Macros @yearly @annually @monthly @weekly @daily @midnight @hourly are accepted. Out-of-range values, reversed ranges (5-1), zero steps, empty list items and negative numbers make the expression invalid. The response description reads like 'At 09:00, Monday through Friday'. A valid expression is a 200; an invalid one is a 400 with {error, code: 'invalid_cron', valid: false, expression, fields} naming the first problem."
                  }
                },
                "required": [
                  "expression"
                ],
                "additionalProperties": false
              },
              "example": {
                "expression": "30 9 * * 1-5"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Cron builder client and server side from freedailypro",
                  "valid": true,
                  "expression": "30 9 * * 1-5",
                  "description": "At 30, past 9, on every day of the month, in every month, on 1-5.",
                  "fields": {
                    "minute": "30",
                    "hour": "9",
                    "dayOfMonth": "*",
                    "month": "*",
                    "dayOfWeek": "1-5"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/timezone-offset": {
      "post": {
        "summary": "Apply a UTC offset to a timestamp and return the local time",
        "operationId": "convertersTimezoneOffset",
        "description": "Four request forms are accepted. Fixed offset: {\"utcIso\":\"2026-01-15T12:00:00Z\",\"offset\":\"+05:30\"}. One IANA zone: {\"utcIso\":\"2026-01-15T12:00:00Z\",\"zone\":\"America/New_York\"}. Several zones: {\"utcIso\":\"2026-01-15T12:00:00Z\",\"toZones\":[\"Europe/London\",\"Asia/Kolkata\"]}. A wall-clock time read in a zone: {\"localTime\":\"2026-11-01T01:30\",\"fromZone\":\"America/New_York\",\"toZones\":[\"Europe/London\",\"Asia/Kolkata\"]} (send localTime with fromZone and no utcIso). A body with only some of the fields is a 400 that names what is missing (for example {\"error\":\"utcIso is missing: send utcIso (ISO 8601 UTC timestamp) together with offset, or use zone / toZones.\",\"code\":\"missing_fields\",\"details\":{\"fieldErrors\":{...},\"formErrors\":[],\"issues\":[...],\"examples\":{\"offset\":{...},\"zone\":{...},\"toZones\":{...},\"localTime\":{...}}}}); a timestamp that cannot be read, an offset in the wrong format or an unknown zone is a 400 with code invalid_utc_iso, invalid_offset or unknown_zone and the offending value (cut to 50 characters) in the message. The first version's request (utcIso plus a fixed offset such as +05:30) is unchanged and still returns utc, offset, localIso and localUnixMs; a bad timestamp or offset is now a 400 with the reason (it used to be a 200 carrying an error field). A fixed offset ignores daylight saving, so for real places send IANA zones: 'zone' and/or 'toZones' (up to 10, such as America/New_York or Asia/Kolkata) with the moment as 'utcIso', or as 'localTime' (a wall-clock time such as 2026-11-01T01:30) read in 'fromZone'. Daylight saving comes from the platform's own time zone database, the same code the website converter uses, so the offset in each result is the one in force at that moment. The response then adds 'conversions', one per zone with 'zone', 'name' (a city and country), 'display' (name, the zone's own abbreviation where one exists, and the offset), 'offset' (+05:30), 'offsetMinutes' and 'localIso'. A wall-clock time that does not exist (the clocks jumped forward) or happens twice (they went back) is flagged with 'kind' gap or ambiguous and a 'note'; a skipped time is read with the offset from before the jump and an ambiguous one uses the first occurrence. 'nextChange': true adds to each conversion 'nextClockChange' (the instant, offsets before and after, the change in minutes and a sentence) found to the minute within 400 days, or null for zones that never change (India, UTC, Arizona). 'workStart' and 'workEnd' (hours, default 9 and 17) with two or more zones add 'workingHours': 'windows' lists the runs of hours when every zone is inside working hours on its own clock (from and to are the start of the first and last qualifying hour on the first zone's clock, with startsUtc and endsUtc), and 'text' says it in words. Who calls it: scheduling and booking tools, webinar and interview platforms, remote-team dashboards, calendar integrations and MCP agents. Worked example: {\"localTime\":\"2026-11-01T01:30\",\"fromZone\":\"America/New_York\",\"toZones\":[\"Europe/London\",\"Asia/Kolkata\"]} returns 2026-11-01T05:30:00.000Z with kind ambiguous (New York's clocks go back that night, so 01:30 happens twice), London 05:30 and Mumbai 11:00. Integration scenario: a booking page shows a visitor in Mumbai the slot a New York host offered, and uses workingHours to suggest only times that fall inside both people's working day. Zone data is only as current as the server's time zone database; a rule a government changed recently may be missing until it is updated. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Time Zones & Dates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "utcIso": {
                    "description": "The moment as a UTC timestamp, such as 2026-10-30T12:00:00Z. Required unless localTime and fromZone are sent.",
                    "type": "string"
                  },
                  "offset": {
                    "description": "A fixed offset such as +05:30 or -08:00 (the first version's request). Use zone for a real time zone with daylight saving.",
                    "type": "string"
                  },
                  "zone": {
                    "description": "An IANA time zone such as America/New_York. Daylight saving is handled from the platform's own time zone database.",
                    "type": "string"
                  },
                  "toZones": {
                    "description": "More IANA zones to convert the same moment to (up to 10, together with zone).",
                    "maxItems": 10,
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "localTime": {
                    "description": "A wall-clock time such as 2026-11-01T01:30, read in fromZone. A time the clocks skip or repeat is detected and explained.",
                    "type": "string"
                  },
                  "fromZone": {
                    "description": "The IANA zone localTime is read in.",
                    "type": "string"
                  },
                  "nextChange": {
                    "description": "Add, for every zone, the next time its clocks change (to the minute) or null when they do not.",
                    "type": "boolean"
                  },
                  "workStart": {
                    "description": "Start of working hours (default 9). With workEnd, returns the hours when every zone is at work.",
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 23
                  },
                  "workEnd": {
                    "description": "End of working hours (default 17).",
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 24
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "utcIso": "2026-10-30T12:00:00Z",
                "offset": "+05:30"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Timezone converter client and server side from freedailypro",
                  "utc": "2026-10-30T12:00:00.000Z",
                  "offset": "+05:30",
                  "localIso": "2026-10-30T17:30:00",
                  "localUnixMs": 1793381400000
                }
              }
            }
          },
          "400": {
            "description": "Body: {error, code, details: {fieldErrors, formErrors, issues, examples}}. code is missing_fields (the message names the missing field, for example utcIso or offset, and details.examples shows the four accepted request forms), invalid_utc_iso (timestamp cannot be read), invalid_offset (use +05:30 or -08:00), unknown_zone (not an IANA name), invalid_local_time, or invalid_timezone_input (localTime with utcIso, workStart not before workEnd, working hours with fewer than two zones); the offending value is shown cut to 50 characters Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/job-experience": {
      "post": {
        "summary": "Calculate the years and months between a start and end date",
        "operationId": "convertersJobExperience",
        "description": "Calculate the years and months between a start and end date. Send JSON with startIso (required); optional: endIso, otherJobs, countEndDate. Returns JSON with years, months, totalMonths, label (inside result). Limits: otherJobs: up to 50 items. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Time Zones & Dates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "startIso": {
                    "type": "string"
                  },
                  "endIso": {
                    "type": "string"
                  },
                  "otherJobs": {
                    "description": "More jobs. When given, the top-level years, months and label are the TOTAL across all jobs (overlapping periods counted once; the first job alone is in `firstJob`), and the response also has a `history` object: each job's length, the total, and the gaps between jobs.",
                    "maxItems": 50,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "startIso": {
                          "type": "string"
                        },
                        "endIso": {
                          "description": "YYYY-MM-DD. Leave out for a job that is still going on (today is used).",
                          "type": "string"
                        }
                      },
                      "required": [
                        "startIso"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "countEndDate": {
                    "description": "Only used with otherJobs. true (default) counts the end date as a full day, so 1 Jan to 31 Dec is one year.",
                    "type": "boolean"
                  }
                },
                "required": [
                  "startIso"
                ],
                "additionalProperties": false
              },
              "example": {
                "startIso": "2018-03-01",
                "endIso": "2026-10-20"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Job experience calculator client and server side from freedailypro",
                  "result": {
                    "years": 8,
                    "months": 7,
                    "totalMonths": 103,
                    "label": "8 years 7 months"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/countdown": {
      "post": {
        "summary": "Count the days, hours and minutes until or since a date",
        "operationId": "convertersCountdown",
        "description": "Count the days, hours and minutes until or since a date. Send JSON with isoTarget (required); optional: fromIso. Returns JSON with past, days, hours, minutes, seconds, totalMs, label (inside result). Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Time Zones & Dates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "isoTarget": {
                    "type": "string"
                  },
                  "fromIso": {
                    "type": "string"
                  }
                },
                "required": [
                  "isoTarget"
                ],
                "additionalProperties": false
              },
              "example": {
                "isoTarget": "2026-12-25",
                "fromIso": "2026-10-20"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Countdown calculator client and server side from freedailypro",
                  "result": {
                    "past": false,
                    "days": 66,
                    "hours": 0,
                    "minutes": 0,
                    "seconds": 0,
                    "totalMs": 5702400000,
                    "label": "66d 0h 0m"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    }
  }
}