{"openapi":"3.1.0","info":{"title":"Proletaria API","description":"Read-only market data for proletaria.io: job postings, company and skill\naggregates, and the editorial overview. Every route here is `GET`, unauthenticated,\nand documented in full (response shapes, caching/ETag semantics, error shapes) in\n[`docs/api-contract.md`](https://github.com/bennysc/proletaria-backend/blob/main/docs/api-contract.md),\nwhich is the binding contract — this page is a generated view of the same routes.\n\n## Canonical URLs\n\n`GET /openapi.json`, `GET /docs` (Swagger UI), and `GET /redoc` (ReDoc) are the\ncanonical, production-safe documentation surface. `/api/openapi.json`,\n`/api/docs`, and `/api/redoc` remain as thin, non-documented compatibility\naliases — same content, never the linked/citable address — and, like the\ncanonical URLs, never enumerate `/api/admin/*` (the control plane) in any\nenvironment. The schema is built from an explicit public route allowlist, not\nby generating the whole application's schema and filtering admin paths back\nout afterward.\n\n## Versioning\n\nThis document's `info.version` and every response's\n`X-Proletaria-Contract-Version` header are the same semver string (currently\n`1.9.0`) — the `docs/api-contract.md` revision this deployment serves. It\nonly changes with a deliberate, documented response-shape change. Contract\n**major version 1** (any `X-Proletaria-Contract-Version` starting `1.`) is\nwhat this document and `docs/api-contract.md` call **\"v1\"** throughout — the\npublic route surface, response shapes, and error envelope are stable at that\nmajor version; the trailing minor/patch numbers track additive,\nbackward-compatible changes only.\n\n## Data-use terms\n\n- **Attribution required.** If you publish or redistribute anything derived from\n  this API, credit \"proletaria.io\" with a link back to the site or the specific\n  page the data came from.\n- **No resale.** You may not resell, sublicense, or repackage this data (raw or\n  lightly transformed) as a competing dataset or API. Building an application,\n  analysis, or one-off report on top of it is fine.\n- **No fabrication downstream, either.** Fields that are `null` here (see\n  \"COLLECTING\" states in the contract) are `null` because we do not have enough\n  history to compute them honestly — do not backfill or estimate a value we\n  chose not to publish and attribute it to us.\n- Full terms: <https://github.com/bennysc/proletaria-backend/blob/main/docs/api-contract.md#openapi-interactive-docs--terms-of-use>\n  (canonical; the site's `/data` page will link here once it ships).\n\n## Rate expectations\n\nThere is no API key and no published numeric quota or availability SLA today.\nPlease cache responses client-side using the `Cache-Control`/`ETag` headers\ndocumented below rather than polling — most routes are safe to cache for at\nleast a minute, and the closer-published ones (`/api/overview`,\n`/api/market/locations`, the company/skill directories) change at most once a\nday. Traffic patterns that look abusive (no caching, high concurrency,\nignoring `429`/`503`/`Retry-After`) may be rate-limited or blocked at the edge\nwithout notice; honor any future `429`/`Retry-After` response.\n\n## Errors\n\nEvery public `4xx`/`503` — validation failures, unknown entities, exhausted\nrate limits, database timeouts, and unpublished-generation gaps — shares one\nenvelope: `{\"error\": \"<stable machine code>\", \"detail\": \"<human message>\"}`.\nSee `docs/api-contract.md`'s \"Error response shapes\" for the full list of\ncodes and which ones are safe to retry.\n","version":"1.9.0"},"paths":{"/healthz":{"get":{"tags":["Health"],"summary":"Liveness/startup check","description":"Dependency-free liveness/startup probe: always `200 {\"status\":\"ok\"}`, never touches PostgreSQL. This is what Kubernetes' readiness/startup probes point at; `GET /health` below is the DB-coupled check. Never cached (`Cache-Control: no-store`) and not represented as a published dataset.","operationId":"get_healthz","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Database health check","description":"`{\"status\":\"ok\",\"db\":\"ok\"}`, or `503 {\"status\":\"error\",\"db\":\"unreachable\",\"error\":\"service_unavailable\",\"detail\":\"...\"}` if PostgreSQL is unreachable — the pre-existing `status`/`db` keys are preserved additively alongside the shared `error`/`detail` envelope (see `docs/api-contract.md`'s \"Error response shapes\"). A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data. Never cached (`Cache-Control: no-store`); an operational probe, not a published dataset.","operationId":"get_health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/meta":{"get":{"tags":["Platform"],"summary":"Site metadata","description":"Drives COLLECTING states, range-button enablement, and the freshness stamp — the closer-published `site_meta` representation. **Cache class: fast-changing.** `Cache-Control: public, max-age=30, s-maxage=300, stale-while-revalidate=600`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. A `503 publication_unavailable` is returned with `Retry-After: 60` if the schema exists but no closer run has published yet. A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data.","operationId":"get_meta","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Meta"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/ticker":{"get":{"tags":["Platform"],"summary":"Market ticker tape","description":"Market segments (ACTIVE, NEW 24H, MED PAY, REMOTE) plus companies that posted new roles on the latest closed day. Optional `discipline`/`industry` scope the company items only; an unrecognised value is a `422 validation_error` — see docs/api-contract.md. Unscoped: **Cache class: fast-changing.** `Cache-Control: public, max-age=30, s-maxage=300, stale-while-revalidate=600`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. A scoped request is always `no-store`.","operationId":"get_ticker","parameters":[{"name":"discipline","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discipline"}},{"name":"industry","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticker"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/blog":{"get":{"tags":["Editorial"],"summary":"Weekly blog archive","description":"Paginated archive of published weekly editorial posts, with the available `week`/`discipline` facets. **Cache class: published.** `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`; a stable `ETag` is attached and a matching `If-None-Match` returns `304` with the same cache and `X-Proletaria-Contract-Version` headers. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. An unbounded query shape (a filter combination outside the documented matrix) is `no-store`. Unpublished schema: `503 publication_unavailable` with `Retry-After: 60`. A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data.","operationId":"get_blog_archive","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":12,"title":"Limit"}},{"name":"week","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Week"}},{"name":"discipline","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}],"title":"Discipline"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlogArchiveResponse"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/blog/{slug}":{"get":{"tags":["Editorial"],"summary":"Weekly blog post","description":"One published weekly editorial post, by slug. `404 not_found` if unknown or unpublished. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. Unpublished schema: `503 publication_unavailable` with `Retry-After: 60`. A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data.","operationId":"get_blog_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlogPost"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/overview":{"get":{"tags":["Market"],"summary":"Market overview","description":"One composite call: headline, KPIs, postings/posting-date series, movers, top employers, trending skills, pullbacks, metros, and editorial for a range. **Cache class: published.** `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`; a stable `ETag` is attached and a matching `If-None-Match` returns `304` with the same cache and `X-Proletaria-Contract-Version` headers. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. A retained `?as_of=` date: **Cache class: snapshot** (only for a retained `?as_of=` date strictly before today). `Cache-Control: public, max-age=31536000, immutable` — a closed generation nothing ever rewrites. The unscoped/live request, and `?as_of=<today>`, remain `no-store`. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. `discipline`/`industry`/`country=US` scoping and an unresolved `?as_of=` are always `no-store`. Unpublished schema: `503 publication_unavailable` with `Retry-After: 60`. A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data.","operationId":"get_overview","parameters":[{"name":"range","in":"query","required":false,"schema":{"enum":["7d","30d","1y","max"],"type":"string","default":"30d","title":"Range"}},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"const":"US","type":"string"},{"type":"null"}],"title":"Country"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}},{"name":"discipline","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discipline"}},{"name":"industry","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Return the payload as it was published on this date (BE-45: D13), not the current one. Resolved against retained snapshot generations only — never recomputed from live data — so a date outside the retention window is a 404, not an approximation. The response is then immutable and cacheable forever. Not combinable with discipline/industry/country scoping — every scoped panel (BE-40's top_employers, D11's US-scoped headline) is computed live and has no retained history of its own.","title":"As Of"},"description":"Return the payload as it was published on this date (BE-45: D13), not the current one. Resolved against retained snapshot generations only — never recomputed from live data — so a date outside the retention window is a 404, not an approximation. The response is then immutable and cacheable forever. Not combinable with discipline/industry/country scoping — every scoped panel (BE-40's top_employers, D11's US-scoped headline) is computed live and has no retained history of its own."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Overview"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/market/locations":{"get":{"tags":["Market"],"summary":"Postings by metro","description":"Market-wide active listings bucketed by metro, remote, or unmapped. **Cache class: published.** `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`; a stable `ETag` is attached and a matching `If-None-Match` returns `304` with the same cache and `X-Proletaria-Contract-Version` headers. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_market_locations","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketLocations"}}}}}}},"/api/editorial/latest":{"get":{"tags":["Editorial"],"summary":"Latest editorial","description":"The most recent editorial published within the last 7 days, or `404 not_found` if none qualifies. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_editorial_latest","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Editorial"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/listings/search":{"get":{"tags":["Listings"],"summary":"Search listings","description":"Faceted job-posting search: filters, facets, histogram, and an optional pay summary. An unrecognized enum/slug value (`experience`, `work_mode`, `employment_type`, `country_code`, `sort`, `include`, a skill/industry/discipline/company slug, `metro_id`(s)) is a `422 validation_error`; a malformed `q` is a `400 invalid_request`. **Cache class: query.** High-cardinality request shapes are always `Cache-Control: no-store` (never cached, no ETag negotiation), except for the one canonical default-filter shape documented in `docs/api-contract.md`, which is cached at `fast-changing` policy instead. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. The one canonical default-US-facets shape (`country_code=US`, `limit=0`, `include=facets,histogram`, no other filter) is instead cached at fast-changing policy — see docs/api-contract.md.","operationId":"search_listings","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"skills","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Skills"}},{"name":"experience","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Experience"}},{"name":"industries","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industries"}},{"name":"disciplines","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disciplines"}},{"name":"work_mode","in":"query","required":false,"schema":{"enum":["any","remote","hybrid","onsite"],"type":"string","default":"any","title":"Work Mode"}},{"name":"employment_type","in":"query","required":false,"schema":{"enum":["any","full_time","part_time","contract","intern"],"type":"string","default":"any","title":"Employment Type"}},{"name":"pay_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Pay Min"}},{"name":"pay_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Pay Max"}},{"name":"company","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company"}},{"name":"companies","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Companies"}},{"name":"metro_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Metro Id"}},{"name":"metro_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metro Ids"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"const":"US","type":"string"},{"type":"null"}],"title":"Country Code"}},{"name":"similar","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Similar"}},{"name":"check_uid","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Check Uid"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["newest","relevance","pay","similarity"],"type":"string","default":"newest","title":"Sort"}},{"name":"title_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Title Only"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":0,"default":50,"title":"Limit"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","default":"facets,histogram","title":"Include"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Public error envelope (invalid_request).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/listings/search.csv":{"get":{"tags":["Listings"],"summary":"Export listing search as CSV","description":"The same filters as `GET /api/listings/search`, streamed as `text/csv` (see `docs/api-contract.md`'s \"Downloads\" section for the column contract and truncation marker). Same `400`/`422` validation as JSON search. **Cache class: query.** High-cardinality request shapes are always `Cache-Control: no-store` (never cached, no ETag negotiation), except for the one canonical default-filter shape documented in `docs/api-contract.md`, which is cached at `fast-changing` policy instead. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"search_listings_csv","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"skills","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Skills"}},{"name":"experience","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Experience"}},{"name":"industries","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industries"}},{"name":"disciplines","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disciplines"}},{"name":"work_mode","in":"query","required":false,"schema":{"enum":["any","remote","hybrid","onsite"],"type":"string","default":"any","title":"Work Mode"}},{"name":"employment_type","in":"query","required":false,"schema":{"enum":["any","full_time","part_time","contract","intern"],"type":"string","default":"any","title":"Employment Type"}},{"name":"pay_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Pay Min"}},{"name":"pay_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Pay Max"}},{"name":"company","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company"}},{"name":"companies","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Companies"}},{"name":"metro_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Metro Id"}},{"name":"metro_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metro Ids"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"const":"US","type":"string"},{"type":"null"}],"title":"Country Code"}},{"name":"similar","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Similar"}}],"responses":{"200":{"description":"CSV export of matching listings.","content":{"application/json":{"schema":{}},"text/csv":{}}},"400":{"description":"Public error envelope (invalid_request).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/listings/{uid}":{"get":{"tags":["Listings"],"summary":"Listing detail","description":"A single job posting, addressed by its stable `posting_uid` (16-hex). A `404 not_found` if the uid is unknown. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_listing_detail","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string","title":"Uid"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingDetail"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/companies":{"get":{"tags":["Companies"],"summary":"Company directory","description":"Every tracked company, with open-role counts and disclosure stats. **Cache class: published.** `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`; a stable `ETag` is attached and a matching `If-None-Match` returns `304` with the same cache and `X-Proletaria-Contract-Version` headers. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. A retained `?as_of=` date: **Cache class: snapshot** (only for a retained `?as_of=` date strictly before today). `Cache-Control: public, max-age=31536000, immutable` — a closed generation nothing ever rewrites. The unscoped/live request, and `?as_of=<today>`, remain `no-store`. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"list_companies","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Return the directory as it was published on this date (BE-45: D13), resolved against retained snapshot generations only. A date outside the retention window is a 404, never an approximation from the current directory.","title":"As Of"},"description":"Return the directory as it was published on this date (BE-45: D13), resolved against retained snapshot generations only. A date outside the retention window is a 404, never an approximation from the current directory."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyList"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/companies/{slug}":{"get":{"tags":["Companies"],"summary":"Company detail","description":"One company's profile, open roles, pay/time-to-fill KPIs, and trend series. `404 not_found` if unknown (a merged slug resolves through `serve.company_redirects` first). Computed live, not closer-published — `?as_of=` is always `404 snapshot_not_retained` here (no dated generation exists yet). **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_company_detail","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"BE-45 (D13): reserved for a future generation. Per-company detail pages are computed live, not closer-published, so no dated generation is retained yet — any value here is an honest 404 rather than a recomputation from current state.","title":"As Of"},"description":"BE-45 (D13): reserved for a future generation. Per-company detail pages are computed live, not closer-published, so no dated generation is retained yet — any value here is an honest 404 rather than a recomputation from current state."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDetail"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/companies/{company_id}/timeseries":{"get":{"tags":["Companies"],"summary":"Company active-listing timeseries","description":"Daily active-listing counts by function for one company over a `days` window (exactly `7`/`30`/`90`/`180`/`365`; any other value is `422 validation_error`). `404 not_found` if the company is unknown. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_company_timeseries","parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"days","in":"query","required":false,"schema":{"type":"string","default":"90","title":"Days"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyTimeseries"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/companies/{company_id}/locations":{"get":{"tags":["Companies"],"summary":"Company office/remote location breakdown","description":"One company's active listings bucketed by metro, remote, or unmapped, mirroring `GET /api/market/locations`'s classification. `404 not_found` if the company is unknown. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_company_locations","parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyLocations"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/companies/{company_id}/pay-timeseries":{"get":{"tags":["Companies"],"summary":"Company disclosed-pay timeseries","description":"Daily median/p25/p75 disclosed pay for one company over a `days` window (same fixed set as `/timeseries`). A day with fewer than 5 disclosed listings reports `disclosed_count` honestly but null stats. `404 not_found` if the company is unknown. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_company_pay_timeseries","parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"days","in":"query","required":false,"schema":{"type":"string","default":"90","title":"Days"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPayTimeseries"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/skills":{"get":{"tags":["Skills"],"summary":"Skill directory","description":"Every public skill, with mention counts and 30-day deltas. **Cache class: published.** `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`; a stable `ETag` is attached and a matching `If-None-Match` returns `304` with the same cache and `X-Proletaria-Contract-Version` headers. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. A retained `?as_of=` date: **Cache class: snapshot** (only for a retained `?as_of=` date strictly before today). `Cache-Control: public, max-age=31536000, immutable` — a closed generation nothing ever rewrites. The unscoped/live request, and `?as_of=<today>`, remain `no-store`. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"list_skills","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Return the directory as it was published on this date (BE-45: D13), resolved against retained snapshot generations only. A date outside the retention window is a 404, never an approximation from the current directory.","title":"As Of"},"description":"Return the directory as it was published on this date (BE-45: D13), resolved against retained snapshot generations only. A date outside the retention window is a 404, never an approximation from the current directory."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillList"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/skills/{slug}":{"get":{"tags":["Skills"],"summary":"Skill detail","description":"One skill's mentions, pay premium, co-occurring skills, and top employers. A merged slug resolves through `serve.skill_redirects` and returns the surviving skill's own slug rather than 404ing. `404 not_found` if the slug is unknown. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. A retained `?as_of=` date: **Cache class: snapshot** (only for a retained `?as_of=` date strictly before today). `Cache-Control: public, max-age=31536000, immutable` — a closed generation nothing ever rewrites. The unscoped/live request, and `?as_of=<today>`, remain `no-store`. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_skill_detail","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Return this skill's detail as it was published on this date (BE-45: D13), resolved against retained snapshot generations only. A date outside the retention window is a 404, never an approximation from current data.","title":"As Of"},"description":"Return this skill's detail as it was published on this date (BE-45: D13), resolved against retained snapshot generations only. A date outside the retention window is a 404, never an approximation from current data."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillDetail"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/disciplines":{"get":{"tags":["Disciplines"],"summary":"Discipline catalog","description":"Every discipline in the code-defined taxonomy, including ones with zero open roles, plus the unclassified share. Computed live — `?as_of=` is always `404 snapshot_not_retained`. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"list_disciplines","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"BE-45 (D13): reserved for a future generation; see error detail.","title":"As Of"},"description":"BE-45 (D13): reserved for a future generation; see error detail."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisciplineCatalog"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/disciplines/{slug}":{"get":{"tags":["Disciplines"],"summary":"Discipline detail","description":"One discipline's KPIs, pay/time-to-fill, top skills, and top employers — mirrors `GET /api/skills/{slug}` panel for panel. `404 not_found` if the slug is outside the taxonomy. Computed live — `?as_of=` is always `404 snapshot_not_retained`. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_discipline_detail","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","csv"],"type":"string","default":"json","title":"Format"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"BE-45 (D13): reserved for a future generation; see error detail.","title":"As Of"},"description":"BE-45 (D13): reserved for a future generation; see error detail."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisciplineDetail"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/disciplines/{slug}/official":{"get":{"tags":["Disciplines"],"summary":"Official BLS benchmark for a discipline","description":"BLS OEWS employment/median-wage and Employment Projections growth for the SOC code(s) a discipline maps to (a reviewed registry, never a similarity match), cited alongside — never blended with — Proletaria's own posted-pay figure. `status: \"collecting\"` with null figures until the crosswalk and an approved OEWS/EP release both exist. `404 not_found` if the discipline slug is unknown. Not yet part of the cached route matrix: `Cache-Control: no-store`.","operationId":"get_discipline_official","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficialBenchmark"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/skills/{slug}/official":{"get":{"tags":["Skills"],"summary":"Official BLS benchmark for a skill","description":"The same benchmark as `GET /api/disciplines/{slug}/official`, for a skill's mapped SOC code(s). A merged slug resolves through `serve.skill_redirects`. `404 not_found` if the slug is unknown. Not yet part of the cached route matrix: `Cache-Control: no-store`.","operationId":"get_skill_official","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficialBenchmark"}}}},"404":{"description":"Public error envelope (not_found (or snapshot_not_retained on an as_of-bearing route)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/changelog":{"get":{"tags":["Changelog"],"summary":"Public contract/vocabulary changelog","description":"A public, auto-updating log of facts that make a cited number stop reproducing tomorrow: skill/company vocabulary merges and renames, coverage jumps, and contract-version bumps — nothing here is derived or estimated. **Cache class: private** (not yet in the cached route matrix): `Cache-Control: no-store`.","operationId":"get_changelog","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Changelog"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/seo/entities":{"get":{"tags":["SEO"],"summary":"Search-discovery manifest","description":"Canonical paths with source-backed modification dates for one entity kind (`companies`, `skills`, `listings`, `blogs`) — the sitemap generator's data source; the API never renders XML itself. **Cache class: entity.** Same policy as `published` — `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`, ETag/If-None-Match/304 supported. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. Shared only at the canonical 10,000-row page shape (`limit=10000`, `page` 1-1,000); other legal pagination sizes remain available but bypass the shared cache (`Cache-Control: no-store`). `kind=blogs` can return `503 publication_unavailable` with `Retry-After: 60`. A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data.","operationId":"get_seo_entities","parameters":[{"name":"kind","in":"query","required":true,"schema":{"enum":["companies","skills","listings","blogs"],"type":"string","title":"Kind"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":10000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoEntityManifest"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/static-pages":{"get":{"tags":["Static Pages"],"summary":"Static page deployment manifest","description":"Epoch-pinned pages of pre-rendered content for the web static-site deployment. `page > 1` requires `epoch` (`422 validation_error` if omitted); an epoch that no longer matches the current publication is `409 conflict` (restart from page 1). **Cache class: published.** `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`; a stable `ETag` is attached and a matching `If-None-Match` returns `304` with the same cache and `X-Proletaria-Contract-Version` headers. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. Unpublished schema (page 1 only): `503 publication_unavailable` with `Retry-After: 60`. A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data.","operationId":"get_static_pages","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":1,"title":"Page"}},{"name":"epoch","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Epoch"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPageManifest"}}}},"409":{"description":"Public error envelope (conflict).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/static-pages/candidates":{"get":{"tags":["Static Pages"],"summary":"Static page candidate manifest","description":"Epoch-pinned pages of candidate static pages, keyed the same way as `GET /api/static-pages` but always requiring `epoch`. **Cache class: published.** `Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400`; a stable `ETag` is attached and a matching `If-None-Match` returns `304` with the same cache and `X-Proletaria-Contract-Version` headers. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached. Unpublished schema (page 1 only): `503 publication_unavailable` with `Retry-After: 60`. A `503` here is retryable — clients should back off and retry rather than treat the gap as empty or `COLLECTING` data.","operationId":"get_static_page_candidates","parameters":[{"name":"epoch","in":"query","required":true,"schema":{"type":"integer","minimum":1,"title":"Epoch"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPageCandidates"}}}},"409":{"description":"Public error envelope (conflict).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"503":{"description":"Public error envelope (database_timeout, publication_unavailable, or service_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/search/suggest":{"get":{"tags":["Search"],"summary":"Company/skill autocomplete","description":"Prefix + trigram autocomplete over canonical companies and skills, up to 8 of each. An empty/blank `q` returns empty lists rather than an error. **Cache class: query.** High-cardinality request shapes are always `Cache-Control: no-store` (never cached, no ETag negotiation), except for the one canonical default-filter shape documented in `docs/api-contract.md`, which is cached at `fast-changing` policy instead. Anonymous cacheable responses use `Access-Control-Allow-Origin: *`; credentialed (`Authorization`/`Cookie`) requests keep strict configured-origin CORS and are never cached.","operationId":"get_search_suggest","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggest"}}}},"422":{"description":"Public error envelope (validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}}},"components":{"schemas":{"ActivePoint":{"properties":{"d":{"type":"string","title":"D"},"active":{"type":"integer","title":"Active"}},"type":"object","required":["d","active"],"title":"ActivePoint"},"BlogArchiveItem":{"properties":{"publication_status":{"type":"string","const":"published","title":"Publication Status"},"slug":{"type":"string","title":"Slug"},"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"week_start_utc":{"type":"string","title":"Week Start Utc"},"week_end_utc":{"type":"string","title":"Week End Utc"},"qualifying_discipline_count":{"type":"integer","title":"Qualifying Discipline Count"},"discipline":{"$ref":"#/components/schemas/BlogDisciplineRank"},"company_count":{"type":"integer","minimum":0.0,"title":"Company Count"},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count"},"published_at":{"type":"string","title":"Published At"}},"type":"object","required":["publication_status","slug","title","description","week_start_utc","week_end_utc","qualifying_discipline_count","discipline","company_count","citation_count","published_at"],"title":"BlogArchiveItem"},"BlogArchiveOption":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"}},"type":"object","required":["key","label"],"title":"BlogArchiveOption"},"BlogArchiveResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BlogArchiveItem"},"type":"array","title":"Items"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"},"total":{"type":"integer","title":"Total"},"total_pages":{"type":"integer","title":"Total Pages"},"available_weeks":{"items":{"type":"string"},"type":"array","title":"Available Weeks"},"disciplines":{"items":{"$ref":"#/components/schemas/BlogArchiveOption"},"type":"array","title":"Disciplines"}},"type":"object","required":["items","page","limit","total","total_pages","available_weeks","disciplines"],"title":"BlogArchiveResponse"},"BlogCompanyRank":{"properties":{"rank":{"type":"integer","minimum":1.0,"title":"Rank"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"name":{"type":"string","minLength":1,"title":"Name"},"added_count":{"type":"integer","minimum":0.0,"title":"Added Count"},"statements":{"items":{"$ref":"#/components/schemas/BlogStatement"},"type":"array","title":"Statements"},"postings":{"items":{"$ref":"#/components/schemas/BlogPostingCitation"},"type":"array","title":"Postings"}},"type":"object","required":["rank","slug","name","added_count","statements","postings"],"title":"BlogCompanyRank"},"BlogDisciplineRank":{"properties":{"key":{"type":"string","minLength":1,"title":"Key"},"label":{"type":"string","minLength":1,"title":"Label"},"rank":{"type":"integer","minimum":1.0,"title":"Rank"},"added_count":{"type":"integer","minimum":0.0,"title":"Added Count"}},"type":"object","required":["key","label","rank","added_count"],"title":"BlogDisciplineRank"},"BlogPost":{"properties":{"publication_status":{"type":"string","const":"published","title":"Publication Status"},"slug":{"type":"string","minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Slug"},"title":{"type":"string","minLength":1,"title":"Title"},"description":{"type":"string","minLength":1,"title":"Description"},"canonical_path":{"type":"string","minLength":1,"title":"Canonical Path"},"week_start_utc":{"type":"string","minLength":1,"title":"Week Start Utc"},"week_end_utc":{"type":"string","minLength":1,"title":"Week End Utc"},"qualifying_discipline_count":{"type":"integer","minimum":0.0,"title":"Qualifying Discipline Count"},"discipline":{"$ref":"#/components/schemas/BlogDisciplineRank"},"category_statements":{"items":{"$ref":"#/components/schemas/BlogStatement"},"type":"array","title":"Category Statements"},"companies":{"items":{"$ref":"#/components/schemas/BlogCompanyRank"},"type":"array","title":"Companies"},"methodology":{"items":{"type":"string"},"type":"array","title":"Methodology"},"model_disclosure":{"type":"string","minLength":1,"title":"Model Disclosure"},"published_at":{"type":"string","minLength":1,"title":"Published At"},"updated_at":{"type":"string","minLength":1,"title":"Updated At"}},"type":"object","required":["publication_status","slug","title","description","canonical_path","week_start_utc","week_end_utc","qualifying_discipline_count","discipline","category_statements","companies","methodology","model_disclosure","published_at","updated_at"],"title":"BlogPost","description":"The reviewed, published payload stored in ``serve.blog_posts``."},"BlogPostingCitation":{"properties":{"evidence_id":{"type":"string","minLength":1,"title":"Evidence Id"},"uid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uid"},"title":{"type":"string","minLength":1,"title":"Title"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"status":{"type":"string","enum":["active","archived","unavailable"],"title":"Status"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"}},"type":"object","required":["evidence_id","uid","title","location","status","source_url"],"title":"BlogPostingCitation"},"BlogStatement":{"properties":{"id":{"type":"string","minLength":1,"title":"Id"},"kind":{"type":"string","enum":["observation","inference","no_signal"],"title":"Kind"},"text":{"type":"string","minLength":1,"title":"Text"},"confidence":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Confidence"},"evidence_ids":{"items":{"type":"string"},"type":"array","title":"Evidence Ids"},"unsupported_dimension":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unsupported Dimension"}},"type":"object","required":["id","kind","text","confidence","evidence_ids","unsupported_dimension"],"title":"BlogStatement"},"Changelog":{"properties":{"generated_at":{"type":"string","title":"Generated At"},"entries":{"items":{"$ref":"#/components/schemas/ChangelogEntry"},"type":"array","title":"Entries"}},"type":"object","required":["generated_at","entries"],"title":"Changelog"},"ChangelogEntry":{"properties":{"kind":{"type":"string","enum":["skill_merge","skill_rename","company_merge","company_rename","coverage_jump","contract_version"],"title":"Kind"},"date":{"type":"string","title":"Date"},"summary":{"type":"string","minLength":1,"title":"Summary"},"detail":{"additionalProperties":true,"type":"object","title":"Detail"}},"type":"object","required":["kind","date","summary","detail"],"title":"ChangelogEntry","description":"One dated, honestly-sourced changelog fact (BE-45: D13).\n\n`detail` is kind-specific (see `app.services.changelog`); `date` is the\nday the underlying row was recorded — `serve.skill_redirects` /\n`serve.company_redirects.created_at`, `serve.companies.first_tracked`, or\n`ops.contract_version_log.changed_at` — never a derived/estimated date."},"CoOccurring":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"lift":{"type":"number","title":"Lift"},"pair_count":{"type":"integer","title":"Pair Count"}},"type":"object","required":["slug","name","lift","pair_count"],"title":"CoOccurring"},"CompanyDetail":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"hq":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hq"},"employees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employees"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"careers_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Careers Url"},"badge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Badge"},"badge_window_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Badge Window Days"},"status":{"type":"string","enum":["active","collecting","stale","paused"],"title":"Status"},"last_success":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Success"},"first_tracked":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Tracked"},"kpis":{"$ref":"#/components/schemas/CompanyKpis"},"series":{"$ref":"#/components/schemas/CompanySeries"},"locations":{"items":{"$ref":"#/components/schemas/LocationCount"},"type":"array","title":"Locations"},"functions":{"anyOf":[{"items":{"$ref":"#/components/schemas/FunctionShare"},"type":"array"},{"type":"null"}],"title":"Functions"},"profile":{"anyOf":[{"$ref":"#/components/schemas/CompanyProfile"},{"type":"null"}]},"pay_distribution":{"anyOf":[{"$ref":"#/components/schemas/PayDistribution"},{"type":"null"}]},"disciplines":{"anyOf":[{"$ref":"#/components/schemas/CompanyDisciplines"},{"type":"null"}]},"newest":{"items":{"$ref":"#/components/schemas/NewestListing"},"type":"array","title":"Newest"},"peers":{"$ref":"#/components/schemas/Peers"},"movement":{"anyOf":[{"$ref":"#/components/schemas/WeeklyMovement"},{"type":"null"}]}},"type":"object","required":["slug","name","industry","hq","employees","website","careers_url","badge","badge_window_days","status","last_success","first_tracked","kpis","series","locations","functions","profile","pay_distribution","disciplines","newest","peers","movement"],"title":"CompanyDetail"},"CompanyDisciplines":{"properties":{"classified":{"type":"integer","title":"Classified"},"items":{"items":{"$ref":"#/components/schemas/DisciplineShare"},"type":"array","title":"Items"}},"type":"object","required":["classified","items"],"title":"CompanyDisciplines"},"CompanyKpis":{"properties":{"open_roles":{"type":"integer","title":"Open Roles"},"change_7d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Change 7D Pct"},"change_14d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Change 14D Pct"},"change_30d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Change 30D Pct"},"median_pay":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Pay"},"pay_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pay N"},"pay_disclosed_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pay Disclosed Pct"},"median_pay_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Median Pay Reason"},"time_to_fill_days":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time To Fill Days"},"time_to_fill":{"anyOf":[{"$ref":"#/components/schemas/TimeToFill"},{"type":"null"}]},"remote_share_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Remote Share Pct"}},"type":"object","required":["open_roles","change_7d_pct","change_14d_pct","change_30d_pct","median_pay","pay_n","pay_disclosed_pct","median_pay_reason","time_to_fill_days","time_to_fill","remote_share_pct"],"title":"CompanyKpis"},"CompanyList":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CompanyListItem"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"CompanyList"},"CompanyListItem":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"open_roles":{"type":"integer","title":"Open Roles"},"delta_7d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta 7D Pct"},"delta_14d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta 14D Pct"},"delta_30d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta 30D Pct"},"status":{"type":"string","enum":["active","collecting","stale","paused"],"title":"Status"},"last_success":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Success"},"first_tracked":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Tracked"},"hq_metro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hq Metro"},"pay_disclosed_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pay Disclosed Pct"},"remote_share_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Remote Share Pct"}},"type":"object","required":["slug","name","industry","open_roles","delta_30d_pct","status","last_success","first_tracked"],"title":"CompanyListItem"},"CompanyLocations":{"properties":{"locations":{"items":{"$ref":"#/components/schemas/LocationItem"},"type":"array","title":"Locations"},"remote_count":{"type":"integer","title":"Remote Count"},"unmapped_count":{"type":"integer","title":"Unmapped Count"}},"type":"object","required":["locations","remote_count","unmapped_count"],"title":"CompanyLocations"},"CompanyPayTimeseries":{"properties":{"days":{"items":{"$ref":"#/components/schemas/PayDay"},"type":"array","title":"Days"},"window":{"type":"string","title":"Window"}},"type":"object","required":["days","window"],"title":"CompanyPayTimeseries"},"CompanyProfile":{"properties":{"blurb":{"type":"string","title":"Blurb"},"hiring_summary":{"type":"string","title":"Hiring Summary"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"active_listings":{"type":"integer","title":"Active Listings"},"new_listings_24h":{"type":"integer","title":"New Listings 24H"},"enriched_at":{"type":"string","title":"Enriched At"}},"type":"object","required":["blurb","hiring_summary","industry","active_listings","new_listings_24h","enriched_at"],"title":"CompanyProfile"},"CompanyRef":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"}},"type":"object","required":["slug","name","industry"],"title":"CompanyRef"},"CompanySeries":{"properties":{"granularity":{"type":"string","title":"Granularity"},"points":{"items":{"$ref":"#/components/schemas/ActivePoint"},"type":"array","title":"Points"}},"type":"object","required":["granularity","points"],"title":"CompanySeries"},"CompanyTimeseries":{"properties":{"days":{"items":{"$ref":"#/components/schemas/TimeseriesDay"},"type":"array","title":"Days"},"window":{"type":"string","title":"Window"}},"type":"object","required":["days","window"],"title":"CompanyTimeseries"},"CountryFacet":{"properties":{"key":{"type":"string","title":"Key"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","count"],"title":"CountryFacet","description":"D11: `key` is 'US' or an ISO2 code (`serve.listing_locations.country_code`).\n\nNo `label` — unlike `industries`/`disciplines`, there is no in-repo\ncountry-name vocabulary to answer to (CLAUDE.md: never fabricate one ad\nhoc), and ISO2/`'US'` render fine client-side, same as `work_mode`.\nListings with no resolved country (unmapped — the majority today, per\nD11's evidence) are omitted, same \"drop rather than invent an `other`\nbucket\" rule as `industries`/`disciplines`."},"DescriptionSection":{"properties":{"kind":{"type":"string","enum":["content","boilerplate"],"title":"Kind","description":"Only boilerplate sections are candidates for collapsed presentation."},"segments":{"items":{"$ref":"#/components/schemas/Segment"},"type":"array","title":"Segments","description":"Ordered raw/highlight blocks; flattening all sections reproduces the source."},"markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown","description":"Exact complete Markdown blocks, or null when no formatted rendering exists."},"summary":{"anyOf":[{"$ref":"#/components/schemas/DescriptionSectionSummary"},{"type":"null"}]},"has_search_match":{"type":"boolean","title":"Has Search Match","description":"True when an active query highlights text in this section."}},"type":"object","required":["kind","segments","markdown","summary","has_search_match"],"title":"DescriptionSection"},"DescriptionSectionSummary":{"properties":{"label":{"type":"string","const":"Repeated company information","title":"Label","description":"Fixed product copy; never a semantic or generated summary."},"blocks":{"type":"integer","minimum":1.0,"title":"Blocks","description":"Exact grouped detector source-block count."}},"type":"object","required":["label","blocks"],"title":"DescriptionSectionSummary"},"DescriptionSections":{"properties":{"detector_version":{"type":"string","title":"Detector Version","description":"Version of the company-scoped detector that produced these current annotations; semantic detector changes use a new value."},"sections":{"items":{"$ref":"#/components/schemas/DescriptionSection"},"type":"array","title":"Sections","description":"Source order is authoritative and every source word appears exactly once."}},"type":"object","required":["detector_version","sections"],"title":"DescriptionSections"},"DisciplineCatalog":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DisciplineCatalogItem"},"type":"array","title":"Items"},"unclassified_open_roles":{"type":"integer","title":"Unclassified Open Roles"}},"type":"object","required":["items","unclassified_open_roles"],"title":"DisciplineCatalog"},"DisciplineCatalogItem":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"function":{"type":"string","title":"Function"},"roles":{"items":{"type":"string"},"type":"array","title":"Roles"},"open_roles":{"type":"integer","title":"Open Roles"}},"type":"object","required":["key","label","function","roles","open_roles"],"title":"DisciplineCatalogItem"},"DisciplineDetail":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"function":{"type":"string","title":"Function"},"delta_30d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta 30D Pct"},"summary":{"type":"string","title":"Summary"},"kpis":{"$ref":"#/components/schemas/DisciplineKpis"},"postings":{"$ref":"#/components/schemas/Mentions"},"pay_distribution":{"anyOf":[{"$ref":"#/components/schemas/PayDistribution"},{"type":"null"}]},"pay_by_seniority":{"items":{"$ref":"#/components/schemas/SeniorityStep"},"type":"array","title":"Pay By Seniority"},"pay_by_metro":{"items":{"$ref":"#/components/schemas/MetroStep"},"type":"array","title":"Pay By Metro"},"top_skills":{"anyOf":[{"$ref":"#/components/schemas/DisciplineSkills"},{"type":"null"}]},"top_employers":{"items":{"$ref":"#/components/schemas/SkillEmployer"},"type":"array","title":"Top Employers"}},"type":"object","required":["key","label","function","delta_30d_pct","summary","kpis","postings","pay_distribution","pay_by_seniority","pay_by_metro","top_skills","top_employers"],"title":"DisciplineDetail"},"DisciplineFacet":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"function":{"type":"string","title":"Function"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","label","function","count"],"title":"DisciplineFacet"},"DisciplineKpis":{"properties":{"listings":{"type":"integer","title":"Listings"},"median_pay":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Pay"},"pay_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pay N"},"pay_disclosed_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pay Disclosed Pct"},"median_pay_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Median Pay Reason"},"employers":{"type":"integer","title":"Employers"},"remote_share_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Remote Share Pct"},"median_days_to_fill":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Days To Fill"},"time_to_fill":{"anyOf":[{"$ref":"#/components/schemas/TimeToFill"},{"type":"null"}]}},"type":"object","required":["listings","median_pay","pay_n","pay_disclosed_pct","median_pay_reason","employers","remote_share_pct","median_days_to_fill","time_to_fill"],"title":"DisciplineKpis"},"DisciplineRef":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"function":{"type":"string","title":"Function"}},"type":"object","required":["key","label","function"],"title":"DisciplineRef"},"DisciplineShare":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"function":{"type":"string","title":"Function"},"count":{"type":"integer","title":"Count"},"share_pct":{"type":"number","title":"Share Pct"}},"type":"object","required":["key","label","function","count","share_pct"],"title":"DisciplineShare"},"DisciplineSkill":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"count":{"type":"integer","title":"Count"},"share_pct":{"type":"number","title":"Share Pct"}},"type":"object","required":["slug","name","count","share_pct"],"title":"DisciplineSkill"},"DisciplineSkills":{"properties":{"extracted":{"type":"integer","title":"Extracted"},"items":{"items":{"$ref":"#/components/schemas/DisciplineSkill"},"type":"array","title":"Items"}},"type":"object","required":["extracted","items"],"title":"DisciplineSkills"},"Editorial":{"properties":{"date":{"type":"string","title":"Date"},"byline":{"type":"string","title":"Byline"},"sections":{"items":{"$ref":"#/components/schemas/EditorialSection"},"type":"array","title":"Sections"}},"type":"object","required":["date","byline","sections"],"title":"Editorial"},"EditorialSection":{"properties":{"key":{"type":"string","title":"Key"},"title":{"type":"string","title":"Title"},"body":{"type":"string","title":"Body"}},"type":"object","required":["key","title","body"],"title":"EditorialSection"},"EmploymentTypeFacet":{"properties":{"key":{"type":"string","title":"Key"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","count"],"title":"EmploymentTypeFacet"},"FacetCount":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","label","count"],"title":"FacetCount"},"Facets":{"properties":{"experience":{"items":{"$ref":"#/components/schemas/FacetCount"},"type":"array","title":"Experience"},"industries":{"items":{"$ref":"#/components/schemas/FacetCount"},"type":"array","title":"Industries"},"work_mode":{"items":{"$ref":"#/components/schemas/WorkModeFacet"},"type":"array","title":"Work Mode"},"employment_type":{"items":{"$ref":"#/components/schemas/EmploymentTypeFacet"},"type":"array","title":"Employment Type"},"disciplines":{"items":{"$ref":"#/components/schemas/DisciplineFacet"},"type":"array","title":"Disciplines"},"pay_unbanded_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pay Unbanded Pct"},"companies":{"items":{"$ref":"#/components/schemas/FacetCount"},"type":"array","title":"Companies"},"country":{"items":{"$ref":"#/components/schemas/CountryFacet"},"type":"array","title":"Country","default":[]}},"type":"object","required":["experience","industries","work_mode","employment_type","disciplines","pay_unbanded_pct","companies"],"title":"Facets"},"FunctionShare":{"properties":{"name":{"type":"string","title":"Name"},"share_pct":{"type":"number","title":"Share Pct"}},"type":"object","required":["name","share_pct"],"title":"FunctionShare"},"Headline":{"properties":{"title":{"type":"string","title":"Title"},"subtitle":{"type":"string","title":"Subtitle"}},"type":"object","required":["title","subtitle"],"title":"Headline"},"Health":{"properties":{"status":{"type":"string","title":"Status"},"db":{"type":"string","title":"Db"}},"type":"object","required":["status","db"],"title":"Health"},"HistogramPoint":{"properties":{"d":{"type":"string","title":"D"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["d","count"],"title":"HistogramPoint"},"IndustryShare":{"properties":{"name":{"type":"string","title":"Name"},"share_pct":{"type":"number","title":"Share Pct"},"rising":{"type":"boolean","title":"Rising"}},"type":"object","required":["name","share_pct","rising"],"title":"IndustryShare"},"Kpi":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"value_fmt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Fmt"},"delta_fmt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delta Fmt"},"direction":{"type":"string","title":"Direction"},"spark":{"anyOf":[{"items":{"$ref":"#/components/schemas/SparkPoint"},"type":"array"},{"type":"null"}],"title":"Spark"},"ttf":{"anyOf":[{"$ref":"#/components/schemas/TimeToFill"},{"type":"null"}]},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N"},"disclosed_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Disclosed Pct"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["key","label","value_fmt","delta_fmt","direction","spark"],"title":"Kpi"},"ListingDetail":{"properties":{"uid":{"type":"string","title":"Uid"},"title":{"type":"string","title":"Title"},"title_slug":{"type":"string","title":"Title Slug"},"company":{"$ref":"#/components/schemas/CompanyRef"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"work_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Work Mode"},"employment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employment Type"},"posted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Posted At"},"first_seen":{"type":"string","title":"First Seen"},"last_seen":{"type":"string","title":"Last Seen"},"is_active":{"type":"boolean","title":"Is Active"},"removed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Removed At"},"source_url":{"type":"string","title":"Source Url"},"pay":{"anyOf":[{"$ref":"#/components/schemas/Pay"},{"type":"null"}]},"pay_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pay Percentile"},"percentile_scope":{"$ref":"#/components/schemas/PercentileScope"},"similar_open":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Similar Open"},"avg_fill_days":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Fill Days"},"discipline":{"anyOf":[{"$ref":"#/components/schemas/DisciplineRef"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"},"locations":{"items":{"$ref":"#/components/schemas/ListingLocation"},"type":"array","title":"Locations"},"skills":{"items":{"$ref":"#/components/schemas/SkillTag"},"type":"array","title":"Skills"},"description_segments":{"items":{"$ref":"#/components/schemas/Segment"},"type":"array","title":"Description Segments"},"description_md":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description Md"},"description_sections":{"anyOf":[{"$ref":"#/components/schemas/DescriptionSections"},{"type":"null"}],"description":"Additive structured presentation. Null when feature-off, absent, stale, invalid, or ambiguously mapped; description_segments and description_md remain authoritative."}},"type":"object","required":["uid","title","title_slug","company","location","work_mode","employment_type","posted_at","first_seen","last_seen","is_active","removed_at","source_url","pay","pay_percentile","percentile_scope","similar_open","avg_fill_days","discipline","role","locations","skills","description_segments","description_md","description_sections"],"title":"ListingDetail"},"ListingLocation":{"properties":{"raw":{"type":"string","title":"Raw"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"metro_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Metro Id"},"metro_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metro Name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"is_remote":{"type":"boolean","title":"Is Remote"}},"type":"object","required":["raw","city","metro_id","metro_name","state","is_remote"],"title":"ListingLocation","description":"One `serve.listing_locations` row. metro fields are null when the raw\nstring resolved to no Census metro (non-US, state-only, unknown locality) —\nserved as itself rather than dropped or guessed at."},"LocationCount":{"properties":{"location":{"type":"string","title":"Location"},"count":{"type":"integer","title":"Count"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"}},"type":"object","required":["location","count"],"title":"LocationCount"},"LocationItem":{"properties":{"metro_id":{"type":"integer","title":"Metro Id"},"cbsa_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cbsa Code"},"name":{"type":"string","title":"Name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"lat":{"type":"number","title":"Lat"},"lon":{"type":"number","title":"Lon"},"count":{"type":"integer","title":"Count"},"sample_titles":{"items":{"type":"string"},"type":"array","title":"Sample Titles"},"office":{"anyOf":[{"$ref":"#/components/schemas/OfficePoint"},{"type":"null"}]}},"type":"object","required":["metro_id","cbsa_code","name","state","lat","lon","count","sample_titles"],"title":"LocationItem"},"MarketLocationItem":{"properties":{"metro_id":{"type":"integer","title":"Metro Id"},"name":{"type":"string","title":"Name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"lat":{"type":"number","title":"Lat"},"lon":{"type":"number","title":"Lon"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["metro_id","name","state","lat","lon","count"],"title":"MarketLocationItem"},"MarketLocations":{"properties":{"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"locations":{"items":{"$ref":"#/components/schemas/MarketLocationItem"},"type":"array","title":"Locations"},"mapped_count":{"type":"integer","title":"Mapped Count"},"remote_count":{"type":"integer","title":"Remote Count"},"unmapped_count":{"type":"integer","title":"Unmapped Count"},"total_active":{"type":"integer","title":"Total Active"}},"type":"object","required":["as_of","locations","mapped_count","remote_count","unmapped_count","total_active"],"title":"MarketLocations"},"MentionPoint":{"properties":{"d":{"type":"string","title":"D"},"v":{"type":"integer","title":"V"}},"type":"object","required":["d","v"],"title":"MentionPoint"},"Mentions":{"properties":{"unit":{"type":"string","title":"Unit"},"points":{"items":{"$ref":"#/components/schemas/MentionPoint"},"type":"array","title":"Points"}},"type":"object","required":["unit","points"],"title":"Mentions"},"Meta":{"properties":{"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"history_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"History Start"},"days_of_history":{"type":"integer","title":"Days Of History"},"companies_tracked":{"type":"integer","title":"Companies Tracked"},"listings_active":{"type":"integer","title":"Listings Active"},"listings_total":{"type":"integer","title":"Listings Total"},"last_ingest_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Ingest At"}},"type":"object","required":["as_of","history_start","days_of_history","companies_tracked","listings_active","listings_total","last_ingest_at"],"title":"Meta"},"MetroItem":{"properties":{"metro":{"type":"string","title":"Metro"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["metro","count"],"title":"MetroItem"},"MetroStep":{"properties":{"metro_id":{"type":"integer","title":"Metro Id"},"metro_name":{"type":"string","title":"Metro Name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"median_annual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Annual"},"p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25"},"p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75"},"n":{"type":"integer","title":"N"}},"type":"object","required":["metro_id","metro_name","state","median_annual","p25","p75","n"],"title":"MetroStep","description":"One qualifying metro row of a skill's or discipline's pay-by-metro\nblock (serve.rollup_pay_by_metro, BE-42 D9). Bounded to the top 20\nqualifying metros by n at read time — the contract states the list is\nbounded and makes no claim of exhaustive metro coverage."},"Metros":{"properties":{"label":{"type":"string","title":"Label"},"items":{"items":{"$ref":"#/components/schemas/MetroItem"},"type":"array","title":"Items"}},"type":"object","required":["label","items"],"title":"Metros"},"Mover":{"properties":{"title_group":{"type":"string","title":"Title Group"},"count":{"type":"integer","title":"Count"},"delta_pct":{"type":"number","title":"Delta Pct"}},"type":"object","required":["title_group","count","delta_pct"],"title":"Mover"},"Movers":{"properties":{"window":{"type":"string","title":"Window"},"gainers":{"items":{"$ref":"#/components/schemas/Mover"},"type":"array","title":"Gainers"},"decliners":{"items":{"$ref":"#/components/schemas/Mover"},"type":"array","title":"Decliners"}},"type":"object","required":["window","gainers","decliners"],"title":"Movers"},"NewestListing":{"properties":{"uid":{"type":"string","title":"Uid"},"title":{"type":"string","title":"Title"},"age_fmt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Age Fmt"},"first_seen":{"type":"string","title":"First Seen"}},"type":"object","required":["uid","title","age_fmt","first_seen"],"title":"NewestListing"},"OfficePoint":{"properties":{"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"lat":{"type":"number","title":"Lat"},"lon":{"type":"number","title":"Lon"}},"type":"object","required":["address","lat","lon"],"title":"OfficePoint"},"OfficialBenchmark":{"properties":{"subject_type":{"type":"string","enum":["discipline","skill"],"title":"Subject Type"},"subject_slug":{"type":"string","title":"Subject Slug"},"status":{"type":"string","enum":["ready","collecting"],"title":"Status"},"soc":{"items":{"$ref":"#/components/schemas/OfficialSocMatch"},"type":"array","title":"Soc"},"posted_pay_comparison":{"anyOf":[{"$ref":"#/components/schemas/OfficialPostedPayComparison"},{"type":"null"}]}},"type":"object","required":["subject_type","subject_slug","status","soc","posted_pay_comparison"],"title":"OfficialBenchmark"},"OfficialFigure":{"properties":{"value":{"type":"number","title":"Value"},"vintage":{"type":"string","title":"Vintage"},"source":{"type":"string","title":"Source"},"source_url":{"type":"string","title":"Source Url"}},"type":"object","required":["value","vintage","source","source_url"],"title":"OfficialFigure","description":"One externally sourced number, never blended with Proletaria's own\nseries -- see docs/api-contract.md's \"Official benchmark\" section."},"OfficialPostedPayComparison":{"properties":{"median_posted_annual":{"type":"number","title":"Median Posted Annual"},"n":{"type":"integer","title":"N"},"median_oews_annual":{"type":"number","title":"Median Oews Annual"},"oews_vintage":{"type":"string","title":"Oews Vintage"}},"type":"object","required":["median_posted_annual","n","median_oews_annual","oews_vintage"],"title":"OfficialPostedPayComparison"},"OfficialSocMatch":{"properties":{"soc_code":{"type":"string","title":"Soc Code"},"soc_version":{"type":"string","title":"Soc Version"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"relationship":{"type":"string","enum":["primary","related"],"title":"Relationship"},"crosswalk_source_note":{"type":"string","title":"Crosswalk Source Note"},"employment":{"anyOf":[{"$ref":"#/components/schemas/OfficialFigure"},{"type":"null"}]},"median_wage_annual":{"anyOf":[{"$ref":"#/components/schemas/OfficialFigure"},{"type":"null"}]},"projected_growth_pct":{"anyOf":[{"$ref":"#/components/schemas/OfficialFigure"},{"type":"null"}]}},"type":"object","required":["soc_code","soc_version","title","relationship","crosswalk_source_note","employment","median_wage_annual","projected_growth_pct"],"title":"OfficialSocMatch"},"Overview":{"properties":{"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"range":{"type":"string","title":"Range"},"headline":{"$ref":"#/components/schemas/Headline"},"kpis":{"items":{"$ref":"#/components/schemas/Kpi"},"type":"array","title":"Kpis"},"postings_series":{"anyOf":[{"$ref":"#/components/schemas/PostingsSeries"},{"type":"null"}]},"posting_date_series":{"anyOf":[{"$ref":"#/components/schemas/PostingDateSeries"},{"type":"null"}]},"movers":{"anyOf":[{"$ref":"#/components/schemas/Movers"},{"type":"null"}]},"top_employers":{"items":{"$ref":"#/components/schemas/TopEmployer"},"type":"array","title":"Top Employers"},"trending_skills":{"anyOf":[{"$ref":"#/components/schemas/TrendingSkills"},{"type":"null"}]},"pullbacks":{"anyOf":[{"$ref":"#/components/schemas/Pullbacks"},{"type":"null"}]},"metros":{"anyOf":[{"$ref":"#/components/schemas/Metros"},{"type":"null"}]},"editorial":{"anyOf":[{"$ref":"#/components/schemas/Editorial"},{"type":"null"}]},"scope":{"$ref":"#/components/schemas/OverviewScope"}},"type":"object","required":["as_of","range","headline","kpis","postings_series","movers","top_employers","trending_skills","metros","editorial"],"title":"Overview"},"OverviewScope":{"properties":{"key":{"type":"string","enum":["global","US"],"title":"Key"},"label":{"type":"string","title":"Label"}},"type":"object","required":["key","label"],"title":"OverviewScope","description":"D11: which population `kpis`/`headline` describe.\n\n`key` is `\"global\"` (every tracked country — the historical default) or\n`\"US\"` (`?country=US`, live-scoped, same WHERE `country_code=US` search\nalready filters on — see `app.services.search.build_where`). `label` is\nthe honest, renderable disclosure the ticket asks for: while `global`\nstays the default, its label says \"US + international\" rather than\nletting a reader assume a mixed-country headline is a US number."},"Pay":{"properties":{"min":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min"},"max":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max"},"currency":{"type":"string","title":"Currency"},"period":{"type":"string","title":"Period"}},"type":"object","required":["min","max","currency","period"],"title":"Pay"},"PayBin":{"properties":{"lo":{"type":"integer","title":"Lo"},"hi":{"type":"integer","title":"Hi"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["lo","hi","count"],"title":"PayBin"},"PayDay":{"properties":{"d":{"type":"string","title":"D"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"},"p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25"},"p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75"},"disclosed_count":{"type":"integer","title":"Disclosed Count"}},"type":"object","required":["d","median","p25","p75","disclosed_count"],"title":"PayDay"},"PayDistribution":{"properties":{"ready":{"type":"boolean","title":"Ready"},"min_n":{"type":"integer","title":"Min N"},"bins":{"items":{"$ref":"#/components/schemas/PayBin"},"type":"array","title":"Bins"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"}},"type":"object","required":["ready","min_n","bins","median"],"title":"PayDistribution"},"PaySummary":{"properties":{"n":{"type":"integer","title":"N"},"disclosed_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Disclosed Pct"},"p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"},"p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["n","disclosed_pct","p25","median","p75","reason"],"title":"PaySummary","description":"Filtered-set pay summary (BE-38), opt-in via `include=pay_summary`.\n\nFloored exactly like every other headline pay figure (TODO #238:\nproletaria_core.disclosure.PAY_MIN_N/PAY_MIN_DISCLOSURE_PCT). `n` (the\nfiltered set's priced-listing count) and `disclosed_pct` are always\npresent, even when the floor nulls `p25`/`median`/`p75` — a client can\nstill show the sample size. `reason` is `\"below_floor\"` exactly when the\nfloor nulled the percentiles."},"PeerItem":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"open_roles":{"type":"integer","title":"Open Roles"},"delta_30d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta 30D Pct"}},"type":"object","required":["slug","name","open_roles","delta_30d_pct"],"title":"PeerItem"},"Peers":{"properties":{"label":{"type":"string","title":"Label"},"items":{"items":{"$ref":"#/components/schemas/PeerItem"},"type":"array","title":"Items"}},"type":"object","required":["label","items"],"title":"Peers"},"PercentileScope":{"properties":{"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"discipline":{"anyOf":[{"$ref":"#/components/schemas/PercentileScopeDiscipline"},{"type":"null"}]},"experience":{"anyOf":[{"$ref":"#/components/schemas/PercentileScopeExperience"},{"type":"null"}]},"metro":{"anyOf":[{"$ref":"#/components/schemas/PercentileScopeMetro"},{"type":"null"}]},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"state":{"type":"string","title":"State"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["key","label","discipline","experience","metro","n","as_of","state","reason"],"title":"PercentileScope","description":"BE-42 D9: what a listing's `pay_percentile` actually compares against.\n\nAlways present, including on a `pay_percentile: null` response — the\ncontract is that a client can render \"vs Senior ML · Austin (n=212)\" (or\nthe equivalent) from `label`/`n` alone, and never has to fall back to an\nunqualified \"market\" string. `state: \"ready\"` means `key`/`n`/`as_of` are\nreal; `state: \"collecting\"` means `reason` explains why no scope (down to\nmarket) could be produced, and `key`/`n` may be null or describe the last\ndimension that was checked, never a percentile that was invented."},"PercentileScopeDiscipline":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"}},"type":"object","required":["key","label"],"title":"PercentileScopeDiscipline"},"PercentileScopeExperience":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"}},"type":"object","required":["key","label"],"title":"PercentileScopeExperience"},"PercentileScopeMetro":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},"type":"object","required":["id","name","state"],"title":"PercentileScopeMetro"},"PostingDateSeries":{"properties":{"label":{"type":"string","title":"Label"},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"},"points":{"items":{"$ref":"#/components/schemas/PostingDateSeriesPoint"},"type":"array","title":"Points"},"stats":{"$ref":"#/components/schemas/PostingDateSeriesStats"}},"type":"object","required":["label","since","points","stats"],"title":"PostingDateSeries"},"PostingDateSeriesPoint":{"properties":{"d":{"type":"string","title":"D"},"active":{"type":"integer","title":"Active"},"inactive":{"type":"integer","title":"Inactive"}},"type":"object","required":["d","active","inactive"],"title":"PostingDateSeriesPoint"},"PostingDateSeriesStats":{"properties":{"total":{"type":"integer","title":"Total"},"active":{"type":"integer","title":"Active"},"inactive":{"type":"integer","title":"Inactive"},"undated":{"type":"integer","title":"Undated"}},"type":"object","required":["total","active","inactive","undated"],"title":"PostingDateSeriesStats"},"PostingsSeries":{"properties":{"label":{"type":"string","title":"Label"},"since":{"type":"string","title":"Since"},"points":{"items":{"$ref":"#/components/schemas/SeriesPoint"},"type":"array","title":"Points"},"stats":{"$ref":"#/components/schemas/SeriesStats"}},"type":"object","required":["label","since","points","stats"],"title":"PostingsSeries"},"PublicError":{"properties":{"error":{"type":"string","title":"Error","examples":["not_found"]},"detail":{"type":"string","title":"Detail","examples":["Unknown company"]}},"type":"object","required":["error","detail"],"title":"PublicError","description":"BE-28: the one envelope every public 4xx/503 uses (see\n`app.core.errors`). `error` is a stable machine code (`not_found`,\n`validation_error`, `invalid_request`, `conflict`, `rate_limited`,\n`database_timeout`, `publication_unavailable`, `service_unavailable`,\n`snapshot_not_retained`); `detail` is a human-readable message that may\nchange wording without a contract-version bump."},"Pullback":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"net_removed":{"type":"integer","title":"Net Removed"},"delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta Pct"}},"type":"object","required":["slug","name","net_removed","delta_pct"],"title":"Pullback"},"Pullbacks":{"properties":{"label":{"type":"string","title":"Label"},"window":{"type":"string","title":"Window"},"items":{"items":{"$ref":"#/components/schemas/Pullback"},"type":"array","title":"Items"}},"type":"object","required":["label","window","items"],"title":"Pullbacks"},"QueryErrorOut":{"properties":{"message":{"type":"string","title":"Message"},"position":{"type":"integer","title":"Position"}},"type":"object","required":["message","position"],"title":"QueryErrorOut"},"SearchResponse":{"properties":{"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"},"query_error":{"anyOf":[{"$ref":"#/components/schemas/QueryErrorOut"},{"type":"null"}]},"facets":{"anyOf":[{"$ref":"#/components/schemas/Facets"},{"type":"null"}]},"histogram":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistogramPoint"},"type":"array"},{"type":"null"}],"title":"Histogram"},"pay_summary":{"anyOf":[{"$ref":"#/components/schemas/PaySummary"},{"type":"null"}]},"results":{"items":{"$ref":"#/components/schemas/SearchResult"},"type":"array","title":"Results"},"similar_to":{"anyOf":[{"$ref":"#/components/schemas/SimilarTo"},{"type":"null"}]},"check_uid_matches":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Check Uid Matches"}},"type":"object","required":["total","page","limit","query_error","facets","histogram","results"],"title":"SearchResponse"},"SearchResult":{"properties":{"uid":{"type":"string","title":"Uid"},"title":{"type":"string","title":"Title"},"company":{"$ref":"#/components/schemas/CompanyRef"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"location_count":{"type":"integer","title":"Location Count"},"work_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Work Mode"},"pay":{"anyOf":[{"$ref":"#/components/schemas/Pay"},{"type":"null"}]},"posted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Posted At"},"posted_at_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Posted At Source"},"first_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Seen"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen"},"source_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Kind"},"age_fmt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Age Fmt"}},"type":"object","required":["uid","title","company","location","location_count","work_mode","pay","posted_at","posted_at_source","first_seen","last_seen","source_kind","age_fmt"],"title":"SearchResult"},"Segment":{"properties":{"text":{"type":"string","title":"Text"},"hl":{"type":"boolean","title":"Hl"}},"type":"object","required":["text","hl"],"title":"Segment"},"SeniorityStep":{"properties":{"seniority":{"type":"string","title":"Seniority"},"median_annual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Annual"},"p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25"},"p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75"},"n":{"type":"integer","title":"N"}},"type":"object","required":["seniority","median_annual","p25","p75","n"],"title":"SeniorityStep","description":"One rung of a discipline's or skill's posted-pay ladder\n(serve.rollup_pay_summary for a discipline's own seniority x discipline\ncell, serve.rollup_pay_by_experience for both — BE-42 D9). Rungs below\nthe rollup's n floor are absent, not zeroed — the ladder is as long as\nthe honest evidence, never padded."},"SeoEntity":{"properties":{"path":{"type":"string","title":"Path"},"lastmod":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastmod"}},"type":"object","required":["path","lastmod"],"title":"SeoEntity","description":"One canonical public route and its most recent database observation."},"SeoEntityManifest":{"properties":{"kind":{"type":"string","enum":["companies","skills","listings","blogs"],"title":"Kind"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"},"total":{"type":"integer","title":"Total"},"items":{"items":{"$ref":"#/components/schemas/SeoEntity"},"type":"array","title":"Items"}},"type":"object","required":["kind","page","limit","total","items"],"title":"SeoEntityManifest"},"SeriesPoint":{"properties":{"d":{"type":"string","title":"D"},"active":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active"},"added":{"type":"integer","title":"Added"},"removed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Removed"}},"type":"object","required":["d","active","added","removed"],"title":"SeriesPoint"},"SeriesStats":{"properties":{"high":{"type":"integer","title":"High"},"low":{"type":"integer","title":"Low"},"avg_new_per_day":{"type":"number","title":"Avg New Per Day"},"days_tracked":{"type":"integer","title":"Days Tracked"}},"type":"object","required":["high","low","avg_new_per_day","days_tracked"],"title":"SeriesStats"},"SimilarTo":{"properties":{"uid":{"type":"string","title":"Uid"},"title":{"type":"string","title":"Title"},"company":{"$ref":"#/components/schemas/CompanyRef"},"state":{"type":"string","enum":["ready","collecting"],"title":"State"}},"type":"object","required":["uid","title","company","state"],"title":"SimilarTo","description":"Source-listing context for a ?similar= search (contract: Similar mode).\n\nstate \"collecting\" = the source's embedding isn't computed yet, so the\nsimilar set is unknowable — the client renders COLLECTING, never \"0\"."},"SkillDetail":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"delta_30d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta 30D Pct"},"summary":{"type":"string","title":"Summary"},"kpis":{"$ref":"#/components/schemas/SkillKpis"},"mentions":{"$ref":"#/components/schemas/Mentions"},"pay_distribution":{"anyOf":[{"$ref":"#/components/schemas/PayDistribution"},{"type":"null"}]},"pay_by_seniority":{"items":{"$ref":"#/components/schemas/SeniorityStep"},"type":"array","title":"Pay By Seniority"},"pay_by_metro":{"items":{"$ref":"#/components/schemas/MetroStep"},"type":"array","title":"Pay By Metro"},"co_occurring":{"items":{"$ref":"#/components/schemas/CoOccurring"},"type":"array","title":"Co Occurring"},"top_employers":{"items":{"$ref":"#/components/schemas/SkillEmployer"},"type":"array","title":"Top Employers"},"industries":{"anyOf":[{"items":{"$ref":"#/components/schemas/IndustryShare"},"type":"array"},{"type":"null"}],"title":"Industries"}},"type":"object","required":["slug","name","delta_30d_pct","summary","kpis","mentions","pay_distribution","pay_by_seniority","pay_by_metro","co_occurring","top_employers","industries"],"title":"SkillDetail"},"SkillEmployer":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["slug","name","count"],"title":"SkillEmployer"},"SkillKpis":{"properties":{"listings":{"type":"integer","title":"Listings"},"median_pay":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Pay"},"pay_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pay N"},"pay_disclosed_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pay Disclosed Pct"},"median_pay_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Median Pay Reason"},"pay_premium_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pay Premium Pct"},"pay_premium_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pay Premium N"},"pay_premium_pct_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pay Premium Pct Reason"},"employers":{"type":"integer","title":"Employers"},"remote_share_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Remote Share Pct"}},"type":"object","required":["listings","median_pay","pay_n","pay_disclosed_pct","median_pay_reason","pay_premium_pct","pay_premium_n","pay_premium_pct_reason","employers","remote_share_pct"],"title":"SkillKpis"},"SkillList":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SkillListItem"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"SkillList"},"SkillListItem":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"listings":{"type":"integer","title":"Listings"},"delta_30d_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta 30D Pct"}},"type":"object","required":["slug","name","listings","delta_30d_pct"],"title":"SkillListItem"},"SkillTag":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"matched":{"type":"boolean","title":"Matched"}},"type":"object","required":["slug","name","matched"],"title":"SkillTag"},"SparkPoint":{"properties":{"d":{"type":"string","title":"D"},"v":{"type":"number","title":"V"}},"type":"object","required":["d","v"],"title":"SparkPoint"},"StaticPageCandidate":{"properties":{"path":{"type":"string","title":"Path"},"action":{"type":"string","enum":["upsert","delete"],"title":"Action"},"source_etag":{"type":"string","title":"Source Etag"},"lastmod":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastmod"}},"type":"object","required":["path","action","source_etag","lastmod"],"title":"StaticPageCandidate"},"StaticPageCandidates":{"properties":{"publication_epoch":{"type":"integer","title":"Publication Epoch"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total":{"type":"integer","title":"Total"},"total_pages":{"type":"integer","title":"Total Pages"},"items":{"items":{"$ref":"#/components/schemas/StaticPageCandidate"},"type":"array","title":"Items"}},"type":"object","required":["publication_epoch","as_of","page","page_size","total","total_pages","items"],"title":"StaticPageCandidates"},"StaticPageCorpus":{"properties":{"max_entries":{"type":"integer","title":"Max Entries"},"platform_file_budget":{"type":"integer","title":"Platform File Budget"},"listing_cap":{"type":"integer","title":"Listing Cap"},"listing_eligible":{"type":"integer","title":"Listing Eligible"},"listing_selected":{"type":"integer","title":"Listing Selected"},"reserved_file_headroom":{"type":"integer","title":"Reserved File Headroom"}},"type":"object","required":["max_entries","platform_file_budget","listing_cap","listing_eligible","listing_selected","reserved_file_headroom"],"title":"StaticPageCorpus"},"StaticPageItem":{"properties":{"path":{"type":"string","title":"Path"},"kind":{"type":"string","enum":["home","company_directory","skill_directory","company","skill","listing"],"title":"Kind"},"tier":{"type":"string","enum":["rich","standard"],"title":"Tier"},"lastmod":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lastmod"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"source_etag":{"type":"string","title":"Source Etag"},"source":{"anyOf":[{"$ref":"#/components/schemas/StaticPageSource"},{"type":"null"}]},"render":{"$ref":"#/components/schemas/StaticPageRender"}},"type":"object","required":["path","kind","tier","lastmod","as_of","source_etag","source","render"],"title":"StaticPageItem"},"StaticPageManifest":{"properties":{"publication_epoch":{"type":"integer","title":"Publication Epoch"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total":{"type":"integer","title":"Total"},"total_pages":{"type":"integer","title":"Total Pages"},"corpus":{"$ref":"#/components/schemas/StaticPageCorpus"},"items":{"items":{"$ref":"#/components/schemas/StaticPageItem"},"type":"array","title":"Items"}},"type":"object","required":["publication_epoch","as_of","page","page_size","total","total_pages","corpus","items"],"title":"StaticPageManifest"},"StaticPageRender":{"properties":{"schema_version":{"type":"integer","const":1,"title":"Schema Version"},"mode":{"type":"string","enum":["rich","summary"],"title":"Mode"},"data":{"additionalProperties":true,"type":"object","title":"Data"}},"type":"object","required":["schema_version","mode","data"],"title":"StaticPageRender"},"StaticPageSource":{"properties":{"representation":{"type":"string","title":"Representation"},"key":{"type":"string","title":"Key"}},"type":"object","required":["representation","key"],"title":"StaticPageSource"},"Suggest":{"properties":{"companies":{"items":{"$ref":"#/components/schemas/SuggestItem"},"type":"array","title":"Companies"},"skills":{"items":{"$ref":"#/components/schemas/SuggestItem"},"type":"array","title":"Skills"}},"type":"object","required":["companies","skills"],"title":"Suggest"},"SuggestItem":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"}},"type":"object","required":["slug","name"],"title":"SuggestItem"},"Ticker":{"properties":{"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"},"items":{"items":{"$ref":"#/components/schemas/TickerItem"},"type":"array","title":"Items"}},"type":"object","required":["as_of","items"],"title":"Ticker"},"TickerItem":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"value_fmt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Fmt"},"delta_fmt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delta Fmt"},"direction":{"type":"string","title":"Direction"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"}},"type":"object","required":["key","label","value_fmt","delta_fmt","direction"],"title":"TickerItem"},"TimeToFill":{"properties":{"median_days":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Days"},"definition":{"type":"string","title":"Definition"},"observed_days":{"type":"integer","title":"Observed Days"},"n_closed":{"type":"integer","title":"N Closed"},"share_still_open":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share Still Open"}},"type":"object","required":["median_days","definition","observed_days","n_closed","share_still_open"],"title":"TimeToFill","description":"Right-censored median days-to-fill, disclosed (BE-33).\n\n`median_days` is null whenever it isn't honestly reportable — below\n`TTF_MIN_HISTORY_DAYS` of platform history, or below the caller's own\nminimum closed-posting floor — and `definition` always says which. See\n`proletaria_core.ttf` for the shared shaping logic."},"TimeseriesDay":{"properties":{"d":{"type":"string","title":"D"},"by_function":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Function"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["d","by_function","total"],"title":"TimeseriesDay"},"TopEmployer":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"open_roles":{"type":"integer","title":"Open Roles"},"delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta Pct"}},"type":"object","required":["slug","name","open_roles","delta_pct"],"title":"TopEmployer"},"TrendingSkill":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"mentions":{"type":"integer","title":"Mentions"},"delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta Pct"},"intensity":{"type":"number","title":"Intensity"}},"type":"object","required":["slug","name","mentions","delta_pct","intensity"],"title":"TrendingSkill"},"TrendingSkills":{"properties":{"window":{"type":"string","title":"Window"},"items":{"items":{"$ref":"#/components/schemas/TrendingSkill"},"type":"array","title":"Items"}},"type":"object","required":["window","items"],"title":"TrendingSkills"},"WeeklyMovement":{"properties":{"label":{"type":"string","title":"Label"},"points":{"items":{"$ref":"#/components/schemas/WeeklyMovementPoint"},"type":"array","title":"Points"}},"type":"object","required":["label","points"],"title":"WeeklyMovement"},"WeeklyMovementPoint":{"properties":{"week":{"type":"string","title":"Week"},"added":{"type":"integer","title":"Added"},"removed":{"type":"integer","title":"Removed"},"partial":{"type":"boolean","title":"Partial"}},"type":"object","required":["week","added","removed","partial"],"title":"WeeklyMovementPoint"},"WorkModeFacet":{"properties":{"key":{"type":"string","title":"Key"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","count"],"title":"WorkModeFacet"}}},"tags":[{"name":"Health","description":"Liveness/startup and database-health probes."},{"name":"Platform","description":"Site metadata and the market ticker tape."},{"name":"Market","description":"Whole-market overview and location breakdowns."},{"name":"Editorial","description":"The daily editorial desk and the weekly blog archive it feeds."},{"name":"Listings","description":"Job-posting search, export, and detail."},{"name":"Companies","description":"The company directory and per-company detail."},{"name":"Skills","description":"The skill directory, detail, and official benchmarks."},{"name":"Disciplines","description":"The code-defined discipline taxonomy, detail, and official benchmarks."},{"name":"SEO","description":"Bounded entity manifests for sitemap generation."},{"name":"Static Pages","description":"Epoch-pinned bulk inputs for the static-site deployment."},{"name":"Search","description":"Company/skill autocomplete."},{"name":"Changelog","description":"The public vocabulary/contract-version changelog."}]}