Y Combinator Reader (Read-Only)

curl

Step 1: Verify Prerequisites

curl

jq

!`(command -v curl > /dev/null && echo "CURL_OK" || echo "CURL_MISSING") && (command -v jq > /dev/null && echo "JQ_OK" || echo "JQ_MISSING")`

JQ_MISSING

# macOS
brew install jq

# Linux (Debian/Ubuntu)
sudo apt-get install jq

jq

curl

jq

Step 2: Identify What the User Needs

references/api_reference.md

meta.json

companies/all.json

companies/top.json

companies/hiring.json

companies/nonprofit.json

companies/black-founded.json

hispanic-latino-founded.json

women-founded.json

batches/{batch-name}.json

winter-2025.json

summer-2024.json

industries/{industry}.json

fintech.json

healthcare.json

tags/{tag}.json

ai.json

developer-tools.json

Batch name format

{season}-{year}

winter-2025

summer-2024

fall-2025

summer-2005

Industry and tag name format

real-estate

developer-tools

machine-learning

Step 3: Execute the Request

Base URL

https://yc-oss.github.io/api/

General pattern

# Fetch and pretty-print
curl -s https://yc-oss.github.io/api/companies/top.json | jq .

# Count companies in a result
curl -s https://yc-oss.github.io/api/batches/winter-2025.json | jq length

# Filter by field (e.g., hiring companies in a batch)
curl -s https://yc-oss.github.io/api/batches/winter-2025.json | jq '[.[] | select(.isHiring == true)]'

# Extract specific fields
curl -s https://yc-oss.github.io/api/companies/top.json | jq '.[] | {name, one_liner, batch, team_size, website}'

# Search by name (case-insensitive)
curl -s https://yc-oss.github.io/api/companies/all.json | jq '[.[] | select(.name | test("stripe"; "i"))]'

Key rules

1. Use

   -s

   flag with curl to suppress progress output
2. Pipe through

   jq

   for readable output and filtering
3. Avoid fetching

   companies/all.json

   unless necessary — it's a large response (~5,700 companies). Prefer more specific endpoints (batches, industries, tags) when possible
4. Use

   jq

   select/filter to narrow results client-side when the API doesn't have a specific endpoint for what the user wants
5. Batch names are lowercase with hyphens —

   winter-2025

   not

   Winter 2025

   or

   W25

6. Tag and industry names are lowercase with hyphens —

   developer-tools

   not

   Developer Tools

Common jq filters

jq length

jq '.[0]'

jq '.[:10]'

jq '[.[] | select(.isHiring == true)]'

jq '[.[] | select(.status == "Active")]'

jq '[.[] | select(.team_size > 100)]'

jq '.[] | {name, one_liner, batch, website}'

jq '[.[] | select(.name | test("query"; "i"))]'

jq 'sort_by(-.team_size) | .[:10]'

Step 4: Present the Results

1. Summarize key data — company name, one-liner, batch, team size, status, and website
2. Highlight hiring status — note which companies are actively hiring (growth signal)
3. Include website URLs when the user might want to visit the company
4. For batch listings, summarize the batch size and notable companies
5. For industry/tag queries, highlight trends (how many companies, which are top/hiring)
6. For research queries, provide aggregate stats (count, common industries, team size distribution)
7. Note the data freshness — the API updates daily, so data is near-real-time

Step 5: Diagnostics

404 Not Found

meta.json

[]

curl: Could not resolve host

companies/all.json

jq

# List all batches
curl -s https://yc-oss.github.io/api/meta.json | jq '.batches[].name'

# List all industries
curl -s https://yc-oss.github.io/api/meta.json | jq '.industries[].name'

# List all tags (there are 333+)
curl -s https://yc-oss.github.io/api/meta.json | jq '.tags[].name'

Reference Files

• references/api_reference.md

  — Complete endpoint reference with company schema, all endpoint URLs, and research workflow examples