Public API Overview

Foir provides a powerful GraphQL API for building headless applications. The Public API is designed for frontend applications and external integrations.

API Endpoints

Environment	Endpoint
Production	`https://api.foir.io/graphql/public`
Staging	`https://api-staging.foir.io/graphql/public`

API Capabilities

The Public API provides access to:

Routing - Resolve URL paths to content with variant selection
Entities - Query and manage content records
Customer Auth - Customer authentication flows
Workflows - Execute custom workflows via API
Schemas - Retrieve project schemas for code generation

Quick Start

1. Get an API Key

API keys are created in the Foir admin dashboard under Settings → API Keys. There are three types:

Key Type	Prefix	Use Case
Production	`pk_live_`	Live frontend applications
Preview	`pk_preview_`	Preview unpublished content
Development	`pk_dev_`	Development and testing

2. Make Your First Request


query GetHomePage {
  resolveRoute(path: "/", locale: "en-US") {
    record {
      id
      modelKey
      naturalKey
    }
    content {
      fields {
        key
        type
        value
      }
    }
  }
}

3. Include Authentication


curl -X POST https://api.foir.io/graphql/public \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_api_key" \
  -d '{"query": "{ resolveRoute(path: \"/\") { record { id } } }"}'

GraphQL Clients

Apollo Client (React)


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

Fetch API


async function foirQuery(query: string, variables?: Record<string, any>) {
  const response = await fetch('https://api.foir.io/graphql/public', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.FOIR_API_KEY!,
    },
    body: JSON.stringify({ query, variables }),
  });
  return response.json();
}

Rate Limits

API requests are subject to rate limiting:

Tier	Requests/Minute	Burst
Free	100	20
Pro	1,000	100
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit - Maximum requests per window
X-RateLimit-Remaining - Remaining requests
X-RateLimit-Reset - Unix timestamp when limit resets

Error Handling

GraphQL errors are returned in the standard format:


{
  "errors": [
    {
      "message": "Not found",
      "extensions": {
        "code": "NOT_FOUND",
        "path": "/products/invalid-handle"
      }
    }
  ],
  "data": null
}

Common error codes:

Code	Description
`UNAUTHENTICATED`	Missing or invalid API key
`FORBIDDEN`	API key lacks required scope
`NOT_FOUND`	Resource not found
`RATE_LIMITED`	Too many requests
`VALIDATION_ERROR`	Invalid input