> ## Documentation Index
> Fetch the complete documentation index at: https://docs.folksbase.joselito.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> How to explore and interact with the folksbase API using the OpenAPI spec and Scalar UI.

## Overview

The folksbase API is a RESTful JSON API built with [Hono](https://hono.dev). 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:

| Endpoint                | What it returns                     |
| ----------------------- | ----------------------------------- |
| `GET /api/openapi.json` | Machine-readable OpenAPI 3.1 spec   |
| `GET /api/docs`         | Interactive 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:

```bash theme={"dark"}
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](https://scalar.com), 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:

| Environment | Base URL                         |
| ----------- | -------------------------------- |
| Production  | `https://folksbase.onrender.com` |
| Local dev   | `http://localhost:3001`          |

All endpoints are prefixed with `/api/`. For example, listing contacts is `GET /api/contacts`.

## Next Steps

* [Authentication](/api/authentication) — how to obtain and pass JWT tokens
* [Rate Limiting](/api/rate-limiting) — request limits and headers
* [Error Responses](/api/errors) — the standard error shape returned by all endpoints