Getting Started

Get up and running with Foir in a few minutes.

Prerequisites

• A Foir account with access to a project
• Node.js 18+ installed

Step 1: Create an API Key

1. Log in to the Foir admin
2. Go to API Keys
3. Click Create API Key
4. Configure:
   • Name: give it a descriptive name (e.g., “Frontend”, “Backend”)
   • Type: Public for client-side use, Secret for server-side
   • Mode: Test for development, Live for production
5. Click Create
6. Copy the key — it is only shown once

Add it to your environment:

# .env.local
FOIR_API_KEY=pk_test_abc123...
FOIR_API_URL=https://api.foir.io

See API Keys for details on key types, scopes, and security.

Step 2: Install the CLI

npm install -g @eide/foir-cli

Or use it without installing:

npx @eide/foir-cli login

Step 3: Authenticate and Select a Project

# Login to Foir (opens browser for OAuth)
foir login
 
# Select your project
foir select-project

For CI/CD or headless environments, use an API key instead:

export FOIR_API_KEY=sk_live_...

See CLI Overview for more on authentication and project profiles.

Step 4: Fetch Content

Query the GraphQL API to fetch your data. The schema is generated from your project’s models — each model becomes a queryable type.

const response = await fetch('https://api.foir.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.FOIR_API_KEY,
  },
  body: JSON.stringify({
    query: `
      query GetPage($naturalKey: String!) {
        page(naturalKey: $naturalKey) {
          _id
          title
          body
        }
      }
    `,
    variables: { naturalKey: 'home' },
  }),
});
 
const { data } = await response.json();
console.log(data.page.title);

See GraphQL API for the full query and mutation reference.

Step 5: Create Content

1. Open a model in the admin (e.g., Pages)
2. Click Create
3. Fill in the fields
4. Click Publish
5. Query it from your application

Step 6: Generate Types (Optional)

If you’re using TypeScript, generate typed queries and mutations from your project’s schema:

foir pull

Configure output paths and targets in foir.config.ts:

import { defineConfig } from '@eide/foir-cli/config';
 
export default defineConfig({
  pull: {
    output: {
      types: './src/generated/types',
      documents: './src/generated/documents',
    },
    targets: ['react'],
  },
});

See Code Generation for the full configuration reference.

Next Steps

Learn the Features

• Models — How data is structured
• Records — Creating, versioning, and publishing data
• Field Types — Available field types
• Variants — Serve different content to different audiences

Automate

• Operations — Register HTTP endpoints for custom logic
• Lifecycle Hooks — Trigger actions when data changes
• Schedules — Run operations on a cron schedule

Define as Code

• Config System — Define models, operations, and hooks in foir.config.ts
• Editor SDK — Build custom editor UIs

Common Issues

”API key required”

Make sure you are passing the x-api-key header in your requests.

”Record not found”

1. Check the record is published in the admin
2. Verify the naturalKey matches the record’s natural key
3. If using preview mode, pass preview: true in your query

Manage content from the terminal

foir records list page
foir records get home --model-key page