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

API keys are created with the CLI (see Step 2 to install it):


foir api-keys create \
  --name "Frontend" \
  --scopes records:read

Name: a descriptive name (e.g., “Frontend”, “Backend”)
Scopes: comma-separated, e.g. records:read,records:write

There are two key types: Public (pk_) keys are embeddable in client-side code, while Secret (sk_) keys are for server-side use and are required for privileged scopes. The raw key is printed once on creation — copy it then, it cannot be retrieved later.

Add it to your environment:


# .env.local
FOIR_API_KEY=pk_abc123...
 
# The CLI talks to the control plane. FOIR_API_URL only configures the CLI
# (default: https://rpc.foir.io) — it is NOT the public data-plane API host,
# which is https://api.foir.dev.
FOIR_API_URL=https://rpc.foir.io

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

Step 2: Install the CLI


npm install -g @foir/cli

Or use it without installing:


npx @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 SSH sessions, containers, or CI where no local browser is available, use the device flow — approve on any device with a short code (auto-selected when no browser is detected):


foir login --device

Or, to authenticate without a local callback by pasting a one-time code back into the terminal:


foir login --no-browser

For unattended CI/CD, you can use an API key instead of logging in:


export FOIR_API_KEY=sk_...

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.dev/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

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

Step 6: Manage Your Config as Code (Optional)

Your models, operations, segments, schedules, and project settings can live in a versioned foir.config.ts and be reconciled with the CLI:


foir push   # apply foir.config.ts to the platform
foir pull   # export the platform's current config back to foir.config.ts

For typed queries in TypeScript, introspect your project’s schema (GET https://api.foir.dev/schema) or explore it in GraphiQL. See Config as Code for the full 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”

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

Manage content from the terminal


foir records list page
foir records get page home