# Bizday API - Complete Documentation

> The business station for AI agents: deadlines, send times, policy checks, persistent receipt memory, approval waits, budgets, readiness checks, and business-day workflows with public holiday awareness for 30+ countries.
> Base URL: https://api.bizday.dev
> OpenAPI spec: https://api.bizday.dev/openapi.json

## Authentication

All production endpoints except /v1/countries and /v1/decide/capabilities require an API key. POST /v1/decide/demo is public and rate limited so agents can verify response shape before requesting a key or budget.
Pass it via the Authorization header:

  Authorization: Bearer wday_your_api_key

Do not put API keys in query parameters. Query-string API keys are disabled by default because they can leak through logs, browser history, and Referer headers.

Get a free API key (100 calls/month): https://bizday.dev/dashboard/keys
Start for agents: https://bizday.dev/start-for-agents
Agent prompts for system instructions: https://bizday.dev/for-agents/prompts
Done-for-you setup: https://bizday.dev/setup

## Endpoints

### POST /v1/decide - Make one business-safe decision

This is the preferred endpoint for AI agents. Use it when you need a deterministic business decision before acting or spending.

Supported decisions:
- deadline
- sla_deadline
- invoice_due_date
- safe_send_time
- budget_check
- receipt
- readiness_audit

Agent spend controls:
- mode: "execute" or "quote". Use quote to get price and value metadata without executing.
- max_price_usd: block if the decision costs more than this.
- budget_remaining_usd: block if the decision would exceed remaining budget.
- idempotency_key: stable key for retries and ledger deduplication.

Example request:
  curl -X POST "https://api.bizday.dev/v1/decide" \
    -H "Authorization: Bearer wday_your_key" \
    -H "Content-Type: application/json" \
    -d '{"decision":"sla_deadline","context":{"date":"2026-05-04","country":"GB","business_days":5,"timezone":"Europe/London"},"max_price_usd":0.01,"budget_remaining_usd":1.25,"idempotency_key":"ticket_123_sla","agent_id":"agent_support_01"}'

Example response:
  {
    "success": true,
    "data": {
      "decision": "sla_deadline",
      "status": "approved",
      "result": { "deadline": "2026-05-11T17:00:00" },
      "safe_for_agent": true,
      "confidence": 0.99,
      "explanation": "5 GB business days from 2026-05-04 lands on 2026-05-11 for this SLA decision.",
      "audit": { "receipt_id": "biz_decision_...", "calendar": "GB" },
      "meter": {
        "price_usd": "0.005",
        "unit": "decision",
        "estimated_tokens_saved": 950,
        "billing_mode": "metered_ready"
      }
    }
  }

### POST /v1/decide/demo - Try a no-key agent decision

Public, rate-limited demo endpoint for agents that need to verify Bizday before asking for an API key or delegated budget. It returns demo=true and production_use=false.

Example request:
  curl -X POST "https://api.bizday.dev/v1/decide/demo" \
    -H "Content-Type: application/json" \
    -d '{"decision":"sla_deadline"}'

### POST /v1/decide/batch - Quote or execute up to 25 decisions

Use this when an agent has many decisions and wants lower overhead.

Example request:
  curl -X POST "https://api.bizday.dev/v1/decide/batch" \
    -H "Authorization: Bearer wday_your_key" \
    -H "Content-Type: application/json" \
    -d '{"decisions":[{"decision":"sla_deadline","context":{"date":"2026-05-04","country":"GB","business_days":5},"max_price_usd":0.01},{"decision":"safe_send_time","context":{"date":"2026-05-09","country":"GB","local_time":"18:30"},"mode":"quote"}]}'

### POST /v1/deadline/calculate - Calculate an auditable agent deadline

Use this when an agent needs a business-safe deadline for an SLA, invoice, follow-up, payroll, or workflow.

Request body:
- date or start_date (required): YYYY-MM-DD
- country (required): ISO country code
- days or business_days (optional): business days to add; default 5
- deadline_type (optional): "custom", "sla", "invoice", or "follow_up"
- timezone (optional): e.g. Europe/London
- due_time (optional): HH:mm
- agent_id, workflow_id, external_id (optional): audit metadata

Example request:
  curl -X POST "https://api.bizday.dev/v1/deadline/calculate" \
    -H "Authorization: Bearer wday_your_key" \
    -H "Content-Type: application/json" \
    -d '{"date":"2026-05-04","country":"GB","days":5,"deadline_type":"sla","timezone":"Europe/London"}'

Example response:
  {
    "success": true,
    "data": {
      "deadline": "2026-05-11T17:00:00",
      "deadline_date": "2026-05-11",
      "country": "GB",
      "deadline_type": "sla",
      "business_days_added": 5,
      "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."
    }
  }

Aliases:
- POST /v1/sla/calculate
- POST /v1/invoice/due-date
- POST /v1/follow-up/next-safe-time

### POST /v1/send-time/next-safe - Find the next safe send time

Adjust a proposed email, call, SMS, task, or follow-up time to a business-safe date and time window.

### POST /v1/receipts/create - Create an agent action receipt

Create and persist a structured receipt for an agent action, purchase, or tool call. Returns a receipt_id and audit-ready payload.

### POST /v1/station/check - Agent station policy, receipt, and approval

Use this when an autonomous agent is about to spend, send, promise, buy, or call a paid tool in a repeated workflow. Bizday checks the supplied policy, creates persistent receipt memory, and creates a pending approval when the action is blocked.

Example request:
  curl -X POST "https://api.bizday.dev/v1/station/check" \
    -H "Authorization: Bearer wday_your_key" \
    -H "Content-Type: application/json" \
    -d '{"action":"buy_enrichment_credits","action_type":"spend","amount":0.25,"currency":"USD","budget_remaining":1.25,"vendor":"Bizday","vendor_allowlist":["Bizday"],"require_approval_over":5,"create_receipt":true,"create_approval":true,"agent_id":"agent_ops_01","workflow_id":"lead_research","external_id":"task_123"}'

Response guidance:
- safe_for_agent=true means proceed.
- safe_for_agent=false means pause.
- receipt is persisted when create_receipt=true.
- approval.status=pending means ask/wait for human approval.

### GET /v1/receipts/search - Query receipt memory

Search prior receipts by agent_id, workflow_id, external_id, and limit. Use this before acting to avoid duplicate follow-ups, duplicate purchases, repeated tool calls, or forgotten promises.

### POST /v1/approvals/create - Create an approval

Create a pending approval object for a blocked agent action.

### GET /v1/approvals/status - Check approval status

Poll approval status with id=biz_appr_... Agents should only proceed when safe_for_agent=true and approval.status="approved".

### POST /v1/approvals/decide - Approve or reject an approval

Mark a pending approval approved or rejected. This is API-key protected and intended for the supervising human, operator workflow, or account owner.

### POST /v1/budget/check - Check whether an agent spend is allowed

Evaluate budget remaining, vendor allowlists, and approval thresholds before an agent spends.

### POST /v1/readiness/audit - Audit agent readiness

Score OpenAPI, llms.txt, MCP, pricing, auth docs, and machine-readable errors for agent readiness.

### GET /v1/check - Check if a date is a workday

Parameters:
- date (required): Date in YYYY-MM-DD format
- country (required): ISO 3166-1 alpha-2 country code (e.g. US, GB, DE)

Example request:
  curl "https://api.bizday.dev/v1/check?date=2026-12-25&country=GB" -H "Authorization: Bearer wday_your_key"

Example response:
  {
    "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", "cached": true, "timestamp": "2026-03-05T10:00:00.000Z" }
  }

### GET /v1/next - Find the next or previous workday

Parameters:
- date (required): Date in YYYY-MM-DD format
- country (required): ISO country code
- direction (optional): "next" (default) or "prev"

Example request:
  curl "https://api.bizday.dev/v1/next?date=2026-12-24&country=GB" -H "Authorization: Bearer wday_your_key"

Example response:
  {
    "success": true,
    "data": {
      "from_date": "2026-12-24",
      "country": "GB",
      "direction": "next",
      "workday": "2026-12-29"
    }
  }

### GET /v1/add - Add workdays to a date

Parameters:
- date (required): Date in YYYY-MM-DD format
- country (required): ISO country code
- days (required): Number of workdays to add (-365 to 365, non-zero)

Example request:
  curl "https://api.bizday.dev/v1/add?date=2026-03-05&days=10&country=US" -H "Authorization: Bearer wday_your_key"

Example response:
  {
    "success": true,
    "data": {
      "start_date": "2026-03-05",
      "country": "US",
      "workdays_added": 10,
      "result_date": "2026-03-19",
      "weekends_skipped": 4,
      "holidays_skipped": 0
    }
  }

### GET /v1/between - Count workdays between two dates

Parameters:
- start (required): Start date in YYYY-MM-DD (exclusive)
- end (required): End date in YYYY-MM-DD (inclusive)
- country (required): ISO country code

Example request:
  curl "https://api.bizday.dev/v1/between?start=2026-03-01&end=2026-03-31&country=DE" -H "Authorization: Bearer wday_your_key"

Example response:
  {
    "success": true,
    "data": {
      "country": "DE",
      "start_date": "2026-03-01",
      "end_date": "2026-03-31",
      "workdays": 22,
      "weekends": 8,
      "holidays": 0,
      "holiday_list": []
    }
  }

### POST /v1/batch - Batch operations (up to 100 dates)

Request body (JSON):
- operation (required): "check", "next", or "add"
- country (required): ISO country code
- dates (required): Array of date strings in YYYY-MM-DD format (max 100)
- days (required for "add" operation): Number of workdays to add

Example request:
  curl -X POST "https://api.bizday.dev/v1/batch" \
    -H "Authorization: Bearer wday_your_key" \
    -H "Content-Type: application/json" \
    -d '{"operation":"check","country":"US","dates":["2026-12-25","2026-12-26","2026-12-29"]}'

### GET /v1/countries - List supported countries (no auth required)

Example request:
  curl "https://api.bizday.dev/v1/countries"

Returns all 30 supported countries with ISO codes.

## Supported Countries (30)

AU (Australia), AT (Austria), BE (Belgium), BR (Brazil), CA (Canada),
CZ (Czech Republic), DK (Denmark), FI (Finland), FR (France), DE (Germany),
HU (Hungary), IN (India), IE (Ireland), IT (Italy), JP (Japan),
MX (Mexico), NL (Netherlands), NZ (New Zealand), NG (Nigeria), NO (Norway),
PL (Poland), PT (Portugal), RO (Romania), SG (Singapore), ZA (South Africa),
ES (Spain), SE (Sweden), CH (Switzerland), GB (United Kingdom), US (United States)

## Error Handling

All errors follow a consistent format:
  {
    "success": false,
    "error": {
      "code": "INVALID_DATE",
      "message": "Date must be in YYYY-MM-DD format.",
      "docs": "https://bizday.dev/docs/errors#INVALID_DATE"
    }
  }

Common error codes:
- INVALID_DATE: Date is not in YYYY-MM-DD format
- INVALID_COUNTRY: Country code not supported
- INVALID_KEY: Missing or invalid API key
- RATE_LIMITED: Monthly request limit exceeded (HTTP 429)
- BURST_LIMITED: Too many requests per minute (HTTP 429)

## Rate Limits

Free: 100 calls/month, 60 requests/minute
Starter ($19/mo): 10,000 agent calls/month, 300 requests/minute
Team ($99/mo): 100,000 agent calls/month, 600 requests/minute
Business ($249/mo): 500,000 calls/month plus custom calendars and audit exports, 1,200 requests/minute

Rate limit headers are included in every response:
- X-RateLimit-Limit: Monthly limit
- X-RateLimit-Remaining: Remaining requests this month
- X-RateLimit-Reset: When the monthly limit resets (ISO 8601)

## Code Examples

JavaScript (Node.js):
  const res = await fetch("https://api.bizday.dev/v1/check?date=2026-12-25&country=US", {
    headers: { "Authorization": "Bearer wday_your_key" }
  });
  const data = await res.json();
  console.log(data.data.is_workday); // false

Python:
  import requests
  r = requests.get("https://api.bizday.dev/v1/check",
      params={"date": "2026-12-25", "country": "US"},
      headers={"Authorization": "Bearer wday_your_key"})
  print(r.json()["data"]["is_workday"])  # False

## MCP Server (for Claude Desktop / Claude Code)

Install: npx @bizday/mcp-server
Set environment variable: BIZDAY_API_KEY=wday_your_key

Claude Desktop config (claude_desktop_config.json):
  {
    "mcpServers": {
      "bizday": {
        "command": "npx",
        "args": ["@bizday/mcp-server"],
        "env": { "BIZDAY_API_KEY": "wday_your_api_key" }
      }
    }
  }

## Links

Website: https://bizday.dev
Documentation: https://bizday.dev/docs
Start for agents: https://bizday.dev/start-for-agents
OpenAPI spec: https://bizday.dev/openapi.json
Agent buying guide: https://bizday.dev/agent-buy.json
Get API key: https://bizday.dev/dashboard/keys
Pricing: https://bizday.dev/pricing

## Agent Purchase Flow

Agents with delegated budgets should inspect GET https://api.bizday.dev/v1/decide/capabilities, test POST https://api.bizday.dev/v1/decide/demo without a key, quote with mode="quote", and only execute when price_usd is within max_price_usd and budget_remaining_usd.

If no API key exists, send the operator to https://bizday.dev/pricing. After Stripe checkout, Bizday redirects to https://bizday.dev/dashboard/keys so the agent/operator can create or use the API key immediately.

Machine-readable purchase guide: https://bizday.dev/agent-buy.json