YSWS Programs API

Hack Club YSWS Programs API

Public read-only REST API for Hack Club's You Ship We Ship programs, backed by Airtable.

Table of Contents

1. About
2. Built With
3. Setup
4. Project Structure
5. API Endpoints
6. Response Format
7. Contact

About

This API serves Hack Club YSWS program data from Airtable. It is public and read-only — no authentication is required for any public endpoint.

Live demo + API docs: https://events-api.hackclub.dev/api

Features:

• All programs, or filtered by status (active / upcoming / ended)
• Single program lookup by Airtable record ID
• Redis caching (5 min TTL) to minimise Airtable API usage
• Rate limited to 100 requests per 15 minutes per IP

Built With

• Node.js
• Express 5
• Airtable
• Upstash Redis — response caching
• Vercel — deployment

Setup

1. Install dependencies:

   npm install

2. Copy .env.example to .env and fill in your credentials:

   cp .env.example .env

3. Run locally:

   npm run dev

Project Structure

public/              # Static frontend demo
controllers/         # Route handler logic
routes/              # Express route definitions
middleware/
  cache.js           # Upstash Redis cache
server.js            # App entrypoint

API Endpoints

Base URL: https://events-api.hackclub.dev

All endpoints are GET and publicly accessible. Responses include an X-Cache header (HIT / MISS) indicating whether the response was served from cache.

Programs

URL	Description
GET /api/programs	All listed programs, sorted by Start Date descending
GET /api/programs/active	Programs currently running (Start Date ≤ today ≤ End Date)
GET /api/programs/upcoming	Programs whose Start Date is in the future
GET /api/programs/ended	Programs whose End Date has passed
GET /api/programs/:id	Single program by Airtable record ID

Query params for GET /api/programs:

Param	Description
include_unlisted=true	Include unlisted programs. Requires x-api-key header.

Other

URL	Description
GET /api	API documentation
GET /health	Health check

Quick Start

# All programs
curl https://events-api.hackclub.dev/api/programs

# Active programs only
curl https://events-api.hackclub.dev/api/programs/active

# Upcoming programs
curl https://events-api.hackclub.dev/api/programs/upcoming

# Single program by ID
curl https://events-api.hackclub.dev/api/programs/recABC123

Response Format

All list endpoints return:

{
  "success": true,
  "count": 9,
  "data": [
    {
      "id": "recABC123",
      "Name": "Stardance",
      "Start Date": "2026-05-30",
      "End Date": "2026-09-30",
      "Website URL": "https://stardance.hackclub.com/program_page",
      "Icon – CDN Link": "https://cdn.hackclub.com/...",
      "HCB": "https://hcb.hackclub.com/stardance",
      "createdTime": "2026-05-21T19:43:29.000Z"
    }
  ]
}

Contact

Tanishq Goyal - @Tanuki - tanishqgoyal590@gmail.com

(back to top)