Frequently Asked Questions

Common questions about using Foir.

General

What is Foir?

Foir is a headless content and data platform for building applications. It provides flexible data modeling, a GraphQL API, content personalization, automation, and AI-powered search.

Who is Foir for?

Foir is built for development teams who need:

• Flexible data modeling with typed fields and configurable capabilities
• A GraphQL API for querying and mutating data
• Multi-language content with locale fallbacks
• Audience personalization with variants, segments, and A/B testing
• Built-in semantic search with vector embeddings
• Workflow automation with operations, hooks, and schedules
• Config-as-code for defining project resources

How does Foir differ from other headless CMSs?

Foir combines content management with built-in personalization, experimentation, and AI capabilities. Instead of integrating multiple services, you get variant targeting, customer segmentation, A/B testing, semantic search, and lifecycle automation in a single platform. The config system lets you define your entire project as code.

Content & Data

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

All data in Foir uses the same models and records system. The difference is in the model’s capabilities — you choose which to enable: versioning, publishing, variants, and inline mode. 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.io/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. See API Keys 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, run experiments, and understand your audience.

Can I run A/B tests?

Yes. Create experiments with a control group and one or more treatment variants, set traffic allocation, and start the experiment. Foir uses deterministic assignment so customers always see the same variant. When you’ve gathered enough data, declare a winner and apply it.

Automation

Does Foir support webhooks?

Yes. Configure lifecycle hooks to trigger operations when records are created, updated, deleted, published, or unpublished. Operations can call any HTTP endpoint — Slack, Zapier, your own APIs, or any service.

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 (@eide/foir-editor-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 semanticSearch query 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?

Each project’s data is completely isolated. API keys are scoped to a single project and can only access that project’s data.

Support

How do I get help?

• Check this documentation
• Contact support through the admin panel