API Overview

The Foir API is a GraphQL-first platform for building headless applications. It provides a single endpoint for querying content, managing records, uploading media, authenticating customers, and executing custom operations.

Base URL

All API requests are made against:

https://api.foir.io

Endpoints

GraphQL as Primary Interface

GraphQL is the primary interface for interacting with Foir. Your project’s schema is generated from your models, so every model you define becomes directly queryable and mutable through the API.

Benefits of GraphQL for content delivery:

• Request exactly what you need — no over-fetching or under-fetching
• Single request — fetch related records, resolved content, and metadata in one query
• Strongly typed — your schema reflects your models, with full type safety
• Introspectable — explore the API with GraphiQL or any GraphQL client

GraphiQL Explorer

Foir provides an interactive GraphiQL interface at:

https://api.foir.io/graphiql

Use it to explore your schema, test queries, and view documentation for all available types and fields. Configure your API key in the headers panel.

Quick Start

1. Get an API Key

Create an API key in the Foir dashboard under Settings > API Keys. For getting started, a public live key (pk_live_) is sufficient for read-only access.

2. Fetch Content with curl

curl -X POST https://api.foir.io/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_api_key" \
  -d '{
    "query": "{ recordByKey(modelKey: \"page\", naturalKey: \"homepage\") { id naturalKey resolved(locale: \"en-US\") { content } } }"
  }'

3. Fetch Content with JavaScript

async function fetchPage(slug) {
  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($slug: String!) {
          recordByKey(modelKey: "page", naturalKey: $slug) {
            id
            naturalKey
            resolved(locale: "en-US") {
              content
            }
          }
        }
      `,
      variables: { slug },
    }),
  });
 
  const { data, errors } = await response.json();
  if (errors) throw new Error(errors[0].message);
  return data.recordByKey;
}

4. Use with Apollo Client

import { ApolloClient, InMemoryCache, createHttpLink } from "@apollo/client";
 
const client = new ApolloClient({
  link: createHttpLink({
    uri: "https://api.foir.io/graphql",
    headers: {
      "x-api-key": process.env.FOIR_API_KEY,
    },
  }),
  cache: new InMemoryCache(),
});

Authentication Summary

All API requests require an API key passed via the x-api-key header. There are four key types:

For customer-facing features, combine an API key with a customer JWT in the Authorization header.

See Authentication for full details on scopes, security, and customer auth.

Rate Limiting

API requests are rate-limited per API key. The default limit is 10,000 requests per hour. Rate limit status is returned in response headers:

See Errors and Rate Limits for details on error handling and query complexity limits.

What’s Next

• Authentication — API keys, scopes, customer JWT, and security
• GraphQL API — Records, filtering, mutations, operations, search, and schemas
• Media API — File upload, image transformations, and media management
• Real-time and Subscriptions — WebSocket subscriptions and Server-Sent Events
• Errors and Rate Limits — Error codes, rate limiting, and query complexity