{ "openapi": "3.1.0", "info": { "title": "Wait, What Time? Agent API", "version": "1.8.1", "description": "Read-only weekly-call comparisons. Explicit dates and IANA zones required. No account access, messages, calendar edits or availability check." }, "servers": [ { "url": "https://waitwhattime.com" } ], "paths": { "/api/compare": { "post": { "operationId": "compareWeeklyCall", "summary": "Compare both local-time policies for a weekly call", "description": "Send only scheduling fields. Inputs are processed remotely. No batch requests; max 16 KiB. Ask for missing fields rather than guessing the anchor, dates, scope or policy.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Decision" }, "example": { "v": 1, "sourceZone": "America/New_York", "viewerZone": "Asia/Kolkata", "referenceDate": "2026-10-26", "referenceTime": "09:00", "duration": 30, "cutoff": "19:00", "knownAnchor": true, "scope": "four", "choice": "viewer", "asOf": "2026-10-31" } } } }, "responses": { "200": { "description": "A proposed comparison, never an applied calendar change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comparison" } } } }, "400": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "405": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "413": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "415": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "500": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/zones": { "get": { "operationId": "searchTimeZones", "summary": "Suggest IANA time zones from a city or zone name", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } } ], "responses": { "200": { "description": "Up to 20 suggestions; confirm ambiguous locations.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "query", "rulesVersion", "matches", "totalMatches", "truncated", "limit", "note" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 80 }, "rulesVersion": { "type": "string" }, "matches": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "zone", "label" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "label": { "type": "string" } } } }, "totalMatches": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" }, "limit": { "type": "integer", "const": 20 }, "note": { "type": "string" } } } } } }, "400": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "405": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "500": { "description": "Request rejected. Do not act on stale results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } }, "components": { "schemas": { "Decision": { "type": "object", "additionalProperties": false, "required": [ "v", "sourceZone", "viewerZone", "referenceDate", "referenceTime", "duration", "cutoff", "knownAnchor", "scope", "choice", "asOf" ], "properties": { "v": { "type": "integer", "const": 1, "description": "Decision input version. Must be 1." }, "sourceZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Confirmed invitation anchor zone, or an explicitly assumed zone when knownAnchor=false. Use a recognized IANA identifier or UTC." }, "viewerZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The other person’s recognized time zone. Must differ from sourceZone." }, "referenceDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "Reference call date in sourceZone, 2020–2040, on/before asOf and within 366 days. Prefer a completed call before the clock change." }, "referenceTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "minLength": 5, "maxLength": 5, "description": "Reference call start in sourceZone, using the 24-hour clock." }, "duration": { "type": "integer", "minimum": 15, "maximum": 180, "description": "Call duration in minutes." }, "cutoff": { "type": "string", "pattern": "^$|^([01]\\d|2[0-3]):[0-5]\\d$", "maxLength": 5, "description": "Viewer-local finish-by time, or an empty string to disable the cutoff check." }, "knownAnchor": { "type": "boolean", "description": "True only if the invitation’s time zone is confirmed. False returns conditional scenarios." }, "scope": { "type": "string", "enum": [ "four", "ongoing" ], "description": "Propose only the four previewed occurrences, or an ongoing weekly local-time policy." }, "choice": { "type": "string", "enum": [ "source", "viewer" ], "description": "Whose reference local start time should remain fixed in the proposed request. Both options are compared." }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "Explicit review date, 2020–2040, interpreted in sourceZone. Occurrences on this date are excluded." } } }, "Comparison": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "rulesVersion", "input", "scenarioOnly", "reference", "options", "selectedPolicy", "scope", "laterTransitions", "warnings", "proposalText", "organizerText", "reviewUrl", "requiresHumanAgreement", "calendarChanged", "limits" ], "properties": { "schemaVersion": { "type": "integer", "const": 1 }, "rulesVersion": { "type": "string" }, "input": { "type": "object", "additionalProperties": false, "required": [ "v", "sourceZone", "viewerZone", "referenceDate", "referenceTime", "duration", "cutoff", "knownAnchor", "scope", "choice", "asOf" ], "properties": { "v": { "type": "integer", "const": 1, "description": "Decision input version. Must be 1." }, "sourceZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Confirmed invitation anchor zone, or an explicitly assumed zone when knownAnchor=false. Use a recognized IANA identifier or UTC." }, "viewerZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The other person’s recognized time zone. Must differ from sourceZone." }, "referenceDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "Reference call date in sourceZone, 2020–2040, on/before asOf and within 366 days. Prefer a completed call before the clock change." }, "referenceTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "minLength": 5, "maxLength": 5, "description": "Reference call start in sourceZone, using the 24-hour clock." }, "duration": { "type": "integer", "minimum": 15, "maximum": 180, "description": "Call duration in minutes." }, "cutoff": { "type": "string", "pattern": "^$|^([01]\\d|2[0-3]):[0-5]\\d$", "maxLength": 5, "description": "Viewer-local finish-by time, or an empty string to disable the cutoff check." }, "knownAnchor": { "type": "boolean", "description": "True only if the invitation’s time zone is confirmed. False returns conditional scenarios." }, "scope": { "type": "string", "enum": [ "four", "ongoing" ], "description": "Propose only the four previewed occurrences, or an ongoing weekly local-time policy." }, "choice": { "type": "string", "enum": [ "source", "viewer" ], "description": "Whose reference local start time should remain fixed in the proposed request. Both options are compared." }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "Explicit review date, 2020–2040, interpreted in sourceZone. Occurrences on this date are excluded." } } }, "scenarioOnly": { "type": "boolean" }, "reference": { "type": "object", "additionalProperties": false, "required": [ "startUtc", "endUtc", "source", "viewer", "outsideCutoff" ], "properties": { "startUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "endUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "source": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "viewer": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "outsideCutoff": { "type": [ "boolean", "null" ] } } }, "options": { "type": "object", "additionalProperties": false, "required": [ "source", "viewer" ], "properties": { "source": { "type": "object", "additionalProperties": false, "required": [ "anchorZone", "anchorLocalTime", "anchorWeekday", "rows", "cutoffCount", "changes" ], "properties": { "anchorZone": { "type": "string", "minLength": 1, "maxLength": 80 }, "anchorLocalTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "anchorWeekday": { "type": "string", "enum": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ] }, "rows": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "required": [ "startUtc", "endUtc", "source", "viewer", "outsideCutoff" ], "properties": { "startUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "endUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "source": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "viewer": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "outsideCutoff": { "type": [ "boolean", "null" ] } } } }, "cutoffCount": { "type": "integer", "minimum": 0, "maximum": 4 }, "changes": { "type": "array", "maxItems": 52, "items": { "type": "object", "additionalProperties": false, "required": [ "date", "sourceTime", "viewerTime", "sourceDate", "viewerDate" ], "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "sourceTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "viewerTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "sourceDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "viewerDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } } } }, "viewer": { "type": "object", "additionalProperties": false, "required": [ "anchorZone", "anchorLocalTime", "anchorWeekday", "rows", "cutoffCount", "changes" ], "properties": { "anchorZone": { "type": "string", "minLength": 1, "maxLength": 80 }, "anchorLocalTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "anchorWeekday": { "type": "string", "enum": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ] }, "rows": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "required": [ "startUtc", "endUtc", "source", "viewer", "outsideCutoff" ], "properties": { "startUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "endUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "source": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "viewer": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "outsideCutoff": { "type": [ "boolean", "null" ] } } } }, "cutoffCount": { "type": "integer", "minimum": 0, "maximum": 4 }, "changes": { "type": "array", "maxItems": 52, "items": { "type": "object", "additionalProperties": false, "required": [ "date", "sourceTime", "viewerTime", "sourceDate", "viewerDate" ], "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "sourceTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "viewerTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "sourceDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "viewerDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } } } } } }, "selectedPolicy": { "type": "string", "enum": [ "source", "viewer" ] }, "scope": { "type": "string", "enum": [ "four", "ongoing" ] }, "firstExcluded": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "startUtc", "endUtc", "source", "viewer", "outsideCutoff" ], "properties": { "startUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "endUtc": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "source": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "viewer": { "type": "object", "additionalProperties": false, "required": [ "zone", "date", "time", "endDate", "endTime" ], "properties": { "zone": { "type": "string", "minLength": 1, "maxLength": 80 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "outsideCutoff": { "type": [ "boolean", "null" ] } } }, { "type": "null" } ] }, "laterTransitions": { "type": "array", "maxItems": 52, "items": { "type": "object", "additionalProperties": false, "required": [ "date", "sourceTime", "viewerTime", "sourceDate", "viewerDate" ], "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "sourceTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "viewerTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "sourceDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "viewerDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "proposalText": { "type": "string" }, "organizerText": { "type": "string" }, "reviewUrl": { "type": "string", "pattern": "^https://[^/]+/#decision=" }, "requiresHumanAgreement": { "type": "boolean", "const": true }, "calendarChanged": { "type": "boolean", "const": false }, "limits": { "type": "object", "additionalProperties": false, "required": [ "previewOccurrences", "forecastOccurrences", "frequency", "reviewDateRule", "availabilityChecked", "calendarExceptionsModeled", "futureTimeZoneRulesMayChange", "scopeNote" ], "properties": { "previewOccurrences": { "type": "integer", "const": 4 }, "forecastOccurrences": { "type": "integer", "const": 52 }, "frequency": { "type": "string", "const": "weekly" }, "reviewDateRule": { "type": "string" }, "availabilityChecked": { "type": "boolean", "const": false }, "calendarExceptionsModeled": { "type": "boolean", "const": false }, "futureTimeZoneRulesMayChange": { "type": "boolean", "const": true }, "scopeNote": { "type": "string" } } } }, "allOf": [ { "if": { "properties": { "scope": { "const": "four" } }, "required": [ "scope" ] }, "then": { "required": [ "firstExcluded" ] }, "else": { "not": { "required": [ "firstExcluded" ] } } } ] } } } }