{ "openapi": "3.1.0", "info": { "title": "Calcadian API", "version": "1.0.0", "summary": "Date, business-day and duration calculations over HTTP.", "description": "All operations are POST, accept a JSON object body and return a JSON object.\n\nAuthentication uses an API key in the `Authorization: Bearer ` header. Keys are environment tagged: `cal_live_` for live, `cal_test_` for sandbox. Keys must never be sent in a query string; requests carrying `?api_key=` are rejected with 401 `API_KEY_IN_QUERY_STRING`.\n\nDates are date-only strings in strict `YYYY-MM-DD` form. Impossible dates such as `2026-02-30` are rejected, never rolled over.\n\nThe monthly quota is account-wide, shared by every API key on the account and by authenticated MCP usage. It resets at the start of each UTC calendar month.", "license": { "name": "Proprietary", "identifier": "LicenseRef-Calcadian" } }, "servers": [ { "url": "https://calcadian.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Date calculations", "description": "Calendar arithmetic that needs no holiday data." }, { "name": "Business day calculations", "description": "Working-day arithmetic. Accepts either a saved Business Calendar id or an inline country/subdivision/working-week specification." } ], "paths": { "/date-difference": { "post": { "operationId": "dateDifference", "summary": "Date difference", "description": "Calendar days, weeks and years/months/days between two dates.", "tags": [ "Date calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "start_date": { "type": "string", "description": "Start date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "description": "End date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "include_end_date": { "type": "boolean", "description": "Add the end date as one extra day. By default the span runs from the start date to the end date, so the end date closes the span and the start date is not counted.", "default": false } }, "required": [ "start_date", "end_date" ] }, "examples": { "default": { "value": { "start_date": "2026-01-01", "end_date": "2026-03-15" } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "start_date": "2026-01-01", "end_date": "2026-03-15", "include_end_date": false, "total_days": 73, "weeks": 10, "remainder_days": 3, "years": 0, "months": 2, "days": 14 }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "RANGE_TOO_LARGE, VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/add-days": { "post": { "operationId": "addDays", "summary": "Add days", "description": "Add or subtract days, weeks, months or years from a date.", "tags": [ "Date calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "start_date": { "type": "string", "description": "Start date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "description": "Amount to add. Negative values subtract.", "minimum": -36500, "maximum": 36500 }, "unit": { "type": "string", "description": "Unit for the amount.", "enum": [ "days", "weeks", "months", "years" ], "default": "days" }, "skip_weekends": { "type": "boolean", "description": "Skip Saturdays and Sundays. Ignores public holidays; use add-business-days for holiday-aware maths.", "default": false } }, "required": [ "start_date", "days" ] }, "examples": { "default": { "value": { "start_date": "2026-01-01", "days": 45 } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "start_date": "2026-01-01", "days": 45, "unit": "days", "skip_weekends": false, "result_date": "2026-02-15", "weekday": "Sunday" }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/business-days-between": { "post": { "operationId": "businessDaysBetween", "summary": "Business days between", "description": "Count working days between two dates using a working week and holiday calendar.", "tags": [ "Business day calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "start_date": { "type": "string", "description": "Start date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "description": "End date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "include_start_date": { "type": "boolean", "description": "Count the start date when it is a working day. Defaults to true, so a working-day span includes both endpoints.", "default": true }, "include_end_date": { "type": "boolean", "description": "Count the end date when it is a working day. Defaults to true, so a working-day span includes both endpoints.", "default": true }, "detailed": { "type": "boolean", "description": "Return a day-by-day trace. Only available for ranges of 400 days or fewer.", "default": false }, "business_calendar_id": { "type": "string", "description": "Id of a saved Business Calendar owned by the API key's account. When supplied, all other calendar fields are ignored. Requires the Business Calendars feature on the account.", "format": "uuid" }, "country_code": { "type": "string", "description": "Two-letter ISO 3166-1 country code used for public holidays.", "default": "US" }, "subdivision_code": { "type": "string", "description": "Region/state code within the country. If supplied and not supported for that country, the request fails with 422 INVALID_SUBDIVISION. There is no silent fallback to national holidays." }, "working_days": { "type": "array", "description": "ISO weekday numbers that count as working days. 1 = Monday, 7 = Sunday. Defaults to [1,2,3,4,5].", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "include_public_holidays": { "type": "boolean", "description": "Whether public holidays for the country/subdivision are treated as non-working days.", "default": true } }, "required": [ "start_date", "end_date" ] }, "examples": { "default": { "value": { "start_date": "2026-01-01", "end_date": "2026-01-31", "country_code": "US" } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "start_date": "2026-01-01", "end_date": "2026-01-31", "business_days": 20, "summary": { "calendar_days_elapsed": 31, "working_days_counted": 20, "non_working_weekdays_skipped": 9, "public_holidays_skipped": 2, "custom_holidays_skipped": 0, "excluded_dates_skipped": 0, "reversed": false, "provider": "date-holidays", "provider_version": "3.x" } }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH, FEATURE_NOT_AVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "BUSINESS_CALENDAR_NOT_FOUND", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "INVALID_COUNTRY, INVALID_SUBDIVISION, RANGE_TOO_LARGE, VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/add-business-days": { "post": { "operationId": "addBusinessDays", "summary": "Add business days", "description": "Move forwards or backwards by a number of working days.", "tags": [ "Business day calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "start_date": { "type": "string", "description": "Start date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "description": "Business days to add. Negative values move backwards.", "minimum": -10000, "maximum": 10000 }, "include_start_date": { "type": "boolean", "description": "Count the start date as day one.", "default": false }, "detailed": { "type": "boolean", "description": "Return a day-by-day trace.", "default": false }, "business_calendar_id": { "type": "string", "description": "Id of a saved Business Calendar owned by the API key's account. When supplied, all other calendar fields are ignored. Requires the Business Calendars feature on the account.", "format": "uuid" }, "country_code": { "type": "string", "description": "Two-letter ISO 3166-1 country code used for public holidays.", "default": "US" }, "subdivision_code": { "type": "string", "description": "Region/state code within the country. If supplied and not supported for that country, the request fails with 422 INVALID_SUBDIVISION. There is no silent fallback to national holidays." }, "working_days": { "type": "array", "description": "ISO weekday numbers that count as working days. 1 = Monday, 7 = Sunday. Defaults to [1,2,3,4,5].", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "include_public_holidays": { "type": "boolean", "description": "Whether public holidays for the country/subdivision are treated as non-working days.", "default": true } }, "required": [ "start_date", "days" ] }, "examples": { "default": { "value": { "start_date": "2026-01-01", "days": 10, "country_code": "GB" } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "start_date": "2026-01-01", "days": 10, "result_date": "2026-01-16", "summary": { "calendar_days_elapsed": 15, "working_days_counted": 10, "non_working_weekdays_skipped": 4, "public_holidays_skipped": 1, "custom_holidays_skipped": 0, "excluded_dates_skipped": 0, "reversed": false, "provider": "date-holidays", "provider_version": "3.x" } }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH, FEATURE_NOT_AVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "BUSINESS_CALENDAR_NOT_FOUND", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "INVALID_COUNTRY, INVALID_SUBDIVISION, VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/is-business-day": { "post": { "operationId": "isBusinessDay", "summary": "Is business day", "description": "Check whether a date is a working day, and find the neighbouring working days.", "tags": [ "Business day calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "description": "Date to check, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "business_calendar_id": { "type": "string", "description": "Id of a saved Business Calendar owned by the API key's account. When supplied, all other calendar fields are ignored. Requires the Business Calendars feature on the account.", "format": "uuid" }, "country_code": { "type": "string", "description": "Two-letter ISO 3166-1 country code used for public holidays.", "default": "US" }, "subdivision_code": { "type": "string", "description": "Region/state code within the country. If supplied and not supported for that country, the request fails with 422 INVALID_SUBDIVISION. There is no silent fallback to national holidays." }, "working_days": { "type": "array", "description": "ISO weekday numbers that count as working days. 1 = Monday, 7 = Sunday. Defaults to [1,2,3,4,5].", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "include_public_holidays": { "type": "boolean", "description": "Whether public holidays for the country/subdivision are treated as non-working days.", "default": true } }, "required": [ "date" ] }, "examples": { "default": { "value": { "date": "2026-01-01", "country_code": "US" } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "date": "2026-01-01", "is_business_day": false, "weekday": 4, "reason": "public_holiday", "label": "New Year's Day", "next_business_day": "2026-01-02", "previous_business_day": "2025-12-31" }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH, FEATURE_NOT_AVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "BUSINESS_CALENDAR_NOT_FOUND", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "INVALID_COUNTRY, INVALID_SUBDIVISION, VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/age": { "post": { "operationId": "age", "summary": "Age", "description": "Exact age in years, months and days, plus totals and the next birthday.", "tags": [ "Date calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "birth_date": { "type": "string", "description": "Date of birth, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "as_of_date": { "type": "string", "description": "Date to calculate the age at. Defaults to today (UTC).", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "birth_date" ] }, "examples": { "default": { "value": { "birth_date": "1990-05-20", "as_of_date": "2026-01-01" } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "birth_date": "1990-05-20", "as_of_date": "2026-01-01", "years": 35, "months": 7, "days": 12, "total_months": 427, "total_weeks": 1858, "total_days": 13010, "born_on": "Sunday", "next_birthday": "2026-05-20", "days_until_next_birthday": 139 }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/time-duration": { "post": { "operationId": "timeDuration", "summary": "Time duration", "description": "Duration between two clock times, with optional dates, overnight shifts and unpaid breaks.", "tags": [ "Date calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "start_time": { "type": "string", "description": "24-hour HH:MM.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end_time": { "type": "string", "description": "24-hour HH:MM.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "start_date": { "type": "string", "description": "Optional start date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "description": "Optional end date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "next_day": { "type": "boolean", "description": "End time falls on the following day.", "default": false }, "break_minutes": { "type": "integer", "description": "Unpaid break subtracted from the total.", "default": 0, "minimum": 0, "maximum": 1440 } }, "required": [ "start_time", "end_time" ] }, "examples": { "default": { "value": { "start_time": "09:00", "end_time": "17:30", "break_minutes": 30 } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "start_time": "09:00", "end_time": "17:30", "break_minutes": 30, "total_minutes": 480, "hours": 8, "minutes": 0, "decimal_hours": 8 }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/week-number": { "post": { "operationId": "weekNumber", "summary": "ISO week number", "description": "ISO-8601 week number, week year and the week's start and end dates.", "tags": [ "Date calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "description": "Date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "date" ] }, "examples": { "default": { "value": { "date": "2026-01-01" } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "date": "2026-01-01", "iso_week": 1, "iso_week_year": 2026, "weekday": 4, "week_start": "2025-12-29", "week_end": "2026-01-04" }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/day-of-week": { "post": { "operationId": "dayOfWeek", "summary": "Day of week", "description": "Weekday name and ISO weekday number for a date.", "tags": [ "Date calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "description": "Date, YYYY-MM-DD.", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "date" ] }, "examples": { "default": { "value": { "date": "2026-01-01" } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "date": "2026-01-01", "weekday": "Thursday", "iso_weekday": 4 }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD, INVALID_DATE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/unix-timestamp": { "post": { "operationId": "unixTimestamp", "summary": "Unix timestamp", "description": "Convert between Unix seconds and ISO-8601. Supply exactly one of timestamp or date_time.", "tags": [ "Date calculations" ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "timestamp": { "type": "number", "description": "Seconds since the Unix epoch. Values above 1e11 are read as milliseconds." }, "date_time": { "type": "string", "description": "ISO-8601 date (YYYY-MM-DD) or date-time to convert." } } }, "examples": { "default": { "value": { "timestamp": 1767225600 } } } } } }, "responses": { "200": { "description": "Successful calculation.", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "examples": { "default": { "value": { "data": { "unix_seconds": 1767225600, "iso_utc": "2026-01-01T00:00:00.000Z", "date": "2026-01-01", "weekday": "Thursday" }, "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" } } } } } } }, "400": { "description": "INVALID_REQUEST, INVALID_JSON, UNKNOWN_FIELD", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, API_KEY_IN_QUERY_STRING", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ENVIRONMENT_MISMATCH", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED, API_QUOTA_EXCEEDED", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "description": "Unique id for this call. Also present as meta.request_id.", "schema": { "type": "string" } }, "x-api-version": { "description": "API version that served the request (v1).", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Requests allowed per minute for the account's plan.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Requests allowed in the current UTC calendar month.", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Requests left in the current UTC calendar month.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Preferred. `Authorization: Bearer cal_live_...`" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternative to the bearer header. Never place the key in a URL." } }, "schemas": { "Meta": { "type": "object", "required": [ "request_id", "api_version" ], "properties": { "request_id": { "type": "string", "pattern": "^req_[0-9a-f]{24}$" }, "api_version": { "type": "string", "const": "v1" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "additionalProperties": true, "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "INVALID_DATE", "INVALID_JSON", "PAYLOAD_TOO_LARGE", "UNKNOWN_FIELD", "MISSING_API_KEY", "INVALID_API_KEY", "REVOKED_API_KEY", "EXPIRED_API_KEY", "API_KEY_IN_QUERY_STRING", "ENVIRONMENT_MISMATCH", "FEATURE_NOT_AVAILABLE", "PLAN_UPGRADE_REQUIRED", "NOT_FOUND", "BUSINESS_CALENDAR_NOT_FOUND", "BUSINESS_CALENDAR_FORBIDDEN", "CONFLICT", "INVALID_COUNTRY", "INVALID_SUBDIVISION", "INVALID_TIMEZONE", "RANGE_TOO_LARGE", "VALIDATION_ERROR", "RATE_LIMIT_EXCEEDED", "API_QUOTA_EXCEEDED", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" }, "request_id": { "type": "string", "pattern": "^req_[0-9a-f]{24}$" } } } }, "examples": [ { "error": { "code": "INVALID_SUBDIVISION", "message": "subdivision_code 'XX' is not supported for country MY.", "request_id": "req_9f2c41a7be03d5710c8e2b44" } } ] } } }, "x-base-path": "/api/v1" }