Frequently Asked Questions

Common questions about using Foir.

General

What is Foir?

Foir is a backend platform for building applications. It gives you a database with a typed GraphQL API, authentication for your end users, file and media storage, transactional email, billing, background jobs, and search — as one platform, with each project’s data isolated in the database by default. Rather than assembling and securing those services yourself, you configure them in one place.

Who is Foir for?

Development teams and studios building one or more applications who would otherwise wire together a database, an auth provider, object storage, email, billing, and a job queue — and take on securing and maintaining that stack. Foir is a particularly good fit when you run several apps at once: each is its own isolated project under one account. You get:

• A database with a typed GraphQL API and versioned, publishable content
• Authentication for your end users, including hosted login on custom domains
• Database-enforced data isolation between projects
• File and media storage with on-the-fly image transforms
• Transactional email, billing, and durable background jobs
• Full-text and semantic search, personalization, and localization
• Config-as-code, a CLI, and an Editor SDK to extend the admin

Is Foir a headless CMS?

Foir includes everything a headless CMS does — content modeling, versioning, publishing, localization, personalization — but it’s a full application backend, not just a content layer. Alongside content it gives you authentication for your end users, file and media storage, email, billing, background jobs, and database-enforced access control. So it replaces the stack you’d otherwise assemble from a database service, an auth provider, and object storage — not only a CMS.

Content & Data

What’s the difference between models with and without versioning?

All data in Foir uses the same models and records system. Each model has a kind — record-bearing (its own records) or inline (an embeddable Block schema with no records of its own) — and a set of capabilities you choose to enable: versioning, publishing, and variants. A “page” model might have all capabilities enabled, while a “booking” model might have none. Both use the same API.

Can I create custom content schemas?

Yes. Models are fully customizable. Define your own fields using built-in field types (text, content, number, image, etc.) or create reusable inline schemas that can be embedded as field types in other models.

How does versioning work?

For models with versioning enabled, every change creates a new version. You can review version history, compare changes, and publish specific versions. Variants each have independent version histories.

Does Foir support rich text content?

Yes. Rich text fields support formatted content with headings, lists, links, embedded media, and more. Rich text content is fully translatable across locales.

API

What API does Foir use?

Foir uses GraphQL for all data operations. The public API endpoint is https://api.foir.dev/graphql. This provides type safety, flexible queries, and excellent developer tooling.

What are the different API key types?

API keys are scoped — you control which operations each key can access. A single deploy that serves several projects in one account can use a tenant key with a project allow-list instead. See API Keys and Authentication for details.

Can I use Foir with any frontend framework?

Yes. Foir is headless, so it works with any technology that can make HTTP requests — React, Next.js, Vue, Svelte, mobile apps, or server-side applications. The GraphQL API returns structured JSON that you render however you want.

Is there a rate limit?

Yes. The default is 10,000 requests per hour, configurable per API key. Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. See Errors & Rate Limits for details.

Localization

How many languages can I support?

There’s no hard limit on locales. Configure as many BCP-47 language codes as your project needs (e.g., en-US, fr-FR, de-DE, ja-JP).

What happens when a translation is missing?

Foir follows a fallback chain. If content isn’t available in the requested locale, it falls back to the configured fallback locale, then to the project’s default locale. The API response tells you which locale was actually used. See Localization for details.

Personalization

How do variants work?

Variants let you serve different content to different audiences. Create variants targeted to specific devices, markets, or customer segments. When content is resolved, Foir evaluates targeting rules and returns the best-matching variant.

What are segments?

Segments are named groups of customers defined by rules. Customers automatically enter or leave segments as their attributes change. Use segments to target content variants and understand your audience.

Can I run A/B tests?

Foir doesn’t include a built-in experiment framework with traffic splitting and goal tracking. You can serve different variants to different segments or contexts, but measuring results and choosing a winner is handled by your own analytics. See Analytics and Reporting for where each analytics need is met.

Analytics & Reporting

Does Foir do analytics?

Not as a product, and the honest answer depends on which analytics you mean. For pageviews and funnels, bring your own tool such as PostHog or Plausible and put it in your storefront; Foir never sees your traffic. For reporting over the data Foir holds, export it with foir export postgres and query a database you own. For pushing changes into another system, use lifecycle hooks. See Analytics and Reporting for the full breakdown.

Automation

Does Foir support webhooks?

Yes. Configure lifecycle hooks to trigger operations when records are created, updated, deleted, published, or unpublished — each delivered to an HTTP endpoint you control. See Webhooks for the delivery contract, authentication, and retry behavior.

What are operations?

Operations are registered HTTP endpoints that Foir can call on demand or in response to lifecycle events. They receive a standardized payload with the record data and context. Execute them via the admin, CLI, API, or have them triggered automatically by hooks.

Can I schedule recurring tasks?

Yes. Schedules let you run operations on a cron schedule — for example, syncing data every hour or generating reports daily.

Are lifecycle hooks reliable?

Async hooks are processed by a durable job queue with automatic retries. If a target endpoint is temporarily down, the job will retry. Hook execution errors are logged but don’t fail the parent operation — your data is always saved even if a hook fails.

Config System

What is the config system?

The config system lets you define your project’s models, operations, hooks, schedules, segments, and editor placements as code in a foir.config.ts file. Push changes to the platform with foir push.

When should I use config-as-code vs the admin?

Use the config system when you want version-controlled, reproducible project setup — especially for operations, hooks, and editor placements. Use the admin for day-to-day content management and one-off model changes.

Editor SDK

What is the Editor SDK?

The Editor SDK lets you build custom editor UIs that run as iframes inside the Foir admin. Use it to create specialized editing experiences — visual editors, integration dashboards, translation panels, and more.

What frameworks does the Editor SDK support?

The client SDK is a React library (@foir/sdk). The server SDK works with any Node.js framework (Hono, Express, etc.) or edge runtime (Cloudflare Workers, Deno).

Media

What file types can I upload?

Foir supports images (JPEG, PNG, WebP, AVIF, GIF, SVG), videos (MP4, WebM, QuickTime), audio (MP3, WAV, OGG), documents (PDF, JSON, CSV), and fonts (WOFF, WOFF2). See Media & Files for the full list.

Can I transform images on the fly?

Yes. The platform emits image URLs with an opaque ?t= token that encodes the size preset and any per-usage crop and focal point. Set the focal point and per-usage crop in the editor; the platform mints the URL automatically. See Image Transformations for the URL format.

AI & Search

How does semantic search work?

Foir generates vector embeddings for your content using AI models. When you search, queries are matched by meaning rather than exact keywords. Searching for “winter clothing” finds results about “cold weather apparel” even without those exact words.

Do I need to set up anything for AI features?

Enable embeddings per model in the admin, then use the per-model search<Model>s query (or the generic searchRecords) to find content by meaning. See AI & Search for details.

Collaboration

Can my team comment on content?

Yes. The Notes & Comments system lets team members attach notes to any record, reply in threads, @mention colleagues, and resolve discussions.

How do notifications work?

Every user has a personal notification inbox. You’re notified when background jobs complete, when you’re @mentioned in notes, when someone replies to your notes, and for system events.

Infrastructure

How is data isolated between projects?

Isolation is enforced in the database, not just by the API. Every project’s records sit behind Postgres Row-Level Security, so a request can only ever reach the project it’s authorized for — a missing filter in application code can’t cross that boundary. API keys are scoped to a single project (or, for a tenant key, an explicit allow-list of projects). See Authorization & Access for the full model.

Support

How do I get help?

• Check this documentation
• Contact support through the admin panel