{ "openapi": "3.1.0", "info": { "title": "Dierum API", "version": "1.3.0", "description": "The calendar-aware date API: business-day arithmetic, due dates, paydays, and holiday calendars for 250+ countries, subdivisions, and financial markets. Free tier: 100 requests/day at POST /v1/signup with an email. Agent-friendly by design: one header, stable error codes, this spec, and /llms.txt.", "contact": { "url": "https://dierum.io/docs" } }, "servers": [ { "url": "https://dierum.io" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key" } }, "responses": { "BadRequest": { "description": "Malformed input; error.code names the field family.", "content": { "application/json": { "example": { "error": { "code": "bad_date", "message": "invoice_date must be yyyy-MM-dd." } } } } }, "Unauthorized": { "description": "Missing or invalid key.", "content": { "application/json": { "example": { "error": { "code": "missing_key", "message": "Pass your API key in the X-Api-Key header." } } } } }, "RateLimited": { "description": "Daily quota reached; X-RateLimit-* headers show standing.", "content": { "application/json": { "example": { "error": { "code": "quota_exceeded", "message": "Daily limit reached." } } } } } } }, "paths": { "/v1/check": { "get": { "summary": "Classify a date", "description": "Is the date a business day, weekend, or holiday in the region? Includes the next business day.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "business_day": false, "weekend": false, "holiday": true, "next_business_day": "2027-11-26" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "description": "Date, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } } ] } }, "/v1/add": { "get": { "summary": "Add business days", "description": "Add or subtract (negative) business days to a date. Use market regions like XNYS for settlement math.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "result": "2027-03-30" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start date, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "days", "in": "query", "required": true, "description": "-5000..5000", "schema": { "type": "integer" } } ] } }, "/v1/count": { "get": { "summary": "Count business days", "description": "Business days between two dates, inclusive.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "business_days": 19 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "Range start, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Range end (inclusive), yyyy-MM-dd", "schema": { "type": "string", "format": "date" } } ] } }, "/v1/due-date": { "get": { "summary": "Invoice due date", "description": "Invoice date plus payment terms (net30, net10b for business days, eom, eom+15), rolled forward off weekends/holidays.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "nominal_due": "2027-02-14", "due_date": "2027-02-16", "rolled": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "invoice_date", "in": "query", "required": true, "description": "yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "terms", "in": "query", "required": true, "description": "net | netb | eom | eom+", "schema": { "type": "string" } } ] } }, "/v1/paydays": { "get": { "summary": "Payday calendar", "description": "A year of pay dates from a rule; dates roll backward off non-working days.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "paydays": [ "2027-01-15", "2027-01-29" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Year, 2020-2035", "schema": { "type": "integer", "minimum": 2020, "maximum": 2035 } }, { "name": "rule", "in": "query", "required": true, "description": "last-business-day | nth:<1-28> | semi:,", "schema": { "type": "string" } } ] } }, "/v1/nth": { "get": { "summary": "Nth business day of each month", "description": "The nth business day per month, from either end. 'Invoice on the 3rd business day' schedules.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "dates": [ "2027-01-06", "2027-02-03" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Year, 2020-2035", "schema": { "type": "integer", "minimum": 2020, "maximum": 2035 } }, { "name": "n", "in": "query", "required": true, "description": "1-23", "schema": { "type": "integer" } }, { "name": "from_end", "in": "query", "required": false, "description": "count backward from month end", "schema": { "type": "boolean" } } ] } }, "/v1/common-days": { "get": { "summary": "Common business days", "description": "Days that are business days in every listed region. Cross-border settlement windows.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "common_business_days": [ "2027-05-28", "2027-06-01" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "regions", "in": "query", "required": true, "description": "2-5 comma-separated region codes", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "Range start, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Range end (inclusive), yyyy-MM-dd", "schema": { "type": "string", "format": "date" } } ] } }, "/v1/window": { "get": { "summary": "Next N business days", "description": "The next N business days from a date, as a list. Date pickers and schedulers.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "business_days": [ "2027-11-24", "2027-11-26" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start date, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "count", "in": "query", "required": false, "description": "1-100, default 10", "schema": { "type": "integer" } } ] } }, "/v1/diff": { "get": { "summary": "Day-type census", "description": "How many business days, weekend days, and holidays a range contains.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "total_days": 90, "business_days": 62, "weekend_days": 25, "holiday_days": 3 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "Range start, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Range end (inclusive), yyyy-MM-dd", "schema": { "type": "string", "format": "date" } } ] } }, "/v1/year": { "get": { "summary": "Year summary", "description": "Business-day totals per month plus the full holiday list for a year.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "business_days_total": 253, "holidays_count": 10 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Year, 2020-2035", "schema": { "type": "integer", "minimum": 2020, "maximum": 2035 } } ] } }, "/v1/bridge-days": { "get": { "summary": "Bridge-day finder", "description": "Leave windows ranked by days-off per PTO day spent.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "windows": [ { "from": "2027-03-25", "to": "2027-03-29", "pto_days": 1, "total_days_off": 5 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": true, "description": "Year, 2020-2035", "schema": { "type": "integer", "minimum": 2020, "maximum": 2035 } }, { "name": "pto", "in": "query", "required": false, "description": "leave budget 1-5", "schema": { "type": "integer" } } ] } }, "/v1/next-holiday": { "get": { "summary": "Next holiday", "description": "Upcoming holidays with a day countdown.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "holidays": [ { "date": "2026-09-07", "name": "Labor Day", "days_until": 7 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "1-10", "schema": { "type": "integer" } } ] } }, "/v1/holidays": { "get": { "summary": "Holiday list", "description": "Raw holiday calendar for a range (max 3 years).", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "holidays": [ { "date": "2027-12-25", "name": "Christmas Day" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "Range start, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Range end (inclusive), yyyy-MM-dd", "schema": { "type": "string", "format": "date" } } ] } }, "/v1/regions": { "get": { "summary": "Region catalog", "description": "Every supported region with its weekend definition (day numbers, Sunday=0).", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "count": 1801, "regions": [ { "code": "US", "kind": "country", "weekend": [ 0, 6 ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/pay-periods": { "get": { "summary": "Pay period generator", "description": "Pay periods with rolled paydays. Rules: weekly/biweekly (anchored on a known payday), semi-monthly, monthly.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "periods": [ { "period_start": "2027-01-23", "period_end": "2027-02-05", "payday": "2027-02-05" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "rule", "in": "query", "required": true, "description": "weekly | biweekly | semi-monthly | monthly", "schema": { "type": "string" } }, { "name": "anchor", "in": "query", "required": false, "description": "known payday, required for weekly/biweekly", "schema": { "type": "string", "format": "date" } }, { "name": "from", "in": "query", "required": true, "description": "Range start, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "count", "in": "query", "required": false, "description": "1-60", "schema": { "type": "integer" } } ] } }, "/v1/add-hours": { "get": { "summary": "Business-hours arithmetic", "description": "Add business hours inside a working window; spills across holidays. Local wall-clock times.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "result_date": "2027-03-30", "result_time": "10:00" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start date, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "time", "in": "query", "required": true, "description": "HH:mm", "schema": { "type": "string" } }, { "name": "hours", "in": "query", "required": true, "description": "0-2000", "schema": { "type": "number" } }, { "name": "window", "in": "query", "required": false, "description": "HH:mm-HH:mm", "schema": { "type": "string" } } ] } }, "/v1/recurrence": { "get": { "summary": "Calendar-aware recurring schedules", "description": "weekly::, nth::, last: with roll policy forward|backward|skip|none.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "dates": [ "2027-01-21", "2027-02-18" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "rule", "in": "query", "required": true, "description": "e.g. nth:3:thu", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start date, yyyy-MM-dd", "schema": { "type": "string", "format": "date" } }, { "name": "count", "in": "query", "required": false, "description": "1-60", "schema": { "type": "integer" } }, { "name": "roll", "in": "query", "required": false, "description": "forward|backward|skip|none", "schema": { "type": "string" } } ] } }, "/v1/quarter": { "get": { "summary": "Fiscal quarter progress", "description": "Quarter containing a date with business days total/elapsed/remaining; custom fiscal-year start month.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "quarter": "Q1", "business_days_remaining": 29 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code: ISO country (US), subdivision (US-CA, DE-BY), or market (XNYS). Full list at /v1/regions.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "defaults to today", "schema": { "type": "string", "format": "date" } }, { "name": "fiscal_start", "in": "query", "required": false, "description": "1-12", "schema": { "type": "integer" } } ] } }, "/v1/batch": { "post": { "summary": "Batch operations", "description": "Up to 100 add/count/check/due-date operations per call (1,000 on Pro+); each metered as one request.", "security": [ { "apiKey": [] }, { "apiKeyQuery": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "count": 2, "results": [ { "result": "2027-03-30" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "operations": [ { "op": "add", "region": "XNYS", "start": "2027-03-25", "days": 2 }, { "op": "due-date", "region": "US", "start": "2027-01-15", "terms": "net30" } ] } } } } } } } }