{
  "openapi": "3.1.0",
  "info": {
    "title": "Paydays API",
    "version": "1.0.0",
    "summary": "Pay calendars for 2026 to 2028 (biweekly, semi-monthly, monthly, weekly, federal, military, Social Security), 50 tech employers with the evidence behind each schedule, and the payday law of every state",
    "description": "Pay calendars for 2026 to 2028 (biweekly, semi-monthly, monthly, weekly, federal, military, Social Security), 50 tech employers with the evidence behind each schedule, and the payday law of every state. Calendars are computed from published rules; sources are checked every Monday. Free to read; please cite \"Paydays (paydays.fru.dev)\" with a link. Responses are cached at the edge; keep to about 60 requests a minute. Guide: https://paydays.fru.dev/agents",
    "contact": {
      "name": "fru.dev",
      "url": "https://fru.dev",
      "email": "fru.dev3@gmail.com"
    }
  },
  "externalDocs": {
    "description": "For AI agents",
    "url": "https://paydays.fru.dev/agents"
  },
  "servers": [
    {
      "url": "https://paydays.fru.dev"
    }
  ],
  "paths": {
    "/api/companies/{slug}": {
      "get": {
        "operationId": "company_paydays",
        "summary": "One company's pay schedule, the evidence behind it, and its paydays for a year",
        "description": "One company's pay schedule, the evidence behind it, and its paydays for a year. Returns the company, its schedule (rule, whether the week is known, source tier, basis), sources with quotes, and paydays per possible week.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Company slug, e.g. meta, google, amd",
            "schema": {
              "type": "string"
            },
            "example": "meta"
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Year, 2026 to 2028 (default: the current year)",
            "schema": {
              "type": "integer",
              "minimum": 2026,
              "maximum": 2028
            },
            "example": 2027
          }
        ],
        "responses": {
          "200": {
            "description": "the company, its schedule (rule, whether the week is known, source tier, basis), sources with quotes, and paydays per possible week",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "slug": "meta",
                  "name": "Meta",
                  "domain": "meta.com",
                  "url": "https://paydays.fru.dev/companies/meta",
                  "schedule": {
                    "frequency": "biweekly",
                    "rule": "Every other Friday",
                    "weekday": "Friday",
                    "days": null,
                    "weekKnown": true,
                    "anchor": "2024-01-19",
                    "tier": "employee-reported",
                    "assumed": [],
                    "basis": "Employee-reported: every other Friday, from 5 employee reports. A reported payday on Jan 19, 2024 fixes the week."
                  },
                  "sources": [
                    {
                      "url": "https://www.teamblind.com/post/did-meta-pay-today-qy40ggoh",
                      "note": "\"There is a wiki with all paydates. It's every two weeks... So on 01/19 you get paid for 1/1-1/14.\" (Blind, 2024-01-12)"
                    },
                    {
                      "url": "https://www.teamblind.com/post/meta-pay-schedule-and-procedure-hv4ftfzn",
                      "note": "\"Yes, 9/16 is the payout for 8/28-9/9.\" (Blind, 2022-08-31)"
                    }
                  ],
                  "checkedAt": "2026-09-24",
                  "year": 2027,
                  "nextPaydays": [
                    "2026-09-25"
                  ],
                  "series": [
                    {
                      "week": null,
                      "label": "Every other Friday",
                      "paydays": [
                        {
                          "nominal": "2027-01-15",
                          "date": "2027-01-15",
                          "reason": ""
                        },
                        {
                          "nominal": "2027-01-29",
                          "date": "2027-01-29",
                          "reason": ""
                        }
                      ]
                    }
                  ],
                  "company": {
                    "slug": "meta",
                    "name": "Meta",
                    "domain": "meta.com",
                    "frequency": "biweekly",
                    "weekday": "Friday",
                    "semimonthlyDays": null,
                    "examplePayday": "2024-01-19",
                    "sourceType": "employee-reported",
                    "confidence": "medium",
                    "sources": [
                      {
                        "url": "https://www.teamblind.com/post/did-meta-pay-today-qy40ggoh",
                        "note": "\"There is a wiki with all paydates. It's every two weeks... So on 01/19 you get paid for 1/1-1/14.\" (Blind, 2024-01-12)"
                      },
                      {
                        "url": "https://www.teamblind.com/post/meta-pay-schedule-and-procedure-hv4ftfzn",
                        "note": "\"Yes, 9/16 is the payout for 8/28-9/9.\" (Blind, 2022-08-31)"
                      }
                    ],
                    "notes": "Several employee reports agree: every other Friday. Two dated paydays (Sep 16, 2022 and Jan 19, 2024) and the 27th paycheck in 2026 all p...",
                    "checkedAt": "2026-09-24"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/companies": {
      "get": {
        "operationId": "list_companies",
        "summary": "Every tracked employer with its schedule and next payday",
        "description": "Every tracked employer with its schedule and next payday. Returns companies with rule, week known or not, source tier and the next payday (both possible dates when the week is unknown).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Items to skip, for the next page",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "companies with rule, week known or not, source tier and the next payday (both possible dates when the week is unknown)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "items": [
                    {
                      "slug": "amd",
                      "name": "AMD",
                      "domain": "amd.com",
                      "url": "https://paydays.fru.dev/companies/amd",
                      "schedule": {
                        "frequency": "biweekly",
                        "rule": "Every other Thursday",
                        "weekday": "Thursday",
                        "days": null,
                        "weekKnown": false,
                        "anchor": null,
                        "tier": "official",
                        "assumed": [
                          "week"
                        ],
                        "basis": "Official: every other Thursday, from 3 sources, including the company's own. Which Thursday is not stated, so both are shown."
                      },
                      "sources": [
                        {
                          "url": "https://ir.amd.com/financial-information/sec-filings/content/0000002488-24-000123/exh10_1guidoxofferxlettera.htm",
                          "note": "\"AMD pays on a bi-weekly basis on Thursday, with the exception of the first paycheck for exempt employees who begin work in a pay week, w..."
                        },
                        {
                          "url": "https://ir.amd.com/financial-information/sec-filings/content/0000002488-23-000003/exh10_1jhuofferletter.htm",
                          "note": "\"AMD pays on a bi-weekly basis on Thursday, with the exception of the first paycheck for exempt employees who begin work in a pay week, w..."
                        }
                      ],
                      "checkedAt": "2026-09-23",
                      "nextPaydays": [
                        "2026-09-24",
                        "2026-10-01"
                      ]
                    },
                    {
                      "slug": "accenture",
                      "name": "Accenture",
                      "domain": "accenture.com",
                      "url": "https://paydays.fru.dev/companies/accenture",
                      "schedule": {
                        "frequency": "biweekly",
                        "rule": "Every other Friday",
                        "weekday": "Friday",
                        "days": null,
                        "weekKnown": false,
                        "anchor": null,
                        "tier": "no-evidence",
                        "assumed": [
                          "frequency",
                          "weekday"
                        ],
                        "basis": "No published schedule or employee report yet. Shown as every other Friday, the usual schedule at large US tech employers; which Friday is..."
                      },
                      "sources": [],
                      "checkedAt": "2026-09-23",
                      "nextPaydays": [
                        "2026-09-25",
                        "2026-10-02"
                      ]
                    }
                  ],
                  "total": 50,
                  "limit": 3,
                  "offset": 0,
                  "next": "/api/companies?limit=3&offset=3",
                  "asOf": "2026-09-24"
                }
              }
            }
          }
        }
      }
    },
    "/api/schedules/{id}": {
      "get": {
        "operationId": "schedule_paydays",
        "summary": "Every payday of a standard schedule in a year, with the ones moved off weekends and bank holidays",
        "description": "Every payday of a standard schedule in a year, with the ones moved off weekends and bank holidays. Returns the schedule rule and its paydays (date, nominal date, reason moved).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Schedule id",
            "schema": {
              "type": "string",
              "enum": [
                "biweekly-a",
                "biweekly-b",
                "weekly",
                "semimonthly",
                "semimonthly-1-15",
                "monthly",
                "monthly-first",
                "military",
                "military-retiree",
                "federal-annuity",
                "ssi",
                "ssa-2nd-wednesday",
                "ssa-3rd-wednesday",
                "ssa-4th-wednesday",
                "ssa-3rd"
              ]
            },
            "example": "biweekly-a"
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Year, 2026 to 2028 (default 2027)",
            "schema": {
              "type": "integer",
              "minimum": 2026,
              "maximum": 2028
            },
            "example": 2027
          }
        ],
        "responses": {
          "200": {
            "description": "the schedule rule and its paydays (date, nominal date, reason moved)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "biweekly-a",
                  "name": "Biweekly, cycle A",
                  "rule": "Every other Friday, starting Friday, January 2, 2026",
                  "year": 2027,
                  "shift": "before",
                  "paydays": [
                    {
                      "nominal": "2027-01-15",
                      "date": "2027-01-15",
                      "reason": ""
                    },
                    {
                      "nominal": "2027-01-29",
                      "date": "2027-01-29",
                      "reason": ""
                    }
                  ],
                  "url": "https://paydays.fru.dev"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/payday-laws": {
      "get": {
        "operationId": "payday_laws",
        "summary": "How often each state requires wages to be paid, per the U.S. Department of Labor table",
        "description": "How often each state requires wages to be paid, per the U.S. Department of Labor table. Returns states with the pay frequencies marked, the note and the source.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Items to skip, for the next page",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "states with the pay frequencies marked, the note and the source",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "items": [
                    {
                      "slug": "alabama",
                      "state": "Alabama",
                      "abbr": "AL",
                      "dolText": "No frequency marked in DOL table; state name carries footnote 1",
                      "frequencies": [],
                      "notes": "No payday frequency requirement listed by DOL. Alabama and Florida. No regulations or not specified.",
                      "statute": "",
                      "sourceUrl": "https://www.dol.gov/agencies/whd/state/payday",
                      "stateSourceUrl": "",
                      "stateSourceSummary": "",
                      "checkedAt": "2026-09-22",
                      "url": "https://paydays.fru.dev/payday-laws/alabama"
                    },
                    {
                      "slug": "alaska",
                      "state": "Alaska",
                      "abbr": "AK",
                      "dolText": "Semi-monthly, Monthly",
                      "frequencies": [
                        "semimonthly",
                        "monthly"
                      ],
                      "notes": "",
                      "statute": "",
                      "sourceUrl": "https://www.dol.gov/agencies/whd/state/payday",
                      "stateSourceUrl": "",
                      "stateSourceSummary": "",
                      "checkedAt": "2026-09-22",
                      "url": "https://paydays.fru.dev/payday-laws/alaska"
                    }
                  ],
                  "total": 51,
                  "limit": 3,
                  "offset": 0,
                  "next": "/api/payday-laws?limit=3&offset=3",
                  "dolRevised": "2023-01-01"
                }
              }
            }
          }
        }
      }
    },
    "/api/published": {
      "get": {
        "operationId": "published_calendars",
        "summary": "Pay calendars published by SSA, DFAS, NFC and GSA, as stored with their sources",
        "description": "Pay calendars published by SSA, DFAS, NFC and GSA, as stored with their sources. Returns calendars with organisation, year, dates and source URL.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "calendars with organisation, year, dates and source URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "published": [
                    {
                      "id": "dfas-military-2026",
                      "org": "DFAS",
                      "name": "Active duty paydays 2026",
                      "kind": "military",
                      "year": 2026,
                      "dates": [
                        "2026-01-15",
                        "2026-01-30"
                      ],
                      "sourceUrl": "https://www.dfas.mil/MilitaryMembers/payentitlements/2026ACPayDay/",
                      "notes": "The end-of-month pay is paid on the 1st of the next month. DFAS has not published 2027 yet.",
                      "origin": "seed",
                      "status": "published",
                      "reviewed": true,
                      "matches": null
                    },
                    {
                      "id": "dfas-military-annuitant-2026",
                      "org": "DFAS",
                      "name": "Military annuitant pay dates 2026 (from October 2026 entitlement)",
                      "kind": "military-annuitant",
                      "year": 2026,
                      "dates": [
                        "2026-11-02",
                        "2026-12-01"
                      ],
                      "sourceUrl": "https://www.dfas.mil/RetiredMilitary/manage/payschedule/",
                      "notes": "DFAS publishes a rolling schedule; this covers entitlement months October 2026 to December 2027.",
                      "origin": "seed",
                      "status": "published",
                      "reviewed": true,
                      "matches": null
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "search",
        "summary": "Search companies, schedules and state law pages",
        "description": "Search companies, schedules and state law pages. Returns up to 20 ranked results with title, link and one line.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Company, schedule or state",
            "schema": {
              "type": "string"
            },
            "example": "biweekly"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results, 1 to 20",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "up to 20 ranked results with title, link and one line",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "q": "meta",
                  "results": [
                    {
                      "id": "co:meta",
                      "group": "companies",
                      "title": "Meta",
                      "subtitle": "Employee-reported · Every other Friday",
                      "href": "/companies/meta",
                      "keywords": [
                        "meta.com",
                        "meta"
                      ],
                      "logo": "https://img.logo.dev/meta.com?token=...&format=png&theme=light&size=64&retina=true&fallback=404",
                      "score": 1050
                    },
                    {
                      "id": "page:/method",
                      "group": "pages",
                      "title": "Method",
                      "subtitle": "How company paydays are sourced",
                      "href": "/method",
                      "icon": "info",
                      "score": 150
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}