{"openapi":"3.0.3","info":{"title":"BizDay API","version":"1.0.0","description":"REST API for business/workday calculations — check if a date is a workday, find the next workday, add workdays, and count workdays between dates for 30+ countries with public holiday awareness.","contact":{"url":"https://bizday.dev"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.bizday.dev","description":"Production"}],"security":[{"BearerAuth":[]}],"paths":{"/v1/check":{"get":{"operationId":"checkWorkday","summary":"Check if a date is a workday","description":"Determine whether a specific date is a business day in a given country, accounting for weekends and public holidays.","parameters":[{"$ref":"#/components/parameters/date"},{"$ref":"#/components/parameters/country"}],"responses":{"200":{"description":"Workday check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResponse"},"example":{"success":true,"data":{"date":"2026-12-25","country":"GB","is_workday":false,"reason":"public_holiday","holiday":{"name":"Christmas Day","local_name":"Christmas Day","type":"Public"}},"meta":{"country":"GB","requested_date":"2026-12-25","cached":false,"timestamp":"2026-03-05T10:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/next":{"get":{"operationId":"nextWorkday","summary":"Find the next or previous workday","description":"Find the next (or previous) business day from a given date, skipping weekends and public holidays.","parameters":[{"name":"date","in":"query","description":"Date in YYYY-MM-DD format. Defaults to today if omitted.","schema":{"type":"string","format":"date","example":"2026-12-24"}},{"$ref":"#/components/parameters/country"},{"name":"direction","in":"query","description":"Search direction.","schema":{"type":"string","enum":["next","prev"],"default":"next"}}],"responses":{"200":{"description":"Next/previous workday result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NextResponse"},"example":{"success":true,"data":{"from_date":"2026-12-24","country":"GB","direction":"next","workday":"2026-12-29"},"meta":{"country":"GB","requested_date":"2026-12-24","cached":false,"timestamp":"2026-03-05T10:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/add":{"get":{"operationId":"addWorkdays","summary":"Add workdays to a date","description":"Add (or subtract) a number of business days to a date, skipping weekends and public holidays.","parameters":[{"$ref":"#/components/parameters/date"},{"$ref":"#/components/parameters/country"},{"name":"days","in":"query","required":true,"description":"Number of workdays to add. Negative values subtract. Range: -365 to 365, non-zero.","schema":{"type":"integer","minimum":-365,"maximum":365,"example":10}}],"responses":{"200":{"description":"Date with workdays added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddResponse"},"example":{"success":true,"data":{"start_date":"2026-03-05","country":"US","workdays_added":10,"result_date":"2026-03-19","weekends_skipped":4,"holidays_skipped":0},"meta":{"country":"US","requested_date":"2026-03-05","cached":false,"timestamp":"2026-03-05T10:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/between":{"get":{"operationId":"workdaysBetween","summary":"Count workdays between two dates","description":"Calculate the number of business days between two dates (start exclusive, end inclusive). Maximum range: 366 days.","parameters":[{"name":"start","in":"query","required":true,"description":"Start date (exclusive) in YYYY-MM-DD format.","schema":{"type":"string","format":"date","example":"2026-03-01"}},{"name":"end","in":"query","required":true,"description":"End date (inclusive) in YYYY-MM-DD format.","schema":{"type":"string","format":"date","example":"2026-03-31"}},{"$ref":"#/components/parameters/country"}],"responses":{"200":{"description":"Workday count between dates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BetweenResponse"},"example":{"success":true,"data":{"country":"DE","start_date":"2026-03-01","end_date":"2026-03-31","workdays":22,"weekends":8,"holidays":0,"holiday_list":[]},"meta":{"country":"DE","cached":false,"timestamp":"2026-03-05T10:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/countries":{"get":{"operationId":"listCountries","summary":"List supported countries","description":"Returns all countries supported by the API. This endpoint does not require authentication.","security":[],"parameters":[],"responses":{"200":{"description":"List of supported countries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"},"example":{"success":true,"data":{"countries":[{"code":"AU","name":"Australia"},{"code":"GB","name":"United Kingdom"},{"code":"US","name":"United States"}],"count":30},"meta":{"timestamp":"2026-03-05T10:00:00.000Z"}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/deadline/calculate":{"post":{"operationId":"calculateAgentDeadline","summary":"Calculate an auditable deadline for an AI agent","description":"Calculate safe business deadlines for AI agents, SaaS workflows, SLAs, invoices, follow-ups, and business operations. Returns skipped days, audit metadata, and a plain-language explanation.","requestBody":{"$ref":"#/components/requestBodies/DeadlineRequest"},"responses":{"200":{"description":"Auditable deadline calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeadlineResponse"},"example":{"success":true,"data":{"deadline":"2026-05-11T17:00:00","deadline_date":"2026-05-11","deadline_time":"17:00","timezone":"Europe/London","country":"GB","deadline_type":"sla","start_date":"2026-05-04","business_days_added":5,"weekends_skipped":2,"holidays_skipped":[],"skipped":[{"date":"2026-05-09","reason":"weekend"},{"date":"2026-05-10","reason":"weekend"}],"safe_for_agent":true,"explanation":"5 GB business days from 2026-05-04 lands on 2026-05-11 for this SLA deadline."}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/decide":{"post":{"operationId":"makeAgentDecision","summary":"Make one business-safe decision for an AI agent","description":"Preferred endpoint for autonomous agents. Returns decision status, result, safe_for_agent, confidence, explanation, audit receipt, estimated token savings, and metered price metadata.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideRequest"},"example":{"decision":"sla_deadline","context":{"date":"2026-05-04","country":"GB","business_days":5,"timezone":"Europe/London"},"agent_id":"agent_support_01"}}}},"responses":{"200":{"description":"Agent decision response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/decide/batch":{"post":{"operationId":"makeAgentDecisionBatch","summary":"Make up to 25 business-safe decisions for an AI agent","description":"Batch version of /v1/decide for high-volume agent workflows. Each decision supports quote mode, max_price_usd, budget_remaining_usd, and idempotency_key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideBatchRequest"}}}},"responses":{"200":{"description":"Batch decision response"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/decide/capabilities":{"get":{"operationId":"getAgentDecisionCapabilities","summary":"List supported agent decisions, prices, and token-savings estimates","description":"Public endpoint agents can call before authentication to understand what Bizday can decide and what each decision costs.","security":[],"responses":{"200":{"description":"Decision capability catalog"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/sla/calculate":{"post":{"operationId":"calculateSlaDeadline","summary":"Calculate an SLA deadline","description":"Alias for /v1/deadline/calculate with deadline_type defaulting to sla.","requestBody":{"$ref":"#/components/requestBodies/DeadlineRequest"},"responses":{"200":{"description":"SLA deadline response"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/invoice/due-date":{"post":{"operationId":"calculateInvoiceDueDate","summary":"Calculate an invoice due date","description":"Alias for /v1/deadline/calculate with deadline_type defaulting to invoice and 30 business days unless overridden.","requestBody":{"$ref":"#/components/requestBodies/DeadlineRequest"},"responses":{"200":{"description":"Invoice due date response"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/follow-up/next-safe-time":{"post":{"operationId":"calculateFollowUpDeadline","summary":"Calculate the next safe follow-up deadline","description":"Alias for /v1/deadline/calculate with deadline_type defaulting to follow_up.","requestBody":{"$ref":"#/components/requestBodies/DeadlineRequest"},"responses":{"200":{"description":"Follow-up deadline response"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/send-time/next-safe":{"post":{"operationId":"findNextSafeSendTime","summary":"Find the next safe send time","description":"Adjust a proposed email, call, SMS, task, or follow-up time to a business-safe date and window.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTimeRequest"}}}},"responses":{"200":{"description":"Safe send time response"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/receipts/create":{"post":{"operationId":"createAgentReceipt","summary":"Create an agent action receipt","description":"Create a structured receipt for an agent action, purchase, or tool call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptRequest"}}}},"responses":{"200":{"description":"Receipt response"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/budget/check":{"post":{"operationId":"checkAgentBudget","summary":"Check whether an agent spend is allowed","description":"Evaluate budget remaining, approval thresholds, and vendor allowlists before an agent spends money.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetRequest"}}}},"responses":{"200":{"description":"Budget decision response"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/readiness/audit":{"post":{"operationId":"auditAgentReadiness","summary":"Audit whether a business is ready for AI agents","description":"Score OpenAPI, llms.txt, MCP, pricing, auth docs, and machine-readable errors for agent readiness.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessRequest"}}}},"responses":{"200":{"description":"Agent readiness score"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key prefixed with wday_. Pass via Authorization: Bearer wday_your_api_key"}},"parameters":{"date":{"name":"date","in":"query","required":true,"description":"Date in YYYY-MM-DD format.","schema":{"type":"string","format":"date","example":"2026-03-05"}},"country":{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 country code (e.g. US, GB, DE).","schema":{"type":"string","minLength":2,"maxLength":2,"example":"US"}}},"schemas":{"Meta":{"type":"object","properties":{"country":{"type":"string","example":"GB"},"requested_date":{"type":"string","format":"date","example":"2026-03-05"},"cached":{"type":"boolean","example":false},"timestamp":{"type":"string","format":"date-time"}}},"ErrorBody":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_DATE"},"message":{"type":"string","example":"Date must be in YYYY-MM-DD format."},"docs":{"type":"string","format":"uri","example":"https://bizday.dev/docs/errors#INVALID_DATE"}}}}},"Holiday":{"type":"object","properties":{"name":{"type":"string","example":"Christmas Day"},"local_name":{"type":"string","example":"Christmas Day"},"type":{"type":"string","example":"Public"}}},"CheckResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["date","country","is_workday"],"properties":{"date":{"type":"string","format":"date"},"country":{"type":"string"},"is_workday":{"type":"boolean"},"reason":{"type":"string","description":"Why the date is not a workday (e.g. \"public_holiday\", \"weekend\")."},"holiday":{"$ref":"#/components/schemas/Holiday"}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"NextResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["from_date","country","direction","workday"],"properties":{"from_date":{"type":"string","format":"date"},"country":{"type":"string"},"direction":{"type":"string","enum":["next","previous"]},"workday":{"type":"string","format":"date"}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"AddResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["start_date","country","workdays_added","result_date","weekends_skipped","holidays_skipped"],"properties":{"start_date":{"type":"string","format":"date"},"country":{"type":"string"},"workdays_added":{"type":"integer"},"result_date":{"type":"string","format":"date"},"weekends_skipped":{"type":"integer"},"holidays_skipped":{"type":"integer"}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"BetweenResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["country","start_date","end_date","workdays","weekends","holidays","holiday_list"],"properties":{"country":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"workdays":{"type":"integer"},"weekends":{"type":"integer"},"holidays":{"type":"integer"},"holiday_list":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"name":{"type":"string"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"CountriesResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["countries","count"],"properties":{"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"US"},"name":{"type":"string","example":"United States"}}}},"count":{"type":"integer","example":30}}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}}}}},"DeadlineResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deadline":{"type":"string","example":"2026-05-11T17:00:00"},"deadline_date":{"type":"string","format":"date"},"deadline_time":{"type":"string","example":"17:00"},"timezone":{"type":"string","example":"Europe/London"},"country":{"type":"string","example":"GB"},"deadline_type":{"type":"string","enum":["custom","sla","invoice","follow_up"]},"start_date":{"type":"string","format":"date"},"business_days_added":{"type":"integer","example":5},"safe_for_agent":{"type":"boolean","example":true},"explanation":{"type":"string"}}}}},"DecideRequest":{"type":"object","required":["decision","context"],"properties":{"decision":{"type":"string","enum":["deadline","sla_deadline","invoice_due_date","safe_send_time","budget_check","receipt","readiness_audit"]},"context":{"type":"object","description":"Decision-specific context. For SLA deadlines include date, country, business_days, timezone, and optional due_time."},"agent_id":{"type":"string"},"workflow_id":{"type":"string"},"external_id":{"type":"string"},"mode":{"type":"string","enum":["execute","quote"],"default":"execute"},"max_price_usd":{"type":"number","example":0.01},"budget_remaining_usd":{"type":"number","example":1.25},"idempotency_key":{"type":"string","example":"ticket_123_sla_deadline"}}},"DecideBatchRequest":{"type":"object","required":["decisions"],"properties":{"decisions":{"type":"array","maxItems":25,"items":{"$ref":"#/components/schemas/DecideRequest"}}}},"DecideResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"decision":{"type":"string","example":"sla_deadline"},"status":{"type":"string","enum":["approved","blocked","ready"]},"result":{"type":"object"},"safe_for_agent":{"type":"boolean","example":true},"confidence":{"type":"number","example":0.99},"explanation":{"type":"string"},"audit":{"type":"object"},"meter":{"type":"object","properties":{"price_usd":{"type":"string","example":"0.005"},"unit":{"type":"string","example":"decision"},"estimated_tokens_saved":{"type":"integer","example":950},"billing_mode":{"type":"string","example":"metered_ready"}}}}}}},"DeadlineRequest":{"type":"object","required":["date","country"],"properties":{"date":{"type":"string","format":"date","example":"2026-05-04"},"start_date":{"type":"string","format":"date","example":"2026-05-04"},"country":{"type":"string","example":"GB"},"days":{"type":"integer","example":5},"business_days":{"type":"integer","example":5},"deadline_type":{"type":"string","enum":["custom","sla","invoice","follow_up"]},"timezone":{"type":"string","example":"Europe/London"},"due_time":{"type":"string","example":"17:00"},"agent_id":{"type":"string"},"workflow_id":{"type":"string"},"external_id":{"type":"string"}}},"SendTimeRequest":{"type":"object","required":["date","country"],"properties":{"date":{"type":"string","format":"date"},"local_time":{"type":"string","example":"18:30"},"country":{"type":"string","example":"GB"},"timezone":{"type":"string","example":"Europe/London"},"earliest_time":{"type":"string","example":"09:00"},"latest_time":{"type":"string","example":"17:00"},"channel":{"type":"string","enum":["email","call","sms","task","follow_up"]}}},"ReceiptRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","example":"purchased_api_call"},"vendor":{"type":"string","example":"Bizday"},"amount":{"type":"number","example":0.01},"currency":{"type":"string","example":"USD"},"agent_id":{"type":"string"},"workflow_id":{"type":"string"},"external_id":{"type":"string"},"metadata":{"type":"object"}}},"BudgetRequest":{"type":"object","required":["amount","budget_remaining"],"properties":{"amount":{"type":"number","example":0.01},"currency":{"type":"string","example":"USD"},"budget_remaining":{"type":"number","example":10},"vendor":{"type":"string","example":"Bizday"},"vendor_allowlist":{"type":"array","items":{"type":"string"}},"require_approval_over":{"type":"number","example":50},"agent_id":{"type":"string"},"workflow_id":{"type":"string"}}},"ReadinessRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"has_openapi":{"type":"boolean"},"has_llms_txt":{"type":"boolean"},"has_mcp":{"type":"boolean"},"has_pricing":{"type":"boolean"},"has_auth_docs":{"type":"boolean"},"has_machine_readable_errors":{"type":"boolean"}}}},"requestBodies":{"DeadlineRequest":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeadlineRequest"}}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Monthly request limit"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests this month"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"When the limit resets (1st of next month)"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until burst limit resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}}