{
  "openapi": "3.1.0",
  "info": {
    "title": "PayCrunch Salary API",
    "version": "1.0.0",
    "summary": "Annual pay for 1,008 US occupations - entry, median, top of range, and wages by state. Free, no key.",
    "description": "Free, public, read-only wage data for 1,008 occupations in the United States.\n\nNo account, no key, no rate limit and no quota: every endpoint is a static JSON file on a CDN, so a request costs nothing to serve and nothing to make.\n\n**What the figures are.** Entry is the 10th-percentile annual wage, median the 50th, and the top of the range is the highest state-level 90th percentile among areas employing at least 500 people in the occupation. That floor exists because unfiltered state figures produce artefacts - BLS publishes $113,810 for door-to-door newspaper sales in Missouri - and an artefact that looks like a salary is worse than no salary.\n\n**Two kinds of record, always distinguishable.** Records with `tier: \"A\"` and `estimated: false` carry Bureau of Labor Statistics figures under a named SOC code. Records with `tier: \"B\"` and `estimated: true` cover job titles the Bureau does not track separately; those figures are PayCrunch estimates and must not be presented as BLS data. Every record says which it is, in a field, not in prose.\n\n**Attribution.** CC BY 4.0. Cite the page or endpoint you used and the BLS release date.\n\nWage source: U.S. Bureau of Labor Statistics, Occupational Employment and Wage Statistics.\n",
    "termsOfService": "https://paycrunch.co/terms.html",
    "contact": {
      "name": "PayCrunch",
      "url": "https://paycrunch.co/contact.html"
    },
    "license": {
      "name": "Creative Commons Attribution 4.0 International",
      "identifier": "CC-BY-4.0"
    }
  },
  "externalDocs": {
    "description": "API documentation",
    "url": "https://paycrunch.co/api.html"
  },
  "servers": [
    {
      "url": "https://paycrunch.co/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "What the API contains."
    },
    {
      "name": "Occupations",
      "description": "Pay by job and by SOC code."
    },
    {
      "name": "Geography",
      "description": "Pay by state."
    }
  ],
  "paths": {
    "/index.json": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getIndex",
        "summary": "What this API contains",
        "description": "Endpoint list, record counts, licence, attribution text and the exact citation string to use.",
        "responses": {
          "200": {
            "description": "API description",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/jobs.json": {
      "get": {
        "tags": [
          "Occupations"
        ],
        "operationId": "listJobs",
        "summary": "Every occupation in one file",
        "description": "All 1,008 records, one row each. Use this to build a local index instead of fetching a thousand files.",
        "responses": {
          "200": {
            "description": "All occupations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "name",
                          "tier",
                          "estimated",
                          "wage",
                          "ceiling"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string",
                            "examples": [
                              "welder-salary"
                            ]
                          },
                          "name": {
                            "type": "string",
                            "examples": [
                              "Welder"
                            ]
                          },
                          "tier": {
                            "type": "string",
                            "enum": [
                              "A",
                              "B"
                            ],
                            "description": "A: BLS publishes wages under a named SOC code. B: a PayCrunch estimate."
                          },
                          "estimated": {
                            "type": "boolean"
                          },
                          "tier_note": {
                            "type": "string"
                          },
                          "soc": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "examples": [
                              "51-4121"
                            ]
                          },
                          "bls_title": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "job_zone": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "O*NET Job Zone, 1 to 5: how much preparation the occupation needs."
                          },
                          "source": {
                            "type": "string"
                          },
                          "source_release": {
                            "type": "string"
                          },
                          "last_updated": {
                            "type": "string",
                            "format": "date"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "wage": {
                            "type": "object",
                            "description": "Annual wage percentiles for the occupation, nationally.",
                            "properties": {
                              "currency": {
                                "type": "string",
                                "const": "USD"
                              },
                              "period": {
                                "type": "string",
                                "const": "year"
                              },
                              "p10": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "10th percentile. What the bottom of the field earns.",
                                "examples": [
                                  53750
                                ]
                              },
                              "p25": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "25th percentile.",
                                "examples": [
                                  53750
                                ]
                              },
                              "median": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "50th percentile.",
                                "examples": [
                                  53750
                                ]
                              },
                              "p75": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "75th percentile.",
                                "examples": [
                                  53750
                                ]
                              },
                              "p90": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "90th percentile, nationally.",
                                "examples": [
                                  53750
                                ]
                              },
                              "source_release": {
                                "type": "string",
                                "description": "'BLS OEWS May 2025' or 'PayCrunch estimate'."
                              }
                            }
                          },
                          "ceiling": {
                            "type": "object",
                            "description": "The top of the published range: the highest state-level 90th-percentile wage among areas employing at least 500 people in the occupation, falling back to the national figure when no area qualifies.",
                            "properties": {
                              "amount": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "The top-of-range annual wage.",
                                "examples": [
                                  53750
                                ]
                              },
                              "state": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "state",
                                  "national"
                                ]
                              },
                              "estimated": {
                                "type": "boolean",
                                "description": "true means this is a PayCrunch estimate and must not be cited as a BLS figure."
                              },
                              "basis": {
                                "type": "string"
                              },
                              "state_median": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "Median wage in that state.",
                                "examples": [
                                  53750
                                ]
                              },
                              "state_employment": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            }
                          },
                          "core_tasks": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "O*NET task statements for the occupation."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{slug}.json": {
      "get": {
        "tags": [
          "Occupations"
        ],
        "operationId": "getJob",
        "summary": "One occupation in full",
        "description": "Wages, the top of the range and where it is, the occupation people most often move up into, and the O*NET task statements. The slug is the one in the page URL: /jobs/welder-salary.html is welder-salary.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Occupation slug, e.g. welder-salary.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            },
            "example": "welder-salary"
          }
        ],
        "responses": {
          "200": {
            "description": "The occupation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "name",
                    "tier",
                    "estimated",
                    "wage",
                    "ceiling"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string",
                      "examples": [
                        "welder-salary"
                      ]
                    },
                    "name": {
                      "type": "string",
                      "examples": [
                        "Welder"
                      ]
                    },
                    "tier": {
                      "type": "string",
                      "enum": [
                        "A",
                        "B"
                      ],
                      "description": "A: BLS publishes wages under a named SOC code. B: a PayCrunch estimate."
                    },
                    "estimated": {
                      "type": "boolean"
                    },
                    "tier_note": {
                      "type": "string"
                    },
                    "soc": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "examples": [
                        "51-4121"
                      ]
                    },
                    "bls_title": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "job_zone": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "O*NET Job Zone, 1 to 5: how much preparation the occupation needs."
                    },
                    "source": {
                      "type": "string"
                    },
                    "source_release": {
                      "type": "string"
                    },
                    "last_updated": {
                      "type": "string",
                      "format": "date"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "wage": {
                      "type": "object",
                      "description": "Annual wage percentiles for the occupation, nationally.",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "const": "USD"
                        },
                        "period": {
                          "type": "string",
                          "const": "year"
                        },
                        "p10": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "10th percentile. What the bottom of the field earns.",
                          "examples": [
                            53750
                          ]
                        },
                        "p25": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "25th percentile.",
                          "examples": [
                            53750
                          ]
                        },
                        "median": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "50th percentile.",
                          "examples": [
                            53750
                          ]
                        },
                        "p75": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "75th percentile.",
                          "examples": [
                            53750
                          ]
                        },
                        "p90": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "90th percentile, nationally.",
                          "examples": [
                            53750
                          ]
                        },
                        "source_release": {
                          "type": "string",
                          "description": "'BLS OEWS May 2025' or 'PayCrunch estimate'."
                        }
                      }
                    },
                    "ceiling": {
                      "type": "object",
                      "description": "The top of the published range: the highest state-level 90th-percentile wage among areas employing at least 500 people in the occupation, falling back to the national figure when no area qualifies.",
                      "properties": {
                        "amount": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "The top-of-range annual wage.",
                          "examples": [
                            53750
                          ]
                        },
                        "state": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scope": {
                          "type": "string",
                          "enum": [
                            "state",
                            "national"
                          ]
                        },
                        "estimated": {
                          "type": "boolean",
                          "description": "true means this is a PayCrunch estimate and must not be cited as a BLS figure."
                        },
                        "basis": {
                          "type": "string"
                        },
                        "state_median": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Median wage in that state.",
                          "examples": [
                            53750
                          ]
                        },
                        "state_employment": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    },
                    "core_tasks": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "O*NET task statements for the occupation."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No occupation with that slug."
          }
        }
      }
    },
    "/soc/{code}.json": {
      "get": {
        "tags": [
          "Occupations"
        ],
        "operationId": "getSoc",
        "summary": "One SOC code, with its state wage table",
        "description": "Everything under a Standard Occupational Classification code: the national wages, the best-paying state, the full state table where BLS reports one, and every PayCrunch page mapped to that code.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "SOC code with the hyphen, e.g. 51-4121.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{2}-[0-9]{4}$"
            },
            "example": "51-4121"
          }
        ],
        "responses": {
          "200": {
            "description": "The occupation code",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "soc": {
                      "type": "string"
                    },
                    "bls_title": {
                      "type": "string"
                    },
                    "wage": {
                      "type": "object",
                      "description": "Annual wage percentiles for the occupation, nationally.",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "const": "USD"
                        },
                        "period": {
                          "type": "string",
                          "const": "year"
                        },
                        "p10": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "10th percentile. What the bottom of the field earns.",
                          "examples": [
                            53750
                          ]
                        },
                        "p25": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "25th percentile.",
                          "examples": [
                            53750
                          ]
                        },
                        "median": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "50th percentile.",
                          "examples": [
                            53750
                          ]
                        },
                        "p75": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "75th percentile.",
                          "examples": [
                            53750
                          ]
                        },
                        "p90": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "90th percentile, nationally.",
                          "examples": [
                            53750
                          ]
                        },
                        "source_release": {
                          "type": "string",
                          "description": "'BLS OEWS May 2025' or 'PayCrunch estimate'."
                        }
                      }
                    },
                    "ceiling": {
                      "type": "object",
                      "description": "The top of the published range: the highest state-level 90th-percentile wage among areas employing at least 500 people in the occupation, falling back to the national figure when no area qualifies.",
                      "properties": {
                        "amount": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "The top-of-range annual wage.",
                          "examples": [
                            53750
                          ]
                        },
                        "state": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scope": {
                          "type": "string",
                          "enum": [
                            "state",
                            "national"
                          ]
                        },
                        "estimated": {
                          "type": "boolean",
                          "description": "true means this is a PayCrunch estimate and must not be cited as a BLS figure."
                        },
                        "basis": {
                          "type": "string"
                        },
                        "state_median": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Median wage in that state.",
                          "examples": [
                            53750
                          ]
                        },
                        "state_employment": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    },
                    "state_wages": {
                      "type": "object",
                      "properties": {
                        "employment_floor": {
                          "type": "integer"
                        },
                        "areas": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "area": {
                                "type": "string",
                                "description": "State, the District of Columbia, or a US territory."
                              },
                              "median": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "Annual median wage in that area.",
                                "examples": [
                                  53750
                                ]
                              },
                              "p90": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "Annual 90th-percentile wage in that area.",
                                "examples": [
                                  53750
                                ]
                              },
                              "employment": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "People employed in the occupation there. Always at least 500; areas below the floor are omitted."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such SOC code in this dataset."
          }
        }
      }
    },
    "/state-wages.json": {
      "get": {
        "tags": [
          "Geography"
        ],
        "operationId": "getStateWages",
        "summary": "Wages by state for every occupation",
        "description": "352 occupations across 11,548 area rows. BLS ships this as a spreadsheet; this is the same thing as JSON, filtered to areas employing at least 500 people in the occupation.",
        "responses": {
          "200": {
            "description": "State wage tables",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "area_rows": {
                      "type": "integer"
                    },
                    "employment_floor": {
                      "type": "integer"
                    },
                    "occupations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "soc": {
                            "type": "string"
                          },
                          "bls_title": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "areas": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "area": {
                                  "type": "string",
                                  "description": "State, the District of Columbia, or a US territory."
                                },
                                "median": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "description": "Annual median wage in that area.",
                                  "examples": [
                                    53750
                                  ]
                                },
                                "p90": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "description": "Annual 90th-percentile wage in that area.",
                                  "examples": [
                                    53750
                                  ]
                                },
                                "employment": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "description": "People employed in the occupation there. Always at least 500; areas below the floor are omitted."
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/states.json": {
      "get": {
        "tags": [
          "Geography"
        ],
        "operationId": "getBestPayingStates",
        "summary": "The best-paying state for each occupation",
        "description": "One row per occupation naming the state that pays it most, with the unfiltered answer beside it so you can see what the employment floor changed.",
        "responses": {
          "200": {
            "description": "Best-paying states",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}