{"openapi":"3.1.0","info":{"title":"shaharpolak.com public data","version":"1.0.0","summary":"Read-only JSON views of the hiring directory and the lecture catalog.","description":"Two GET endpoints, no authentication, no rate limit. Responses are CDN-cached for an hour and carry `Access-Control-Allow-Origin: *`, so they are usable from a browser.\n\nVersioning policy: every response carries an `X-API-Version` header, currently `1`. Additive changes (new fields, new enum values) happen within a version; a breaking change to a response shape ships as a new header value and is announced in the changelog section of /api/llms.txt before the old shape is removed.\n\nAuthentication: none, see /auth.md. Errors are always JSON, including 404 for unknown /api/ paths.\n\nFree to use with attribution to https://www.shaharpolak.com.","license":{"name":"Free to use with attribution","url":"https://www.shaharpolak.com/who-is-hiring"},"contact":{"name":"Shahar Polak","url":"https://www.shaharpolak.com/contact"}},"servers":[{"url":"https://www.shaharpolak.com"}],"externalDocs":{"description":"Agent-oriented usage guide","url":"https://www.shaharpolak.com/api/llms.txt"},"security":[],"paths":{"/api/hiring.json":{"get":{"operationId":"getHiringDirectory","summary":"Companies hiring in Israel, with per-role-family counts","description":"The dataset behind the /who-is-hiring page. Without filters it returns every company. Filters use the same matching as the page itself, so a filtered response and a filtered page agree. Parameter names are matched case-insensitively, which HTTP does not require - `?Region=` and `?REGION=` both work, and a value repeated across two casings is still rejected. Every filter takes a single value, trimmed of surrounding whitespace; an empty value means no filter. An unknown parameter name, a repeated parameter, or an unknown region or role returns 400 with the valid options rather than silently ignoring or truncating the filter.","externalDocs":{"description":"Human view","url":"https://www.shaharpolak.com/who-is-hiring"},"parameters":[{"name":"locations","in":"query","required":false,"description":"Case-insensitive substring of a company's raw location string, e.g. `Haifa`. Narrower than `region`: the field is source copy, and some companies publish no location at all. Prefer `region` for geography.","schema":{"type":"string"},"example":"Haifa"},{"name":"region","in":"query","required":false,"description":"Editorial geographic group. Accepts the Hebrew taxonomy value or its English label. Inclusive by design: companies listed as all-of-Israel or with no stated location match every region, so a region result is wider than a `locations` result.","schema":{"type":"string","enum":["תל אביב והמרכז","השרון","ירושלים","חיפה והצפון","דרום","Tel Aviv & Center","Sharon","Jerusalem","Haifa & North","South"]},"example":"Haifa & North"},{"name":"role","in":"query","required":false,"description":"Role-family slug, case-insensitive. Returns companies with at least one open role in that family. Slugs map to families as follows: `eng` = Engineering / Software, `data` = Data / ML / AI, `product` = Product / Design, `hw` = Hardware / Semiconductors / Manufacturing, `security` = Security / IT / Support, `sales` = Sales / BizDev / Customer, `marketing` = Marketing / Content, `ops` = Operations / Finance / HR / Legal, `other` = Other / Unclassified.","schema":{"type":"string","enum":["eng","data","product","hw","security","sales","marketing","ops","other"]},"example":"eng"},{"name":"q","in":"query","required":false,"description":"Free-text search across company name, sector, example role titles, locations and role families. Every term must match. A small alias list widens common role words (backend, devops, frontend, data, cyber).","schema":{"type":"string"},"example":"cyber"},{"name":"X-API-Version","in":"header","required":false,"description":"Advisory: the contract major version the client expects. `1` is the only version that exists; the response always names the served version in its own `X-API-Version` header.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"The matching companies.","headers":{"X-API-Version":{"description":"Contract major version of the response shape. Currently always `1`.","schema":{"type":"string","enum":["1"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HiringResponse"}}}},"400":{"description":"Unknown or repeated query parameter, or unknown region or role.","headers":{"X-API-Version":{"description":"Contract major version of the response shape. Currently always `1`.","schema":{"type":"string","enum":["1"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterError"}}}}}}},"/api/lectures.json":{"get":{"operationId":"getLectureCatalog","summary":"Talk catalog in Hebrew and English","description":"Every talk in both site languages, with takeaways and audience fit. Takes no query parameters. Price and booking specs are deliberately absent.","externalDocs":{"description":"Human view","url":"https://www.shaharpolak.com/lectures"},"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Advisory: the contract major version the client expects. `1` is the only version that exists; the response always names the served version in its own `X-API-Version` header.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"The full catalog.","headers":{"X-API-Version":{"description":"Contract major version of the response shape. Currently always `1`.","schema":{"type":"string","enum":["1"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LecturesResponse"}}}}}}}},"components":{"schemas":{"HiringResponse":{"type":"object","required":["updatedAt","companyCount","totalOpenPositions","companies"],"properties":{"updatedAt":{"type":"string","format":"date","description":"ISO date the counts were collected."},"source":{"type":"string","description":"How the counts were gathered."},"documentation":{"type":"string","format":"uri"},"license":{"type":"string"},"scope":{"type":"string"},"filters":{"type":"object","description":"The filters actually applied, echoed back so a caller can tell a filtered response from a full one. `region` is echoed as the canonical Hebrew value even when requested by English label.","properties":{"locations":{"type":["string","null"],"description":"The `locations` filter, or null."},"region":{"type":["string","null"],"description":"Canonical Hebrew region value, or null."},"role":{"type":["string","null"],"description":"The `role` slug, or null."},"q":{"type":["string","null"],"description":"The search text, or null."}}},"companyCount":{"type":"integer","description":"Companies in this response, after filtering."},"totalOpenPositions":{"type":"integer","description":"Open roles summed across the returned companies that have a publishable count. Companies with `verified: false` contribute nothing."},"roleFamilies":{"type":"array","description":"The full role taxonomy: the key for every `roleBreakdown[].name`, its Hebrew label, and the slug accepted by `?role=`.","items":{"$ref":"#/components/schemas/RoleFamily"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}}},"RoleFamily":{"type":"object","required":["name","label","slug"],"properties":{"name":{"type":"string","description":"Exact `roleBreakdown[].name` key."},"label":{"type":"string","description":"Short Hebrew label."},"slug":{"type":"string","description":"Value accepted by `?role=`."}}},"RoleBreakdown":{"type":"object","required":["name","count"],"properties":{"name":{"type":"string","description":"Role family; matches a `roleFamilies[].name`."},"count":{"type":"integer","description":"Open roles counted in that family."}}},"Company":{"type":"object","required":["name","category","careersUrl","verified","roleBreakdown"],"properties":{"name":{"type":"string"},"category":{"type":"string","description":"Sector, e.g. `Automotive / AI`."},"careersUrl":{"type":"string","format":"uri","description":"Tracked redirect - the outbound link the site itself uses. Prefer it when linking a visitor onward."},"sourceUrl":{"type":["string","null"],"description":"Direct board URL, so a count can be re-verified at the source."},"openPositions":{"type":["integer","null"],"description":"Open roles in Israel, or null when unknown. Read together with `verified`."},"verified":{"type":"boolean","description":"Whether `openPositions` is trustworthy enough to publish as a number. Editorial, not derived: a scraped count of 1 at medium confidence is likelier a parsing artifact than a real vacancy."},"confidence":{"type":["string","null"],"description":"Confidence in the count."},"countStatus":{"type":["string","null"],"description":"How the count should be read."},"roleBreakdown":{"type":"array","description":"Full per-family breakdown from the source.","items":{"$ref":"#/components/schemas/RoleBreakdown"}},"exampleRoles":{"type":"array","items":{"type":"string"},"description":"Hand-checked sample role titles."},"locations":{"type":"array","items":{"type":"string"},"description":"Raw locations from the postings, normalized for display. May be empty."},"region":{"type":"array","items":{"type":"string"},"description":"Editorial geographic groups, Hebrew. `כל הארץ` means the source only said Israel; `לא צוין` means it gave no usable location."},"notes":{"type":["string","null"],"description":"Editorial note."},"checkedAt":{"type":["string","null"],"format":"date","description":"ISO date this record was last checked. Null means the dataset-wide `updatedAt` applies."}}},"LecturesResponse":{"type":"object","required":["speaker","lectures"],"properties":{"speaker":{"type":"string"},"documentation":{"type":"string","format":"uri"},"bookingUrl":{"type":"string","format":"uri","description":"Where to send a speaking enquiry."},"languages":{"type":"array","items":{"type":"string"},"description":"Language keys present in `lectures`."},"lectures":{"type":"object","description":"The catalog, keyed by language.","properties":{"he":{"type":"array","items":{"$ref":"#/components/schemas/Lecture"}},"en":{"type":"array","items":{"$ref":"#/components/schemas/Lecture"}}}}}},"Lecture":{"type":"object","required":["slug","title","description","url"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"shortTitle":{"type":"string"},"subtitle":{"type":["string","null"],"description":"Hero subtitle, or null."},"category":{"type":"string"},"description":{"type":"string"},"takeaways":{"type":"array","items":{"type":"string"},"description":"What the audience leaves with."},"idealFor":{"type":"array","items":{"type":"string"},"description":"Audiences the talk fits."},"mostRequested":{"type":"boolean"},"url":{"type":"string","format":"uri","description":"Page for this talk."}}},"FilterError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What was wrong with the request."},"supported":{"type":"array","items":{"type":"string"},"description":"Accepted parameter names, when one was unknown."},"regions":{"type":"array","description":"Valid regions, when the region was unknown.","items":{"type":"object","properties":{"value":{"type":"string","description":"Hebrew taxonomy value."},"label":{"type":"string","description":"English label."}}}},"roles":{"type":"array","items":{"type":"string"},"description":"Valid role slugs, when the role was unknown."}}}}}}