コンテンツへスキップ
POST AI agent ready /v1/date

Natural Language Date API - Parse "tomorrow", "next Monday"

Recognizes "today", "tomorrow", "yesterday", relative phrases ("in 3 days", "2 weeks ago"), weekday phrases ("next Monday", "last Friday"), ISO dates (2025-03-15), MM/DD/YYYY, and month-name formats ("March 15 2025"). Returns ISO date, unix timestamp, day of week, relative description, and confidence (0-1).

Parameters

stringrequired

Date phrase to parse.

string

ISO date or parseable string used as "now". Defaults to current date.

Code examples

curl -X POST https://api.botoi.com/v1/date \
  -H "Content-Type: application/json" \
  -d '{"text":"next Monday","reference_date":"2026-04-15"}'

When to use this API

Add natural-language date input to forms

Calendar widgets are slow. Let users type "next Friday" or "in 2 weeks" and parse to ISO on the server. Falls back to the date picker only when parsing fails.

Parse dates from LLM responses

When an LLM returns "the meeting is tomorrow at 3pm", extract the date portion and pass to this endpoint to normalize before adding to the user's calendar.

Reminder bots

A Slack or email bot takes commands like "remind me in 3 days to review the spec". Parse the time phrase, compute the target timestamp, and schedule the callback.

Frequently asked questions

What time zone are results in?
The response is date-only (no time component). The ISO field is the calendar date in the reference date's local zone. For time-of-day parsing, combine with /v1/timestamp/convert.
Why reference_date?
Relative phrases need an anchor. "Tomorrow" depends on today. For testing or replaying events in the past, pass reference_date to freeze the anchor deterministically.
What format does confidence follow?
0-1 where 1 means unambiguous (exact ISO, "today"). Phrases like "March 15" without a year are at 0.9 because the year is inferred. Ambiguous inputs return an error rather than a low-confidence guess.
Are other languages supported?
English only. Phrases like "mañana" or "demain" are not recognized. For multilingual date parsing, run the input through /v1/text/language first and route per language.
What happens on unparseable input?
Returns a 400 PARSE_ERROR with a message naming the input. Useful for falling back to a strict format in your UI.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.

Sign up free View full docs