Skip to main content

​
Overview

The folksbase API is a RESTful JSON API built with Hono. Every route is documented using the OpenAPI 3.1 specification, auto-generated from the route definitions themselves. This means the spec is always in sync with the actual code — no manual YAML files to maintain. Two endpoints give you access to the API documentation:
EndpointWhat it returns
GET /api/openapi.jsonMachine-readable OpenAPI 3.1 spec
GET /api/docsInteractive Scalar API reference UI

​
OpenAPI Spec

The spec is generated at runtime by hono-openapi from the describeRoute() and zValidator() decorators on each route handler. It includes:
  • All public endpoints (contacts, tags, imports, exports, settings, stats)
  • Request schemas (query params, path params, JSON bodies, form data)
  • Response schemas for every status code
  • Authentication requirements (Bearer JWT)
  • Server URLs for production and local development
Fetch it directly: 
curl https://folksbase.onrender.com/api/openapi.json
You can import this spec into tools like Postman, Insomnia, or any OpenAPI-compatible client to generate request collections automatically.

​
What’s excluded

Internal and infrastructure endpoints are intentionally left out of the spec:
  • Auth webhooks (/api/webhooks) — called by Supabase, not by API consumers
  • Inngest routes (/api/inngest) — background job orchestration, internal only

​
Scalar API Reference

The interactive docs at /api/docs are powered by Scalar, themed with the “saturn” preset. They provide:
  • A searchable list of all endpoints grouped by tag (Contacts, Tags, Imports, Exports, Settings, Stats)
  • Request/response schema viewers with example values
  • A built-in API client for making live requests directly from the browser
  • Authentication configuration — set your Bearer token once and it applies to all requests
Visit the live reference: 
https://folksbase.onrender.com/api/docs
Or locally when running the API in dev mode: 
http://localhost:3001/api/docs

​
Base URLs

The API is available at two servers, both documented in the OpenAPI spec:
EnvironmentBase URL
Productionhttps://folksbase.onrender.com
Local devhttp://localhost:3001
All endpoints are prefixed with /api/. For example, listing contacts is GET /api/contacts.

​
Next Steps