📚 API Documentation

Ships API v1

All endpoints return JSON. Authenticated endpoints require a valid session cookie (login via the web UI first).

Base URL: https://ships.hackclub.com/api/v1

GET /api/v1/ysws_entries 🌐 Public

Returns all YSWS project entries (cached 5 min).

Response Fields

Field Type Description
id string Airtable record ID
ysws string YSWS program name
approved_at integer|null Unix timestamp of approval
code_url string|null GitHub/code repository URL
country string|null Country of the creator
demo_url string|null Live demo URL
description string|null Project description
github_username string|null GitHub username
heard_through string|null How they heard about YSWS
hours number|null Hours spent on project
screenshot_url string|null Screenshot URL
🌐 Test in Browser
GET /api/v1/stats 🌐 Public

Returns global statistics for all projects (cached 5 min).

Response Fields

Field Type Description
total_projects integer Total number of projects
total_hours number Sum of all hours spent
total_stars integer Sum of all GitHub stars
viral_projects integer Projects with >5 stars
projects_by_country object Top 15 countries by project count
projects_by_ysws object Projects grouped by YSWS program
top_starred array Top 10 starred projects
recent_projects array 10 most recently approved projects
🌐 Test in Browser
GET /api/v1/me 🔒 Auth Required

Returns all project entries for the authenticated user.

Response Fields

Field Type Description
[] array Array of YswsProjectEntry objects
🌐 Test in Browser
GET /api/v1/dashboard 🔒 Auth Required

Returns dashboard data for the authenticated user.

Response Fields

Field Type Description
user.email string User's email
user.name string User's display name
entries array Array of user's project entries
🌐 Test in Browser
GET /api/v1/cached_images/:id 🌐 Public

Returns cached image data by Airtable ID.

Response Fields

Field Type Description
original_url string Original image URL
cached_url string Cached/proxied image URL
🌐 Test in Browser