openapi: 3.0.3 info: title: TimeLogic API | World Time, Timezones & Time Calculations version: v1 description: World time, timezone resolution, DST status, calendar projection, timestamp conversion, business-day calculations, signed JSON responses, and embeddable clocks. termsOfService: | # Terms of Use By using the TimeLogic API, you agree to the following terms: ## 1. Usage You may use the API for personal, commercial, and internal business applications, provided your usage complies with applicable laws and RapidAPI platform policies. ## 2. Rate Limits & Fair Use All users must respect the assigned rate limits of their subscription plan. Excessive, abusive, or automated scraping behavior beyond reasonable usage may result in throttling or suspension. ## 3. Service Availability TimeLogic API is provided on an "as-is" and "as-available" basis. While we aim for high uptime and reliability, we do not guarantee uninterrupted service. ## 4. Prohibited Use You may not use the API for: - Illegal activities - Attempting to disrupt or overload the service - Reverse engineering or attempting to extract backend infrastructure - Reselling the API without permission ## 5. Data Accuracy Time data is sourced and computed using reliable systems, but minor discrepancies may occur due to network conditions, timezone changes, or external dependencies. ## 6. Modifications We reserve the right to update, modify, or discontinue parts of the API at any time with or without notice. ## 7. Liability We are not liable for any damages, losses, or issues arising from the use or inability to use the API. By continuing to use the API, you acknowledge and accept these terms. x-long-description: | TimeLogic API provides world time lookup, timezone resolution, DST status, calendar projection, timestamp conversion, arithmetic, elapsed and diff calculations, signed JSON responses, and embeddable clock views. Key capabilities: - Resolve time using exactly one selector family per request: `tz`, `ip`, `lat` + `lon`, or `offset`. - Use bulk mode only on `/v1/time/current` and `/v1/time/convert` by supplying one comma-separated `tz`, `ip`, or `offset` selector. - Use `/v1/time/diff` and `/v1/time/elapsed` for duration and business-day calculations, including supported holiday calendars. - Use `sign=true` on supported JSON routes and verify signatures with `/.well-known/time-api-public-key`. - Use `/v1/time/clock` for embeddable HTML clock fragments with named analog and digital styles. Human-readable fields such as `human` are display-oriented and should not be parsed structurally. x-category: Tools x-thumbnail: https://timelogicapi.com/logo.png x-website: https://timelogicapi.com/docs servers: - url: https://r-api.timelogicapi.com description: Direct backend origin used for provider-side validation and testing. RapidAPI consumers use the proxy hostname shown in the Hub. x-documentation: readme: | # TimeLogic API TimeLogic API provides world time, timezone resolution, DST status, calendar projection, timestamp conversion, business-day calculations, signed JSON responses, and embeddable clock views. ## Documentation Full docs: [timelogicapi.com/docs](https://timelogicapi.com/docs) ## Capabilities - Resolve time using exactly one selector family per request: `tz`, `ip`, `lat` + `lon`, or `offset`. - Use bulk mode only on `/v1/time/current` and `/v1/time/convert` by supplying one comma-separated `tz`, `ip`, or `offset` selector. - Use `/v1/time/diff` and `/v1/time/elapsed` for duration and business-day calculations, including supported holiday calendars. - Use `sign=true` on supported JSON routes and verify signatures with `/.well-known/time-api-public-key`. - Use `/v1/time/clock` for embeddable HTML clock fragments with named analog and digital styles. ## Usage Notes - Only one selector family is valid per request. - `/v1/time/current` and `/v1/time/convert` are the only bulk-capable routes. - Human-readable fields such as `human` are display-oriented and should not be parsed structurally. - `/v1/time/clock` returns an embeddable HTML fragment, not JSON. externalDocs: description: Full TimeLogic API documentation url: https://timelogicapi.com/docs tags: - name: Utility description: Public verification and support routes. - name: Time description: Time, timezone, calendar, and duration operations. paths: /.well-known/time-api-public-key: get: tags: - Utility summary: Public signing key set description: 'Unauthenticated JWKS endpoint for verifying signed JSON responses. This route publishes the active Ed25519 public key set used by the gateway for detached JSON response signing.' operationId: getPublicSigningKey responses: '200': description: Active Ed25519 signing key set. content: application/jwk-set+json: schema: $ref: '#/components/schemas/JwksResponse' examples: activeKey: $ref: '#/components/examples/JwksExample' '500': description: Signing public key is not configured or could not be loaded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: $ref: '#/components/examples/InternalErrorExample' /v1/time/current: get: tags: - Time summary: Get the current time for a target description: 'Returns current time data for a single target, or a bulk array when exactly one of `tz`, `ip`, or `offset` is supplied as a comma-separated list. Target selector rules: - Use at most one selector family per request: `tz`, `ip`, `lat` + `lon`, `offset`. - If no selector is provided, the response defaults to UTC with `timezone=null` and `iso_local=null`. - Bulk mode is available only through one comma-separated `tz`, `ip`, or `offset` selector and cannot be combined with any other selector. Example: - Single target: `/v1/time/current?tz=America/New_York` - For bulk, provide one comma-separated `tz`, `ip`, or `offset` value, for example `/v1/time/current?tz=America/New_York,Europe/London,Asia/Tokyo`.' operationId: getCurrentTime parameters: - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/Format' - $ref: '#/components/parameters/SignFlag' responses: '200': description: Current time payload or bulk array. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: oneOf: - $ref: '#/components/schemas/TimePayload' - $ref: '#/components/schemas/TimePayloadBulkResponse' examples: singleTarget: $ref: '#/components/examples/CurrentSingleExample' bulkByTimezone: $ref: '#/components/examples/CurrentBulkExample' bulkPartialFailure: $ref: '#/components/examples/CurrentBulkPartialFailureExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' /v1/time/convert: get: tags: - Time summary: Convert a timestamp into a target timezone or offset description: | Converts one required input timestamp into a single target or a bulk array. Input timestamp forms: - `unix=1711300000` - `unix_ms=1711300000000` - `iso=2026-04-16T09:00:00Z` - `iso=2026-04-16T09:00:00&source_tz=America/New_York` - `iso=2026-04-16T09:00:00&source_ip=8.8.8.8` - `iso=2026-04-16T09:00:00&source_lat=40.7128&source_lon=-74.0060` - `iso=2026-04-16T09:00:00&source_offset=-05:00` Target selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` - `utc=true` Incompatible combinations: - exactly one input timestamp form - exactly one target selector family - use at most one of `source_tz`, `source_ip`, `source_lat`/`source_lon`, or `source_offset` - local-ISO companion selectors are valid only with `iso=...` that has no explicit offset - bulk is allowed only through one comma-separated `tz`, `ip`, or `offset` selector Examples: - Single target: `/v1/time/convert?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London` - Bulk target set: `/v1/time/convert?unix=1711300000&offset=-04:00,+00:00,+09:00` operationId: convertTime parameters: - $ref: '#/components/parameters/Unix' - $ref: '#/components/parameters/UnixMs' - $ref: '#/components/parameters/Iso' - $ref: '#/components/parameters/SourceTz' - $ref: '#/components/parameters/SourceIp' - $ref: '#/components/parameters/SourceLat' - $ref: '#/components/parameters/SourceLon' - $ref: '#/components/parameters/SourceOffset' - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/UtcFlag' - $ref: '#/components/parameters/Format' - $ref: '#/components/parameters/SignFlag' responses: '200': description: Converted time payload or bulk array. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: oneOf: - $ref: '#/components/schemas/TimePayload' - $ref: '#/components/schemas/TimePayloadBulkResponse' examples: singleTarget: $ref: '#/components/examples/ConvertSingleExample' bulkByOffset: $ref: '#/components/examples/ConvertBulkExample' bulkPartialFailure: $ref: '#/components/examples/ConvertBulkPartialFailureExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' /v1/time/diff: get: tags: - Time summary: Difference between two instants description: | Computes the duration between `from` and `to`. `from` and `to` are embedded specifier strings. Accepted specifier forms: - `from=now` - `from=unix=1711300000` - `from=unix_ms=1711300000000` - `from=iso=2026-04-16T09:00:00` - `from=tz=America/New_York` - `from=ip=8.8.8.8` - `from=offset=-05:00` - the same forms are accepted for `to` Timezone hint pairings: - `from_tz` only with `from=iso=...` that has no explicit offset - `from_ip`, `from_lat`/`from_lon`, and `from_offset` only with `from=iso=...` that has no explicit offset - `to_tz` only with `to=iso=...` that has no explicit offset - `to_ip`, `to_lat`/`to_lon`, and `to_offset` only with `to=iso=...` that has no explicit offset Selector semantics: - `tz=...`, `ip=...`, and `offset=...` inside `from` or `to` mean the current request-time instant resolved through that selector - those selector forms do not represent an arbitrary local wall-clock time - returned duration magnitudes are absolute; use `direction` to see whether `to` is after, before, or the same instant as `from` Business-day rules: - `holiday_country` and `holiday_subdivision` require `business_days=true` - `holiday_subdivision` also requires `holiday_country` Examples: - Selector-current instant: `/v1/time/diff?from=unix=1711300000&to=tz=America/New_York` - Wall-clock pairing: `/v1/time/diff?from=iso=2026-04-16T09:00:00&from_tz=America/New_York&to=iso=2026-04-16T09:00:00&to_tz=Europe/London` - Wall-clock via selector: `/v1/time/diff?from=iso=2026-01-01T12:00:00&from_ip=8.8.8.8&to=iso=2026-01-01T12:00:00&to_offset=-05:00` operationId: diffTime parameters: - $ref: '#/components/parameters/FromSpecifier' - $ref: '#/components/parameters/ToSpecifier' - $ref: '#/components/parameters/FromTz' - $ref: '#/components/parameters/FromIp' - $ref: '#/components/parameters/FromLat' - $ref: '#/components/parameters/FromLon' - $ref: '#/components/parameters/FromOffset' - $ref: '#/components/parameters/ToTz' - $ref: '#/components/parameters/ToIp' - $ref: '#/components/parameters/ToLat' - $ref: '#/components/parameters/ToLon' - $ref: '#/components/parameters/ToOffset' - $ref: '#/components/parameters/DurationFormat' - $ref: '#/components/parameters/BusinessDays' - $ref: '#/components/parameters/HolidayCountry' - $ref: '#/components/parameters/HolidaySubdivision' - $ref: '#/components/parameters/SignFlag' responses: '200': description: Duration result. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: $ref: '#/components/schemas/DiffResponse' examples: duration: $ref: '#/components/examples/DiffExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' /v1/time/add: get: tags: - Time summary: Add modifiers to a timestamp description: | Adds `seconds`, `minutes`, `hours`, and `days` to an optional base timestamp. Input timestamp forms: - `unix=1711300000` - `unix_ms=1711300000000` - `iso=2026-04-16T09:00:00Z` - `iso=2026-04-16T09:00:00&source_tz=America/New_York` - `iso=2026-04-16T09:00:00&source_ip=8.8.8.8` - `iso=2026-04-16T09:00:00&source_lat=40.7128&source_lon=-74.0060` - `iso=2026-04-16T09:00:00&source_offset=-05:00` - if no input timestamp is provided, the base timestamp defaults to the request time Modifiers: - `seconds=30` - `minutes=15` - `hours=2` - `days=7` Target selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` - `utc=true` Incompatible combinations: - at most one input timestamp form - at most one target selector family - use at most one of `source_tz`, `source_ip`, `source_lat`/`source_lon`, or `source_offset` - local-ISO companion selectors are valid only with `iso=...` that has no explicit offset - bulk is not supported on this route Examples: - `/v1/time/add?iso=2026-04-16T09:00:00&source_tz=America/New_York&days=1&tz=Europe/London` - `/v1/time/add?minutes=30&utc=true` operationId: addTime parameters: - $ref: '#/components/parameters/Unix' - $ref: '#/components/parameters/UnixMs' - $ref: '#/components/parameters/Iso' - $ref: '#/components/parameters/SourceTz' - $ref: '#/components/parameters/SourceIp' - $ref: '#/components/parameters/SourceLat' - $ref: '#/components/parameters/SourceLon' - $ref: '#/components/parameters/SourceOffset' - $ref: '#/components/parameters/SecondsModifier' - $ref: '#/components/parameters/MinutesModifier' - $ref: '#/components/parameters/HoursModifier' - $ref: '#/components/parameters/DaysModifier' - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/UtcFlag' - $ref: '#/components/parameters/Format' - $ref: '#/components/parameters/SignFlag' responses: '200': description: Adjusted timestamp payload. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: $ref: '#/components/schemas/TimePayload' examples: adjustedTime: $ref: '#/components/examples/AddExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' /v1/time/calendar: get: tags: - Time summary: Calendar projection for a target instant operationId: getCalendar parameters: - $ref: '#/components/parameters/Unix' - $ref: '#/components/parameters/UnixMs' - $ref: '#/components/parameters/Iso' - $ref: '#/components/parameters/SourceTz' - $ref: '#/components/parameters/SourceIp' - $ref: '#/components/parameters/SourceLat' - $ref: '#/components/parameters/SourceLon' - $ref: '#/components/parameters/SourceOffset' - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/Format' - $ref: '#/components/parameters/WeekFlag' - $ref: '#/components/parameters/SignFlag' responses: '200': description: Calendar payload. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: $ref: '#/components/schemas/CalendarResponse' examples: calendarProjection: $ref: '#/components/examples/CalendarExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' description: | Returns calendar fields for an optional timestamp and target. Input timestamp forms: - `unix=1711300000` - `unix_ms=1711300000000` - `iso=2026-04-16T09:00:00Z` - `iso=2026-04-16T09:00:00&source_tz=America/New_York` - `iso=2026-04-16T09:00:00&source_ip=8.8.8.8` - `iso=2026-04-16T09:00:00&source_lat=40.7128&source_lon=-74.0060` - `iso=2026-04-16T09:00:00&source_offset=-05:00` - if no input timestamp is provided, the request time is used Target selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` Additional flags: - `week=true` adds `week_number` Incompatible combinations: - at most one input timestamp form - at most one target selector family - use at most one of `source_tz`, `source_ip`, `source_lat`/`source_lon`, or `source_offset` - local-ISO companion selectors are valid only with `iso=...` that has no explicit offset - bulk is not supported on this route Examples: - `/v1/time/calendar?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London&week=true` - `/v1/time/calendar?unix=1711300000&offset=-04:00` /v1/time/dst: get: tags: - Time summary: Daylight-saving status for a target operationId: getDst parameters: - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/Format' - $ref: '#/components/parameters/NextFlag' - $ref: '#/components/parameters/SignFlag' responses: '200': description: DST payload. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: $ref: '#/components/schemas/DstResponse' examples: dstStatus: $ref: '#/components/examples/DstExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' description: 'Returns daylight-saving status for the selected target. Target selector rules: - Use at most one selector family: `tz`, `ip`, `lat` + `lon`, or `offset`. - If no selector is provided, the response defaults to UTC. - Bulk is not supported on this route. - `next=true` adds `next_transition` when the resolver provides a transition timestamp. Example: - `/v1/time/dst?tz=America/New_York&next=true`' /v1/time/clock: get: tags: - Time summary: Render a live HTML clock description: | Returns an embeddable HTML clock fragment. Input timestamp forms: - `unix=1711300000` - `unix_ms=1711300000000` - `iso=2026-04-16T09:00:00Z` - `iso=2026-04-16T09:00:00&source_tz=America/New_York` - `iso=2026-04-16T09:00:00&source_ip=8.8.8.8` - `iso=2026-04-16T09:00:00&source_lat=40.7128&source_lon=-74.0060` - `iso=2026-04-16T09:00:00&source_offset=-05:00` Target selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` Incompatible combinations: - `style` is required and must be one of the 30 names in the `style` enum - at most one input timestamp form - at most one target selector family - use at most one of `source_tz`, `source_ip`, `source_lat`/`source_lon`, or `source_offset` - local-ISO companion selectors are valid only with `iso=...` that has no explicit offset - this route is single-target only; comma-separated `tz`, `ip`, and `offset` values are rejected - `sign` is not supported on this route Examples: - Digital: `/v1/time/clock?style=digital-dashboard&iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London` - Analog: `/v1/time/clock?style=analog-station&offset=-04:00` operationId: getClock parameters: - $ref: '#/components/parameters/Style' - $ref: '#/components/parameters/Unix' - $ref: '#/components/parameters/UnixMs' - $ref: '#/components/parameters/Iso' - $ref: '#/components/parameters/SourceTz' - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/Format' responses: '200': description: Embeddable HTML clock fragment. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Cache-Control: description: Clock HTML is uncached so the bootstrap always reflects the current request. schema: type: string example: no-store content: text/html: schema: type: string examples: digitalDashboard: $ref: '#/components/examples/ClockDigitalHtmlExample' analogStation: $ref: '#/components/examples/ClockAnalogHtmlExample' '400': description: Invalid clock style or unsupported selector combination. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidStyle: $ref: '#/components/examples/ClockInvalidStyleExample' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' /v1/time/elapsed: get: tags: - Time summary: Time elapsed since or remaining until a reference instant description: | Computes elapsed or remaining duration relative to one required reference timestamp. Reference timestamp forms: - `unix=1711300000` - `unix_ms=1711300000000` - `iso=2026-04-16T09:00:00Z` - `iso=2026-04-16T09:00:00&source_tz=America/New_York` - `iso=2026-04-16T09:00:00&source_ip=8.8.8.8` - `iso=2026-04-16T09:00:00&source_lat=40.7128&source_lon=-74.0060` - `iso=2026-04-16T09:00:00&source_offset=-05:00` Compare timestamp forms: - `compare_unix=1711213600` - `compare_unix_ms=1711213600000` - `compare_iso=2026-04-16T09:00:00Z` - `compare_iso=2026-04-16T09:00:00&compare_source_tz=Europe/London` - `compare_iso=2026-04-16T09:00:00&compare_source_ip=8.8.8.8` - `compare_iso=2026-04-16T09:00:00&compare_source_lat=40.7128&compare_source_lon=-74.0060` - `compare_iso=2026-04-16T09:00:00&compare_source_offset=-05:00` Compare selector forms: - `tz=America/New_York` - `ip=8.8.8.8` - `lat=40.7128&lon=-74.0060` - `offset=-04:00` Incompatible combinations: - exactly one reference timestamp form - use either one compare timestamp form or one compare selector family, not both - use at most one of `source_tz`, `source_ip`, `source_lat`/`source_lon`, or `source_offset` - use at most one of `compare_source_tz`, `compare_source_ip`, `compare_source_lat`/`compare_source_lon`, or `compare_source_offset` - local-ISO companion selectors are valid only with `iso=...` that has no explicit offset - compare local-ISO companion selectors are valid only with `compare_iso=...` that has no explicit offset - if no compare input is provided, the comparison defaults to the request time Business-day rules: - `holiday_country` and `holiday_subdivision` require `business_days=true` - `holiday_subdivision` also requires `holiday_country` Examples: - Timestamp-to-timestamp: `/v1/time/elapsed?iso=2026-04-16T09:00:00&source_tz=America/New_York&compare_iso=2026-04-16T09:00:00&compare_source_tz=Europe/London` - Timestamp-to-selector: `/v1/time/elapsed?unix=1711300000&tz=America/New_York&business_days=true` operationId: getElapsed parameters: - $ref: '#/components/parameters/Unix' - $ref: '#/components/parameters/UnixMs' - $ref: '#/components/parameters/Iso' - $ref: '#/components/parameters/SourceTz' - $ref: '#/components/parameters/SourceIp' - $ref: '#/components/parameters/SourceLat' - $ref: '#/components/parameters/SourceLon' - $ref: '#/components/parameters/SourceOffset' - $ref: '#/components/parameters/CompareUnix' - $ref: '#/components/parameters/CompareUnixMs' - $ref: '#/components/parameters/CompareIso' - $ref: '#/components/parameters/CompareSourceTz' - $ref: '#/components/parameters/CompareSourceIp' - $ref: '#/components/parameters/CompareSourceLat' - $ref: '#/components/parameters/CompareSourceLon' - $ref: '#/components/parameters/CompareSourceOffset' - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/DurationFormat' - $ref: '#/components/parameters/BusinessDays' - $ref: '#/components/parameters/HolidayCountry' - $ref: '#/components/parameters/HolidaySubdivision' - $ref: '#/components/parameters/SignFlag' responses: '200': description: Elapsed-duration result. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: $ref: '#/components/schemas/ElapsedResponse' examples: remainingDuration: $ref: '#/components/examples/ElapsedExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' /v1/timezone: get: tags: - Time summary: Resolve timezone information for a target description: 'Resolves timezone metadata for a single target. Target selector rules: - Use exactly one selector family: `tz`, `ip`, `lat` + `lon`, or `offset`. - Bulk is not supported on this route. - `offset` queries return a specialized payload that includes `matching_zones` for the request-time offset match. Examples: - Single target: `/v1/timezone?tz=America/New_York` - Offset match: `/v1/timezone?offset=-04:00`' operationId: getTimezone parameters: - $ref: '#/components/parameters/TzSelector' - $ref: '#/components/parameters/IpSelector' - $ref: '#/components/parameters/LatSelector' - $ref: '#/components/parameters/LonSelector' - $ref: '#/components/parameters/OffsetSelector' - $ref: '#/components/parameters/SignFlag' responses: '200': description: Resolved timezone payload. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-TimeLogic-Signature: $ref: '#/components/headers/XTimeLogicSignature' X-TimeLogic-Key-Id: $ref: '#/components/headers/XTimeLogicKeyId' X-TimeLogic-Signature-Alg: $ref: '#/components/headers/XTimeLogicSignatureAlg' X-TimeLogic-Signature-Timestamp: $ref: '#/components/headers/XTimeLogicSignatureTimestamp' X-TimeLogic-Content-SHA256: $ref: '#/components/headers/XTimeLogicContentSha256' content: application/json: schema: oneOf: - $ref: '#/components/schemas/TimezoneResolvedResponse' - $ref: '#/components/schemas/TimezoneOffsetResponse' examples: resolvedTimezone: $ref: '#/components/examples/TimezoneResolvedExample' offsetMatches: $ref: '#/components/examples/TimezoneOffsetExample' '400': $ref: '#/components/responses/AuthenticatedBadRequest' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' '501': $ref: '#/components/responses/DependencyNotReady' '502': $ref: '#/components/responses/UpstreamFailure' components: headers: XRequestId: description: Gateway-generated or forwarded request identifier. schema: type: string XTimeLogicSignature: description: Base64 Ed25519 detached signature for signed JSON responses. schema: type: string XTimeLogicKeyId: description: Signing key identifier used for `X-TimeLogic-Signature`. schema: type: string XTimeLogicSignatureAlg: description: Signature algorithm. schema: type: string enum: - Ed25519 XTimeLogicSignatureTimestamp: description: UNIX seconds used in the signing envelope. schema: type: string pattern: ^-?\d+$ XTimeLogicContentSha256: description: Standard Base64 SHA-256 hash of the exact UTF-8 JSON response body bytes. schema: type: string parameters: SignFlag: name: sign in: query description: Set to `true` to ask the gateway to sign the final JSON response. Not supported on `/v1/time/clock`. required: false schema: type: boolean Format: name: format in: query description: Custom date/time format template. required: false schema: type: string DurationFormat: name: format in: query description: Custom duration format template using `%days`, `%hours`, `%minutes`, and `%seconds`. required: false schema: type: string TzSelector: name: tz in: query description: IANA timezone name. On bulk-capable routes, a comma-separated list enables bulk mode. required: false schema: type: string maxLength: 64 IpSelector: name: ip in: query description: IP address. On bulk-capable routes, a comma-separated list enables bulk mode. required: false schema: type: string LatSelector: name: lat in: query description: Latitude. Must be provided together with `lon`. required: false schema: type: number format: double minimum: -90 maximum: 90 LonSelector: name: lon in: query description: Longitude. Must be provided together with `lat`. required: false schema: type: number format: double minimum: -180 maximum: 180 OffsetSelector: name: offset in: query description: Fixed UTC offset in `+HH:MM` or `-HH:MM` format. On bulk-capable routes, a comma-separated list enables bulk mode. required: false schema: type: string pattern: ^[+-](0\d|1\d|2[0-3]):[0-5]\d$ UtcFlag: name: utc in: query description: Set to `true` to force UTC on routes that support it. required: false schema: type: boolean Unix: name: unix in: query description: UNIX seconds timestamp. Constrained to the JavaScript `Date` safe range. required: false schema: type: integer format: int64 minimum: -8640000000000 maximum: 8640000000000 UnixMs: name: unix_ms in: query description: UNIX milliseconds timestamp. Constrained to the JavaScript `Date` safe range. required: false schema: type: integer format: int64 minimum: -8640000000000000 maximum: 8640000000000000 Iso: name: iso in: query description: ISO-8601 timestamp. To supply a local wall-clock time without an explicit offset, pair it with one of `source_tz=Area/City`, `source_ip=...`, `source_lat=...&source_lon=...`, or `source_offset=±HH:MM`. required: false schema: type: string SourceTz: name: source_tz in: query description: Used only with `iso=...` when the ISO value has no explicit offset. required: false schema: type: string SourceIp: name: source_ip in: query description: Used only with `iso=...` when the ISO value has no explicit offset. Resolves that local wall-clock time through the timezone mapped from this IP address. required: false schema: type: string SourceLat: name: source_lat in: query description: Used only with `iso=...` when the ISO value has no explicit offset. Provide together with `source_lon` to resolve that local wall-clock time through the timezone mapped from these coordinates. required: false schema: type: number format: double minimum: -90 maximum: 90 SourceLon: name: source_lon in: query description: Used only with `iso=...` when the ISO value has no explicit offset. Provide together with `source_lat`. required: false schema: type: number format: double minimum: -180 maximum: 180 SourceOffset: name: source_offset in: query description: Used only with `iso=...` when the ISO value has no explicit offset. Interprets that local wall-clock time at this fixed UTC offset. required: false schema: type: string pattern: ^[+-](0\d|1\d|2[0-3]):[0-5]\d$ CompareUnix: name: compare_unix in: query description: Comparison UNIX seconds timestamp. Constrained to the JavaScript `Date` safe range. required: false schema: type: integer format: int64 minimum: -8640000000000 maximum: 8640000000000 CompareUnixMs: name: compare_unix_ms in: query description: Comparison UNIX milliseconds timestamp. Constrained to the JavaScript `Date` safe range. required: false schema: type: integer format: int64 minimum: -8640000000000000 maximum: 8640000000000000 CompareIso: name: compare_iso in: query description: ISO-8601 comparison timestamp. To supply a local wall-clock time without an explicit offset, pair it with one of `compare_source_tz=Area/City`, `compare_source_ip=...`, `compare_source_lat=...&compare_source_lon=...`, or `compare_source_offset=±HH:MM`. required: false schema: type: string CompareSourceTz: name: compare_source_tz in: query description: Used only with `compare_iso=...` when the ISO value has no explicit offset. required: false schema: type: string CompareSourceIp: name: compare_source_ip in: query description: Used only with `compare_iso=...` when the ISO value has no explicit offset. Resolves that local wall-clock time through the timezone mapped from this IP address. required: false schema: type: string CompareSourceLat: name: compare_source_lat in: query description: Used only with `compare_iso=...` when the ISO value has no explicit offset. Provide together with `compare_source_lon` to resolve that local wall-clock time through the timezone mapped from these coordinates. required: false schema: type: number format: double minimum: -90 maximum: 90 CompareSourceLon: name: compare_source_lon in: query description: Used only with `compare_iso=...` when the ISO value has no explicit offset. Provide together with `compare_source_lat`. required: false schema: type: number format: double minimum: -180 maximum: 180 CompareSourceOffset: name: compare_source_offset in: query description: Used only with `compare_iso=...` when the ISO value has no explicit offset. Interprets that local wall-clock time at this fixed UTC offset. required: false schema: type: string pattern: ^[+-](0\d|1\d|2[0-3]):[0-5]\d$ FromSpecifier: name: from in: query description: "Time specifier. Supported forms are `now`, `unix=`, `unix_ms=`,\ \ `iso=`, `offset=\xB1HH:MM`, `tz=`, and `ip=`. For `tz=...`, `ip=...`, and `offset=...`, the specifier means\ \ the current request-time instant resolved through that selector. To express\ \ a local wall-clock time, use `from=iso=...` together with one of `from_tz`,\ \ `from_ip`, `from_lat`+`from_lon`, or `from_offset`." required: true schema: type: string ToSpecifier: name: to in: query description: "Time specifier. Supported forms are `now`, `unix=`, `unix_ms=`,\ \ `iso=`, `offset=\xB1HH:MM`, `tz=`, and `ip=`. For `tz=...`, `ip=...`, and `offset=...`, the specifier means\ \ the current request-time instant resolved through that selector. To express\ \ a local wall-clock time, use `to=iso=...` together with one of `to_tz`,\ \ `to_ip`, `to_lat`+`to_lon`, or `to_offset`." required: true schema: type: string FromTz: name: from_tz in: query description: Used only with `from=iso=...` when the ISO value has no explicit offset. required: false schema: type: string FromIp: name: from_ip in: query description: Used only with `from=iso=...` when the ISO value has no explicit offset. Resolves that local wall-clock time through the timezone mapped from this IP address. required: false schema: type: string FromLat: name: from_lat in: query description: Used only with `from=iso=...` when the ISO value has no explicit offset. Provide together with `from_lon` to resolve that local wall-clock time through the timezone mapped from these coordinates. required: false schema: type: number format: double minimum: -90 maximum: 90 FromLon: name: from_lon in: query description: Used only with `from=iso=...` when the ISO value has no explicit offset. Provide together with `from_lat`. required: false schema: type: number format: double minimum: -180 maximum: 180 FromOffset: name: from_offset in: query description: Used only with `from=iso=...` when the ISO value has no explicit offset. Interprets that local wall-clock time at this fixed UTC offset. required: false schema: type: string pattern: ^[+-](0\d|1\d|2[0-3]):[0-5]\d$ ToTz: name: to_tz in: query description: Used only with `to=iso=...` when the ISO value has no explicit offset. required: false schema: type: string ToIp: name: to_ip in: query description: Used only with `to=iso=...` when the ISO value has no explicit offset. Resolves that local wall-clock time through the timezone mapped from this IP address. required: false schema: type: string ToLat: name: to_lat in: query description: Used only with `to=iso=...` when the ISO value has no explicit offset. Provide together with `to_lon` to resolve that local wall-clock time through the timezone mapped from these coordinates. required: false schema: type: number format: double minimum: -90 maximum: 90 ToLon: name: to_lon in: query description: Used only with `to=iso=...` when the ISO value has no explicit offset. Provide together with `to_lat`. required: false schema: type: number format: double minimum: -180 maximum: 180 ToOffset: name: to_offset in: query description: Used only with `to=iso=...` when the ISO value has no explicit offset. Interprets that local wall-clock time at this fixed UTC offset. required: false schema: type: string pattern: ^[+-](0\d|1\d|2[0-3]):[0-5]\d$ BusinessDays: name: business_days in: query description: Set to `true` to enable weekday/business-day counting. required: false schema: type: boolean HolidayCountry: name: holiday_country in: query description: ISO 3166-1 alpha-2 holiday calendar country code. Requires `business_days=true`. required: false schema: type: string pattern: ^[A-Z]{2}$ HolidaySubdivision: name: holiday_subdivision in: query description: Holiday calendar subdivision code from the upstream `python-holidays` calendar, for example `CA` or `ENG`. Requires `holiday_country` and `business_days=true`. required: false schema: type: string SecondsModifier: name: seconds in: query required: false schema: type: integer MinutesModifier: name: minutes in: query required: false schema: type: integer HoursModifier: name: hours in: query required: false schema: type: integer DaysModifier: name: days in: query required: false schema: type: integer WeekFlag: name: week in: query required: false schema: type: boolean NextFlag: name: next in: query required: false schema: type: boolean Style: name: style in: query required: true description: Clock style name. Valid values are enumerated here; there is no separate style discovery endpoint. schema: type: string enum: - analog-station - analog-aviation - analog-bauhaus - analog-graphite - analog-arctic - analog-brass - analog-marine - analog-grid - analog-slate - analog-executive - digital-segment-red - digital-segment-amber - digital-segment-ice - digital-terminal-green - digital-terminal-white - digital-broadcast - digital-dashboard - digital-control-room - digital-slate - digital-onyx - digital-frost - digital-card - digital-glass - digital-matrix - digital-timetable - digital-split-flap - digital-cyan - digital-emerald - digital-monolith - digital-minimal examples: JwksExample: summary: Active Ed25519 signing key set value: keys: - kty: OKP crv: Ed25519 alg: EdDSA use: sig kid: ed25519-2026-04-15-v1 x: dBXyuCfZz41tku9tUoInxgYZ_hMDb4G85sgvZuvSGXQ CurrentSingleExample: summary: Single-target time payload value: unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/New_York day_number: 4 day_short: Wed day_full: Wednesday timezone: America/New_York formatted: '2026-04-15 13:30' CurrentBulkExample: summary: Bulk current-time response value: - unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/New_York day_number: 4 day_short: Wed day_full: Wednesday timezone: America/New_York - unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T18:30:47+01:00' rfc2822: Wed, 15 Apr 2026 18:30:47 +0100 human: April 15, 2026, 6:30 PM Europe/London day_number: 4 day_short: Wed day_full: Wednesday timezone: Europe/London BulkErrorExample: summary: Per-item bulk failure wrapper value: error: code: INVALID_PARAMETER message: Unsupported timezone identifier. request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' item: Mars/Olympus CurrentBulkPartialFailureExample: summary: Bulk current-time response with a per-item failure value: - unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/New_York day_number: 4 day_short: Wed day_full: Wednesday timezone: America/New_York - error: code: INVALID_PARAMETER message: Unsupported timezone identifier. request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' item: Mars/Olympus ConvertSingleExample: summary: Converted timestamp payload value: unix: 1711300000 unix_ms: 1711300000000 utc: '2024-03-24T18:53:20Z' iso_local: '2024-03-24T14:53:20-04:00' rfc2822: Sun, 24 Mar 2024 14:53:20 -0400 human: March 24, 2024, 2:53 PM America/New_York day_number: 1 day_short: Sun day_full: Sunday timezone: America/New_York formatted: '2024-03-24 14:53' ConvertBulkExample: summary: Bulk convert response value: - unix: 1711300000 unix_ms: 1711300000000 utc: '2024-03-24T18:53:20Z' iso_local: '2024-03-24T14:53:20-04:00' rfc2822: Sun, 24 Mar 2024 14:53:20 -0400 human: March 24, 2024, 2:53 PM America/New_York day_number: 1 day_short: Sun day_full: Sunday timezone: America/New_York - unix: 1711300000 unix_ms: 1711300000000 utc: '2024-03-24T18:53:20Z' iso_local: '2024-03-24T18:53:20+00:00' rfc2822: Sun, 24 Mar 2024 18:53:20 +0000 human: March 24, 2024, 6:53 PM UTC+00:00 day_number: 1 day_short: Sun day_full: Sunday timezone: null ConvertBulkPartialFailureExample: summary: Bulk convert response with a per-item failure value: - unix: 1711300000 unix_ms: 1711300000000 utc: '2024-03-24T18:53:20Z' iso_local: '2024-03-24T14:53:20-04:00' rfc2822: Sun, 24 Mar 2024 14:53:20 -0400 human: March 24, 2024, 2:53 PM America/New_York day_number: 1 day_short: Sun day_full: Sunday timezone: America/New_York - error: code: INVALID_PARAMETER message: Unsupported timezone identifier. request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' item: Mars/Olympus DiffExample: summary: Duration between two instants value: seconds: 3600 minutes: 60 hours: 1 days: 0 direction: forward human: 1 hour formatted: 1h 0m 0s business_days: 0 from: unix_ms: 1711300000000 to: unix_ms: 1711303600000 AddExample: summary: Adjusted timestamp payload value: unix: 1711386400 unix_ms: 1711386400000 utc: '2024-03-25T18:53:20Z' iso_local: '2024-03-25T14:53:20-04:00' rfc2822: Mon, 25 Mar 2024 14:53:20 -0400 human: March 25, 2024, 2:53 PM America/New_York day_number: 2 day_short: Mon day_full: Monday timezone: America/New_York formatted: '2024-03-25 14:53' CalendarExample: summary: Calendar projection with week number value: unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/New_York day_number: 4 day_short: Wed day_full: Wednesday timezone: America/New_York year: 2026 month: 4 month_name: April day: 15 week_number: 16 DstExample: summary: DST status with next transition value: unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/New_York day_number: 4 day_short: Wed day_full: Wednesday timezone: America/New_York dst_active: true next_transition: '2026-11-01T02:00:00-04:00' ClockDigitalHtmlExample: summary: Abbreviated digital clock HTML fragment value: '

' ClockAnalogHtmlExample: summary: Abbreviated analog clock HTML fragment value: '

' ElapsedExample: summary: Remaining duration with business-day count value: seconds: 172800 minutes: 2880 hours: 48 days: 2 human: 2 days left direction: left formatted: 2d 0h 0m 0s business_days: 2 TimezoneResolvedExample: summary: Resolved timezone payload value: unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/New_York day_number: 4 day_short: Wed day_full: Wednesday timezone: America/New_York offset: -240 dst: true TimezoneOffsetExample: summary: Offset match response with matching zones value: unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM UTC-04:00 day_number: 4 day_short: Wed day_full: Wednesday timezone: null offset: -240 dst: false matching_zones: - unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/New_York day_number: 4 day_short: Wed day_full: Wednesday timezone: America/New_York offset: -240 dst: true - unix: 1776274247 unix_ms: 1776274247883 utc: '2026-04-15T17:30:47Z' iso_local: '2026-04-15T13:30:47-04:00' rfc2822: Wed, 15 Apr 2026 13:30:47 -0400 human: April 15, 2026, 1:30 PM America/Toronto day_number: 4 day_short: Wed day_full: Wednesday timezone: America/Toronto offset: -240 dst: true InvalidParameterExample: summary: Generic invalid-parameter error value: error: code: INVALID_PARAMETER message: Invalid offset. Use +HH:MM or -HH:MM. request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' AmbiguousTargetExample: summary: Ambiguous target selector error value: error: code: AMBIGUOUS_TARGET message: Ambiguous target selectors. Provide only one of tz, ip, lat/lon, or offset. request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' ClockInvalidStyleExample: summary: Invalid clock style error value: error: code: INVALID_PARAMETER message: Clock endpoint requires a valid named style. details: valid_styles: - analog-station - analog-aviation - digital-dashboard request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' DependencyNotReadyExample: summary: Missing resolver binding value: error: code: DEPENDENCY_NOT_READY message: Timezone resolver binding is not configured. request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' InternalErrorExample: summary: Internal gateway or core failure value: error: code: INTERNAL_ERROR message: Internal server error. request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' UpstreamFailureExample: summary: Core forwarding failure value: error: code: INTERNAL_ERROR message: Failed to forward request to core worker. details: cause: upstream failure request_id: 0f8fad5b-d9cb-469f-a165-70867728950e timestamp: '2026-04-15T17:30:47.883Z' responses: AuthenticatedBadRequest: description: Invalid or ambiguous request parameters. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidParameter: $ref: '#/components/examples/InvalidParameterExample' ambiguousTarget: $ref: '#/components/examples/AmbiguousTargetExample' MethodNotAllowed: description: Only `GET` is supported. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' DependencyNotReady: description: A required resolver or dependency is not configured or not ready. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: dependencyNotReady: $ref: '#/components/examples/DependencyNotReadyExample' InternalError: description: Internal server error, including signing failures. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: $ref: '#/components/examples/InternalErrorExample' UpstreamFailure: description: Gateway failed to forward the request to the core worker. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: upstreamFailure: $ref: '#/components/examples/UpstreamFailureExample' schemas: ApiError: type: object required: - code - message properties: code: type: string enum: - AMBIGUOUS_TARGET - MISSING_TARGET - INVALID_PARAMETER - INVALID_TIMESTAMP - DEPENDENCY_NOT_READY - SIGNING_NOT_READY - METHOD_NOT_ALLOWED - NOT_FOUND - INTERNAL_ERROR message: type: string details: description: Optional implementation-specific detail payload. nullable: true ErrorResponse: type: object required: - error - request_id properties: error: $ref: '#/components/schemas/ApiError' request_id: type: string timestamp: type: string format: date-time description: Present on most gateway and core errors. BulkError: description: Per-item error wrapper used inside bulk arrays returned by bulk-capable routes. allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object required: - item properties: item: type: string TimePayload: title: Single time payload description: Canonical single-target time payload. type: object required: - unix - unix_ms - utc - iso_local - rfc2822 - human - day_number - day_short - day_full - timezone properties: unix: type: integer format: int64 unix_ms: type: integer format: int64 utc: type: string format: date-time iso_local: type: string nullable: true rfc2822: type: string human: type: string day_number: type: integer minimum: 1 maximum: 7 day_short: type: string day_full: type: string timezone: type: string nullable: true formatted: type: string TimePayloadBulkItem: title: Bulk time payload item description: One bulk array item, either a successful time payload or a per-item bulk error. oneOf: - $ref: '#/components/schemas/TimePayload' - $ref: '#/components/schemas/BulkError' TimePayloadBulkResponse: title: Bulk time payload array description: Bulk response array returned when `/v1/time/current` or `/v1/time/convert` receives one comma-separated `tz`, `ip`, or `offset` selector. type: array items: $ref: '#/components/schemas/TimePayloadBulkItem' DiffEndpointRef: description: Resolved endpoint reference for diff calculations. This object intentionally includes only the resolved epoch-millisecond instant. type: object required: - unix_ms properties: unix_ms: type: integer format: int64 DiffResponse: type: object required: - seconds - minutes - hours - days - direction - human - from - to properties: seconds: type: integer minutes: type: integer hours: type: integer days: type: integer direction: description: '`forward` means `to` is after `from`. `backward` means `to` is before `from`. `same` means both sides resolve to the same instant.' type: string enum: - forward - backward - same human: type: string formatted: type: string business_days: type: integer from: $ref: '#/components/schemas/DiffEndpointRef' to: $ref: '#/components/schemas/DiffEndpointRef' CalendarResponse: allOf: - $ref: '#/components/schemas/TimePayload' - type: object required: - year - month - month_name - day properties: year: type: integer month: type: integer month_name: type: string day: type: integer week_number: type: integer DstResponse: allOf: - $ref: '#/components/schemas/TimePayload' - type: object required: - dst_active properties: dst_active: type: boolean next_transition: type: string format: date-time nullable: true ElapsedResponse: type: object required: - seconds - minutes - hours - days - human - direction properties: seconds: type: integer minutes: type: integer hours: type: integer days: type: integer human: type: string direction: description: '`left` means the target instant is still in the future. `passed` means the target instant is already in the past.' type: string enum: - left - passed formatted: type: string business_days: type: integer TimezoneResolvedResponse: title: Resolved timezone response description: Standard single-target timezone resolution payload. allOf: - $ref: '#/components/schemas/TimePayload' - type: object required: - offset - dst properties: offset: type: integer dst: type: boolean TimezoneMatch: allOf: - $ref: '#/components/schemas/TimePayload' - type: object required: - offset - dst - timezone properties: offset: type: integer dst: type: boolean timezone: type: string TimezoneOffsetResponse: title: Offset match response description: Offset-based timezone lookup result with `matching_zones` for the current request-time offset match. allOf: - $ref: '#/components/schemas/TimezoneResolvedResponse' - type: object required: - matching_zones properties: timezone: type: string nullable: true matching_zones: type: array items: $ref: '#/components/schemas/TimezoneMatch' JwkKey: type: object required: - kty - crv - alg - use - kid - x properties: kty: type: string enum: - OKP crv: type: string enum: - Ed25519 alg: type: string enum: - EdDSA use: type: string enum: - sig kid: type: string x: type: string JwksResponse: type: object required: - keys properties: keys: type: array items: $ref: '#/components/schemas/JwkKey'