API Overview

Biruni resolves natural-language temporal expressions to precise, timezone-aware ISO 8601 datetimes. It is designed for agent workflows: send the extracted temporal phrase, an anchor date, and an IANA timezone.

Quickstart

Create an API key in the dashboard, then send one POST request to resolve a temporal phrase.

curl -X POST https://biruni.dev/v1/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "next Monday at 9am",
    "reference_date": "2026-04-02",
    "timezone": "America/New_York"
  }'

POST /v1/resolve

Resolve a temporal phrase into a timezone-aware ISO 8601 datetime. The API is deterministic, ambiguity-aware, and intended to be called by agents during execution.

Request format

Example request body

{
  "expression": "next Monday at 9am",
  "reference_date": "2026-04-02",
  "timezone": "America/New_York",
  "locale": "en-US",
  "options": {
    "prefer_future": true,
    "business_calendar": "us_federal"
  }
}

Response format

Example response

{
  "status": "resolved",
  "resolved": "2026-04-06T09:00:00-04:00",
  "confidence": "high",
  "interpretation": "Next Monday from April 2 is April 6. 9:00 AM in America/New_York.",
  "ambiguities": [],
  "alternatives": [],
  "metadata": {
    "expression_type": "weekday",
    "timezone": "America/New_York",
    "calendar_used": "us_federal",
    "holidays_applied": [],
    "processing_time_ms": 11.2
  }
}

Error codes

All errors return a consistent JSON body:

{ "error": { "code": "ERROR_CODE", "message": "..." } }

For AI Agents

Use Biruni whenever your agent needs an exact date or time before taking an action.

Tool definition

Copy the MCP tool definition below into your agent framework. If your framework uses a different wrapper key, rename inputSchema to match (e.g. parameters for OpenAI, input_schema for Anthropic).

{
  "name": "biruni_resolve",
  "description": "Resolve a natural-language temporal phrase to a timezone-aware ISO 8601 datetime. Send only the temporal phrase, not surrounding prose. If status is ambiguous, inspect alternatives before acting.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "expression": {
        "type": "string",
        "description": "The temporal phrase to resolve, e.g. 'next Tuesday at 10am' or 'in 5 business days'. Extract only the time expression from the user's message."
      },
      "reference_date": {
        "type": "string",
        "description": "Anchor date in YYYY-MM-DD format. Usually today's local date. For chained resolution, use the previously resolved date."
      },
      "timezone": {
        "type": "string",
        "description": "IANA timezone identifier, e.g. 'America/New_York' or 'Europe/London'. Do not use abbreviations like EST or PST."
      },
      "options": {
        "type": "object",
        "description": "Optional resolution overrides.",
        "properties": {
          "prefer_future": {
            "type": "boolean",
            "description": "Bias ambiguous expressions toward the next upcoming occurrence."
          },
          "business_calendar": {
            "type": "string",
            "description": "Business calendar for business day arithmetic. Use 'us_federal' for the MVP."
          }
        }
      }
    },
    "required": ["expression", "reference_date", "timezone"]
  }
}

Integration guide

Register the tool definition above with your agent framework, then paste the rules below into your agent's system prompt or instruction layer so it knows when and how to call the tool.

Usage rules

Copy into your agent's instructions:

When the user mentions a date, time, or deadline, call biruni_resolve instead of
doing date math yourself.

1. Extract only the temporal phrase from the user's message.
   Good: "next Monday at 3pm"  Bad: "Can we meet next Monday at 3pm?"
2. Map informal timezone names to IANA identifiers ("Eastern" → America/New_York).
3. Set reference_date to today's local date (YYYY-MM-DD), or the output of a
   previous call for chained resolution.
4. If status is "resolved", use the resolved datetime directly.
5. If status is "ambiguous", present the alternatives to the user before acting.
6. If status is "unresolvable", ask the user to rephrase.
7. Never fall back to LLM date arithmetic — retry with a cleaner expression instead.

Common mistakes

Expression types

Common patterns Biruni can resolve. Use these as representative examples, not exhaustive limits.

Ambiguous response example

{
  "status": "ambiguous",
  "resolved": "2026-04-10T00:00:00-04:00",
  "confidence": "medium",
  "interpretation": "'next Friday' on a Friday — interpreted as next week's Friday.",
  "ambiguities": ["'next Friday' on a Friday is ambiguous."],
  "alternatives": [
    {
      "resolved": "2026-04-03T00:00:00-04:00",
      "interpretation": "Today (this Friday)"
    }
  ]
}