{ "openapi": "3.0.3", "info": { "title": "Xcout Company Intelligence API", "version": "1.2.0", "description": "Read-only access to company intelligence, funding history, metric time-series, rankings, and the global jobs catalog. Authenticate with a service-account API key (`Authorization: Bearer sk_intel_...`), created in the app under Settings → API keys. **Keys are server-side credentials — call this API from your backend only. Never embed a key in a browser, mobile app, or other client-distributed code; anyone can extract it and spend your quota.** Requests are rate-limited per minute and metered in **records** against a monthly credit budget: 1 credit = 1 company record = **10 job postings** (job rows bill in blocks of 10). Every job row carries Xcout's proprietary classifications — `job_family`, `ai_level` (0–3), `green_level`, `dei_level` — at 100% coverage. Error reasons: `invalid_key`/`key_revoked`/`key_expired` (401), `quota_exceeded`/`record_quota_exceeded` (402), `scope_missing`/`api_disabled`/`feature_disabled` (403), `rate_limited` (429, includes a `Retry-After` header)." }, "servers": [ { "url": "https://ypoibupymucaermphfpa.supabase.co/functions/v1/api-v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Service-account API key, e.g. sk_intel_..." } } }, "paths": { "/companies": { "get": { "summary": "Search companies", "description": "Filter companies by name, country, industry, public/private, tools, events, investors, funding, and web-traffic tier. Each row includes `web_rank` (best Tranco/CrUX rank, lower = more visited) and `traffic_tier`. Scope `read:companies`.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "name substring", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "comma-separated", "schema": { "type": "string" } }, { "name": "industry", "in": "query", "required": false, "description": "comma-separated canonical industries — valid values from GET /industries", "schema": { "type": "string" } }, { "name": "is_public", "in": "query", "required": false, "description": "", "schema": { "type": "boolean" } }, { "name": "tool", "in": "query", "required": false, "description": "comma-separated tool names", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "comma-separated event types", "schema": { "type": "string" } }, { "name": "investor", "in": "query", "required": false, "description": "investor_key(s), comma-separated", "schema": { "type": "string" } }, { "name": "min_raised", "in": "query", "required": false, "description": "min USD raised in any round", "schema": { "type": "number" } }, { "name": "round", "in": "query", "required": false, "description": "funding round type(s), comma-separated", "schema": { "type": "string" } }, { "name": "funded_days", "in": "query", "required": false, "description": "raised within N days", "schema": { "type": "integer" } }, { "name": "traffic_tier", "in": "query", "required": false, "description": "comma-separated web-traffic tiers: Top 1k | Top 10k | Top 100k | Top 1M", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "hiring | market_cap | tech | name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "default 50, capped by export_rows", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/companies/{id}": { "get": { "summary": "Company detail", "description": "Full profile incl. financials, tools, events, investors, funding rounds, web presence (`web_presence`, `presence`, `web_tech`), and passive domain/subdomain intelligence. The `subdomains` block carries `count`, `resolved`, `live` (hosts answering on 80/443), `tech_hosts`, and a `hosts[]` sample — each `{host, resolves, live, status, tech[]}` — with live/infrastructure hosts first. `top_country_ranks` lists the countries where the company's site is a **top-50,000 website by real in-country Chrome usage** (Google CrUX country data, refreshed monthly): each `{cc, rank, month}` where `rank` is the CrUX bucket (1000 | 5000 | 10000 | 50000) and `cc` is ISO 3166-1 alpha-2. `detected_customers` carries customers recognized from **tenant subdomains** on the company's own apex (e.g. `customer.vendor.com`, from certificate-transparency scans): `tenant_labels` (total tenant-style subdomains), `customers[]` (`{company_id, name, domain, host}` — only exact matches against tracked companies; presence signals, not a confirmed customer list), and `history[]` (`{on, tenants, recognized}` weekly series for tracking the tenant base over time). The inverse edges appear on each customer's own profile under `tools` as category `saas_tenant`. Scope `read:companies`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/companies/{id}/people": { "get": { "summary": "Company people", "description": "Directors, officers, founders and C-suite for one company, with provenance. `source` distinguishes how each was established: `sec:form-d` (filed with the SEC on a Form D related-persons list — primary source), `fmp:key-executives` / `fmp:insider`, `website`, `wikidata`, `news` (LLM-extracted from an article). Filter by `source` to take only what you trust. `role_level` is one of founder | c_suite | officer | board. Scope `read:companies`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "role_level", "in": "query", "required": false, "description": "founder | c_suite | officer | board", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "sec:form-d | fmp:key-executives | fmp:insider | website | wikidata | news", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "default 100, max 500", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/industries": { "get": { "summary": "Canonical industry list", "description": "The ~52 canonical industry buckets with live company counts. Use these exact values for the `industry` filter on /companies and /funding-rounds (raw source strings are consolidated server-side). Scope `read:companies`.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/funding-rounds": { "get": { "summary": "Query funding rounds", "description": "Dated funding rounds with amounts and investors. Rounds we have judged to belong to a different company of the same name are left out. Scope `read:funding`, feature `history_funding`.", "parameters": [ { "name": "round", "in": "query", "required": false, "description": "comma-separated", "schema": { "type": "string" } }, { "name": "min_amount", "in": "query", "required": false, "description": "USD", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "required": false, "description": "USD", "schema": { "type": "number" } }, { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "comma-separated", "schema": { "type": "string" } }, { "name": "industry", "in": "query", "required": false, "description": "comma-separated canonical industries — valid values from GET /industries", "schema": { "type": "string" } }, { "name": "investor", "in": "query", "required": false, "description": "investor name contains", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/metrics": { "get": { "summary": "Metric time-series", "description": "A company's metric history: valuation_usd, market_cap, revenue_usd, enterprise_value, pe_ratio, ev_to_ebitda, price_to_sales, employee_count, etc. Scope `read:history`, feature `history_metrics`.", "parameters": [ { "name": "company_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "metric", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/ai-rank": { "get": { "summary": "Xcout AI Rank", "description": "0-100 AI-engagement score from the company's own job postings: 70% intensity (0.25·share mentioning AI + 0.35·share using + 0.40·share building) + 30% depth (log-scaled count of AI-build roles, saturating at 40). Only postings with readable descriptions count. With `company_id` the response also carries `ai_activity` — news-based AI signals (acquisitions of AI companies, AI-framed funding, launches) with evidence headlines, covering companies whose hiring is too thin to rank. With `company_id`: that company's current rank, month, `direction` (up|down|flat vs previous month), and level counts `l1`/`l2`/`l3` of `jobs` — or `eligible:false` with the 10-description minimum. Without `company_id`: the current month's top-ranked companies plus cohort stats (`ranked_companies`, `up_count`, `down_count`). AI tool indicators (categories `ai_ml` = builds on an AI stack, `ai_devtool` = uses AI assistants) are included in `/companies/{id}` under `tools`. Scope `read:companies`.", "parameters": [ { "name": "company_id", "in": "query", "required": false, "description": "company to look up; omit for the leaderboard", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "leaderboard size, default 15, max 30", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/jobs": { "get": { "summary": "Search job postings", "description": "The global jobs catalog — ATS-sourced postings from 45k+ employer feeds across 97 countries, accumulating since 2026-04 (~330k new postings/month). Filter by the proprietary classifications: `family` (display name from /jobs/trends, e.g. \"Software Engineer\"), `min_ai` / `min_green` (levels 0–3), `ats` (greenhouse | workday | smartrecruiters | lever | ashby | personio | workable | recruitee). **`observed_after` is the delta/feed parameter**: pass your last pull's timestamp and receive only postings observed since — the supported way to run a continuous feed without re-billing full pulls. Rows bill at 10 per credit. Fields are documented honestly: `has_description` marks postings with substantive text (~54%); salary is not carried. Scope `read:jobs`.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "title substring", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "required": false, "description": "an Xcout company id — postings are pre-joined to the company graph", "schema": { "type": "integer" } }, { "name": "family", "in": "query", "required": false, "description": "job family display name, e.g. Software Engineer", "schema": { "type": "string" } }, { "name": "ats", "in": "query", "required": false, "description": "ATS provider", "schema": { "type": "string" } }, { "name": "min_ai", "in": "query", "required": false, "description": "minimum ai_level 0-3", "schema": { "type": "integer" } }, { "name": "min_green", "in": "query", "required": false, "description": "minimum green_level 0-3", "schema": { "type": "integer" } }, { "name": "observed_after", "in": "query", "required": false, "description": "ISO timestamp — only postings observed after this (delta pulls)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "default 100, max 1000", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "max 10000 — page deeper with `observed_after`, which is indexed", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/jobs/{id}": { "get": { "summary": "Job posting detail", "description": "One posting with full description text (where captured), apply URL, and all classification levels. Scope `read:jobs`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/jobs/trends": { "get": { "summary": "Monthly hiring trends", "description": "Postings per month by job family, with AI-flagged and green-flagged counts and distinct hiring companies. **Complete months only** — the month in progress is never included, so trend arrows never lie. Also serves as the discovery endpoint for valid `family` values. Scope `read:jobs`.", "parameters": [ { "name": "family", "in": "query", "required": false, "description": "restrict to one job family", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "required": false, "description": "restrict to one company", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/companies/{id}/jobs": { "get": { "summary": "A company's postings", "description": "Live and historical postings for one company from the jobs catalog, pre-joined by resolved company id (not name matching). The cross-dataset join — hiring activity in the same call graph as funding, events, and people. Scope `read:companies`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "family", "in": "query", "required": false, "description": "job family display name", "schema": { "type": "string" } }, { "name": "min_ai", "in": "query", "required": false, "description": "minimum ai_level", "schema": { "type": "integer" } }, { "name": "observed_after", "in": "query", "required": false, "description": "ISO timestamp", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "default 100, max 1000", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/companies/{id}/hiring": { "get": { "summary": "Hiring composition", "description": "The company's hiring mix — counts by role kind/label, recomputed nightly from its own postings. Scope `read:companies`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/rankings": { "get": { "summary": "AI / Green / DEI rankings", "description": "Monthly company rankings computed from each company's own job postings. `kind=ai|green|dei`. Without `company_id`: the leaderboard for the latest complete month (with company names). With `company_id`: that company's last 12 monthly rows. Complete months only. Scope `read:companies`.", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "ai | green | dei (default ai)", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "required": false, "description": "one company's history instead of the leaderboard", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "leaderboard size, default 50, max 200", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/places": { "get": { "summary": "US places: jobs, companies hiring and pay by state or city", "description": "US states (and DC) or cities ranked by open job postings, from the jobs catalog's nightly place snapshot: listed postings first seen in the last 100 days that are located in a US city. Each row: `key` (state code, or a city's GeoNames id), `name`, `state_code`, `lat`/`lon`/`population` (cities), `jobs`, `companies_hiring` (distinct employers posting there — where companies hire, not where they are headquartered), `ai_jobs` and `ai_share` (postings that use or build AI, ai_level >= 2), `pay` (`p25`/`median`/`p75` of the annual USD salary the postings state, only with >= 20 salaried postings; `salaried_postings` is that count), `top_families` (6), `top_companies` (5; `company_id` and `intel_name` when the employer resolves to an Intel company), `top_cities` (states, 5), `window`, `as_of`. A city exists only with >= 25 postings. Scope `read:companies`; **1 record per place returned**.", "parameters": [ { "name": "level", "in": "query", "required": false, "description": "state (default) | city", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "two-letter code; with level=city, only that state's cities", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "jobs (default) | companies | ai_share | pay_median | name", "schema": { "type": "string" } }, { "name": "min_jobs", "in": "query", "required": false, "description": "only places with at least this many postings", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "default 60 for states, 50 for cities; max 250", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "endpoint": { "type": "string" }, "rate_limit_per_min": { "type": "integer" }, "monthly_quota": { "type": "integer", "nullable": true }, "row_cap": { "type": "integer", "nullable": true } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/places/{key}": { "get": { "summary": "One US state or city", "description": "The full place row: every listed field of `/places`, plus up to 15 job families each with `pay_median`/`pay_n` where >= 20 salaried postings, 8 top employers and (states) 10 top cities. `key` is a two-letter state code (`CA`, `DC`) or a city's numeric id from `/places?level=city`. 404 `not_found` for an unknown key (not metered). Scope `read:companies`; 1 record.", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "/metrics/catalog": { "get": { "summary": "Available metric names", "description": "The metric names `/metrics` accepts — no more guessing. Scope `read:companies`.", "parameters": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } } } }