Built-in tool
Date Time
Get the current time, offset/format/diff timestamps, or parse phrases like "tomorrow" or "next Monday".
Endpoint
Parameters
| Name | Type | Required | Note |
|---|---|---|---|
| actionstring · required | string | required | Date/time operation to perform. now: return current UTC time in ISO 8601, unix seconds, and human-readable formats. add: add N units to a timestamp (defaults to now if timestamp omitted). subtract: subtract N units from a timestamp (defaults to now if timestamp omitted). format: convert a timestamp to a specific output format. diff: compute the signed difference between two timestamps in the requested unit (timestamp2 − timestamp). parse: convert a natural language date expression into a concrete timestamp. One of: |
| unitstring · optional | string | optional | Time unit to use with add, subtract, or diff actions. Required for add and subtract. Optional for diff (defaults to hours). Months are calendar months (28–31 days); all other units are fixed-duration. One of: |
| inputstring · optional | string | optional | Natural language date expression for the parse action. Supported values: "today", "tomorrow", "yesterday", "next monday" (or any weekday name), "start of week", "end of week", "start of month", "end of month", "N days ago" (e.g. "3 days ago"), "N days from now" (e.g. "7 days from now"), "N hours ago", "N hours from now", "N weeks ago", "N weeks from now". All relative expressions are evaluated against the current UTC time. Example: |
| amountnumber · optional | number | optional | Number of units to add or subtract. Required for the add and subtract actions. May be fractional (e.g. 1.5 hours). Negative values are accepted but prefer the subtract action for clarity. Example: |
| timezonestring · optional | string | optional | IANA timezone name for display purposes (e.g. "America/New_York", "Europe/London", "Asia/Tokyo"). Affects the human and date-only/time-only output formats. All internal computation is always UTC. Defaults to UTC when omitted. |
| timestampstring · optional | string | optional | ISO 8601 input timestamp (e.g. "2024-06-15T14:30:00Z"). For now/add/subtract, defaults to the current UTC time when omitted. For format/diff, required. Example: |
| timestamp2string · optional | string | optional | Second ISO 8601 timestamp for the diff action. The result is timestamp2 − timestamp, so a positive result means timestamp2 is later. Required when action is diff. |
| outputFormatstring · optional | string | optional | Output format for the format action. ISO: ISO 8601 string with UTC offset (e.g. "2024-06-15T14:30:00.000Z"). unix: Unix epoch in whole seconds (integer). human: human-readable string (e.g. "Saturday, June 15, 2024, 2:30 PM UTC"). date-only: YYYY-MM-DD (e.g. "2024-06-15"). time-only: HH:MM:SS in UTC (e.g. "14:30:00"). One of: |
Response schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"success",
"result"
],
"properties": {
"iso": {
"type": "string",
"description": "ISO 8601 UTC representation of the result timestamp."
},
"unix": {
"type": "number",
"description": "Unix epoch (whole seconds) of the result timestamp."
},
"error": {
"type": "string"
},
"result": {
"type": [
"string",
"number"
],
"description": "Primary result value. String for most formats, number for unix and diff actions."
},
"success": {
"type": "boolean"
},
"formatted": {
"type": "string",
"description": "Human-readable version of the result timestamp when available."
}
},
"additionalProperties": false
}
