# folksbase

## Docs

- [Bulk delete contacts](https://docs.folksbase.joselito.dev/api-reference/contacts/bulk-delete-contacts.md): Deletes multiple contacts by ID. Maximum 500 per request.
- [Create contact](https://docs.folksbase.joselito.dev/api-reference/contacts/create-contact.md): Creates a new contact in the workspace. Automatically fetches Gravatar avatar.
- [Delete contact](https://docs.folksbase.joselito.dev/api-reference/contacts/delete-contact.md): Permanently deletes a single contact.
- [Get contact](https://docs.folksbase.joselito.dev/api-reference/contacts/get-contact.md): Returns a single contact by ID, including associated tags.
- [List contacts](https://docs.folksbase.joselito.dev/api-reference/contacts/list-contacts.md): Returns a paginated list of contacts for the workspace. Supports search, tag filtering, and unsubscribe filtering.
- [Send email to contact](https://docs.folksbase.joselito.dev/api-reference/contacts/send-email-to-contact.md): Sends a one-off email to a contact using the workspace's Resend API key.
- [Update contact](https://docs.folksbase.joselito.dev/api-reference/contacts/update-contact.md): Partially updates a contact. Re-fetches Gravatar if email changes.
- [Create export](https://docs.folksbase.joselito.dev/api-reference/exports/create-export.md): Starts a CSV export job. Optionally filter by tag IDs.
- [Delete export](https://docs.folksbase.joselito.dev/api-reference/exports/delete-export.md): Deletes an export record and its associated blob file.
- [Download export CSV](https://docs.folksbase.joselito.dev/api-reference/exports/download-export-csv.md): Downloads the completed export as a CSV file.
- [Get export status](https://docs.folksbase.joselito.dev/api-reference/exports/get-export-status.md): Returns the current status and progress of an export job.
- [List exports](https://docs.folksbase.joselito.dev/api-reference/exports/list-exports.md): Returns a paginated list of exports for the workspace.
- [Confirm import](https://docs.folksbase.joselito.dev/api-reference/imports/confirm-import.md): Confirms the column mapping and starts CSV processing.
- [Delete import](https://docs.folksbase.joselito.dev/api-reference/imports/delete-import.md): Deletes an import record and its associated blob file.
- [Download import CSV](https://docs.folksbase.joselito.dev/api-reference/imports/download-import-csv.md): Downloads the original uploaded CSV file.
- [Get import preview](https://docs.folksbase.joselito.dev/api-reference/imports/get-import-preview.md): Re-fetches the CSV preview and AI suggestions for a pending import.
- [Get import status](https://docs.folksbase.joselito.dev/api-reference/imports/get-import-status.md): Returns the current status and progress of an import job.
- [List imports](https://docs.folksbase.joselito.dev/api-reference/imports/list-imports.md): Returns a paginated list of imports for the workspace.
- [Upload CSV](https://docs.folksbase.joselito.dev/api-reference/imports/upload-csv.md): Uploads a CSV file and returns a preview with AI-suggested column mappings. Max 200 MB.
- [Get workspace settings](https://docs.folksbase.joselito.dev/api-reference/settings/get-workspace-settings.md): Returns the workspace settings. The Resend API key is masked.
- [Update workspace settings](https://docs.folksbase.joselito.dev/api-reference/settings/update-workspace-settings.md): Updates workspace settings. Send null for resend_api_key to remove it.
- [Get workspace stats](https://docs.folksbase.joselito.dev/api-reference/stats/get-workspace-stats.md): Returns dashboard statistics for the workspace. Cached for 5 minutes.
- [Add tag to contact](https://docs.folksbase.joselito.dev/api-reference/tags/add-tag-to-contact.md): Associates a tag with a contact.
- [Create tag](https://docs.folksbase.joselito.dev/api-reference/tags/create-tag.md): Creates a new tag in the workspace.
- [Delete tag](https://docs.folksbase.joselito.dev/api-reference/tags/delete-tag.md): Permanently deletes a tag.
- [List tags](https://docs.folksbase.joselito.dev/api-reference/tags/list-tags.md): Returns all tags for the workspace.
- [Remove tag from contact](https://docs.folksbase.joselito.dev/api-reference/tags/remove-tag-from-contact.md): Removes a tag association from a contact.
- [Update tag](https://docs.folksbase.joselito.dev/api-reference/tags/update-tag.md): Updates an existing tag.
- [Authentication](https://docs.folksbase.joselito.dev/api/authentication.md): How authentication works in the folksbase API using Supabase Auth and JWT tokens.
- [Error Responses](https://docs.folksbase.joselito.dev/api/errors.md): The standard error response format used by all folksbase API endpoints.
- [API Overview](https://docs.folksbase.joselito.dev/api/overview.md): How to explore and interact with the folksbase API using the OpenAPI spec and Scalar UI.
- [Rate Limiting](https://docs.folksbase.joselito.dev/api/rate-limiting.md): How the folksbase API limits request rates to prevent abuse, including the global and upload-specific limiters.
- [Backend Architecture](https://docs.folksbase.joselito.dev/architecture/backend.md): The layered architecture pattern used in the Hono API and why it exists.
- [Database Schema](https://docs.folksbase.joselito.dev/architecture/database.md): Entity relationships, table definitions, multi-tenancy model, and naming conventions.
- [Design Patterns](https://docs.folksbase.joselito.dev/architecture/design-patterns.md): The recurring design patterns used across the folksbase codebase and why they exist.
- [Frontend Architecture](https://docs.folksbase.joselito.dev/architecture/frontend.md): RSC-first approach, component structure, and data fetching patterns in the Next.js app.
- [Architecture Overview](https://docs.folksbase.joselito.dev/architecture/overview.md): Monorepo structure, tech stack, and the reasoning behind each choice.
- [Streaming Architecture](https://docs.folksbase.joselito.dev/architecture/streaming.md): How folksbase handles large CSV files without running out of memory.
- [Individual Jobs](https://docs.folksbase.joselito.dev/background-jobs/jobs.md): Detailed documentation for each background job in folksbase — what they do, how they work, and how they handle failure.
- [Background Jobs Overview](https://docs.folksbase.joselito.dev/background-jobs/overview.md): How folksbase uses Inngest for reliable background job orchestration with step-level retries.
- [Adding API Routes](https://docs.folksbase.joselito.dev/contributing/adding-routes.md): How to add new Hono routes with OpenAPI documentation, validation, and proper layering.
- [Code Style](https://docs.folksbase.joselito.dev/contributing/code-style.md): Biome rules, TypeScript strictness, and coding conventions enforced across the project.
- [Git Conventions](https://docs.folksbase.joselito.dev/contributing/git.md): Commit format, branch naming, PR rules, and local git hooks.
- [Development Setup](https://docs.folksbase.joselito.dev/contributing/setup.md): Get folksbase running locally in a few minutes.
- [Testing](https://docs.folksbase.joselito.dev/contributing/testing.md): How to write and run unit tests with Vitest and E2E tests with Playwright.
- [CI/CD](https://docs.folksbase.joselito.dev/deployment/ci-cd.md): GitHub Actions workflows that run on every pull request and push to main.
- [Environment Variables](https://docs.folksbase.joselito.dev/deployment/environment.md): All required environment variables for running folksbase in development and production.
- [Deployment Overview](https://docs.folksbase.joselito.dev/deployment/overview.md): Where each part of folksbase is deployed and how the pieces connect.
- [Render Deployment](https://docs.folksbase.joselito.dev/deployment/render.md): How to deploy the folksbase API to Render using the render.yaml blueprint.
- [Troubleshooting](https://docs.folksbase.joselito.dev/deployment/troubleshooting.md): Common deployment issues and how to fix them.
- [Vercel Deployment](https://docs.folksbase.joselito.dev/deployment/vercel.md): How to deploy the folksbase web app to Vercel.
- [AI Integration](https://docs.folksbase.joselito.dev/features/ai-integration.md): How folksbase uses Claude Haiku for CSV column mapping — and what happens when the AI is unavailable.
- [Contact Management](https://docs.folksbase.joselito.dev/features/contacts.md): How to create, search, filter, tag, and manage contacts in folksbase.
- [CSV Import](https://docs.folksbase.joselito.dev/features/csv-import.md): How folksbase handles CSV uploads — from file validation to AI-powered column mapping to chunked background processing.
- [Dashboard](https://docs.folksbase.joselito.dev/features/dashboard.md): The folksbase dashboard — stats at a glance, contact growth trends, and recent activity.
- [Exports](https://docs.folksbase.joselito.dev/features/exports.md): How to export contacts as CSV — with optional tag filtering and streaming for large datasets.
- [Tags](https://docs.folksbase.joselito.dev/features/tags.md): How the tag system works — creating tags, assigning them to contacts, and filtering by multiple tags.
- [Introduction](https://docs.folksbase.joselito.dev/introduction.md): Learn about the folksbase project
- [Opportunities and Technical Debt](https://docs.folksbase.joselito.dev/opportunities.md): Things that will make the project better
- [Plan and Execution](https://docs.folksbase.joselito.dev/plan-and-execution.md): Why folksbase is the way it is
- [Quickstart](https://docs.folksbase.joselito.dev/quickstart.md): Get the project running locally
- [Using AI](https://docs.folksbase.joselito.dev/using-ai.md): My philosophy and workflow

## OpenAPI Specs

- [openapi](https://docs.folksbase.joselito.dev/api-reference/openapi.json)

## Optional

- [Storybook](https://storybook.docs.folksbase.joselito.dev)