# Open-SEO API Endpoints and Server Functions: Complete Reference Guide

> Explore Open-SEO API endpoints and server functions for keyword research, rank tracking, site audits, and billing. Access comprehensive HTTP POST functionalities with Zod validation.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: api-reference
- Published: 2026-06-28

---

**Open-SEO exposes its functionality through HTTP POST server functions organized under `src/serverFunctions/`, covering keyword research, rank tracking, site audits, and billing management with Zod-validated JSON payloads.**

The every-app/open-seo repository implements its API layer using TanStack React Start's `createServerFn` utility. Each server function acts as an authenticated HTTP POST endpoint, grouped by SEO domain logic in dedicated TypeScript files that enforce validation through Zod schemas and middleware.

## How the Open-SEO API Architecture Works

All API endpoints in Open-SEO are server functions wrapped with `createServerFn` from `@tanstack/react-start`. These functions accept **JSON payloads** and return JSON responses. The architecture relies on a middleware stack defined in [`src/serverFunctions/middleware.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/middleware.ts) that handles authentication, error handling, and project context scoping.

Key middleware functions include:
- `globalServerFunctionMiddleware` – Wraps all server functions with error handling
- `requireAuthenticatedContext` – Enforces user authentication via `ensureUserMiddleware`
- `requireProjectContext` – Validates project access permissions

## Keyword Research Endpoints (keywords.ts)

The [`src/serverFunctions/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/keywords.ts) file manages keyword discovery and storage. These endpoints handle everything from initial research to tag management:

- `researchKeywords` – Performs initial keyword research for a domain
- `saveKeywords` – Stores selected keywords to the database
- `getSavedKeywords` – Retrieves stored keywords with filtering
- `exportSavedKeywords` – Exports keyword lists for external use
- `updateSavedKeywordTags` / `updateSavedKeywordTag` / `deleteSavedKeywordTag` – Manages keyword categorization
- `removeSavedKeywords` – Deletes keywords from storage
- `getSerpAnalysis` – Fetches Search Engine Results Page analysis data

## Project Management Endpoints (projects.ts)

Project lifecycle and access control reside in [`src/serverFunctions/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/projects.ts). These functions provide multi-tenant project isolation:

- `getProjects` – Lists active projects for the authenticated user
- `createProject` – Initializes a new SEO project
- `updateProject` – Modifies project metadata
- `archiveProject` – Soft-deletes projects while preserving data
- `getArchivedProjects` – Lists archived projects for restoration
- `restoreProject` – Recovers archived projects
- `getProjectAccess` – Validates user permissions for project resources

## Rank Tracking Endpoints (rank-tracking.ts)

The most extensive API surface lives in [`src/serverFunctions/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/rank-tracking.ts), handling SERP position monitoring:

**Configuration Management:**
- `getRankTrackingConfigs` – Retrieves tracking setups
- `getRankTrackingConfigSummaries` – Gets high-level config overviews
- `createRankTrackingConfig` / `updateRankTrackingConfig` – CRUD operations for tracking campaigns

**Execution and Data Retrieval:**
- `triggerRankCheck` – Initiates a new rank checking run
- `getLatestRankResults` – Fetches current position data
- `getLatestRankRun` – Retrieves the most recent check execution
- `estimateRankCheckCost` – Calculates API credit consumption before execution

**Keyword Management:**
- `addTrackingKeywords` / `removeTrackingKeywords` – Modifies keywords under monitoring
- `refreshTrackingKeywordMetrics` – Updates search volume and difficulty data

**Analytics:**
- `getRankKeywordHistory` – Historical position data for specific keywords
- `getRankConfigTrend` – Trend analysis across tracking configurations
- `getRankPositionMatrix` – Comparative position visualization data

## Domain Analysis Endpoints (domain.ts)

Domain-level SEO metrics are handled in [`src/serverFunctions/domain.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/domain.ts):

- `getDomainOverview` – Retrieves authority scores, traffic estimates, and backlink counts
- `getDomainHistory` – Provides time-series data for domain metrics

## Google Search Console Integration (gsc.ts)

The [`src/serverFunctions/gsc.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/gsc.ts) file bridges Open-SEO with Google's official API:

- `getGscData` – Imports search analytics (clicks, impressions, CTR)
- `addGscProperty` – Connects new GSC properties to projects
- `removeGscProperty` – Disconnects GSC integrations

## Lighthouse Performance Audits (lighthouse.ts)

Core Web Vitals and performance data reside in [`src/serverFunctions/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/lighthouse.ts):

- `runLighthouse` – Queues a new Lighthouse audit for a URL
- `getLighthouseResult` – Retrieves completed audit scores (Performance, Accessibility, SEO, Best Practices)

## Backlink Analysis (backlinks.ts)

Link profile management functions in [`src/serverFunctions/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts):

- `getBacklinks` – Retrieves referring domain data
- `addBacklink` – Manually adds backlink entries
- `removeBacklink` – Deletes backlink records
- `backlinksAccess` – Authorization wrapper for backlink data

## Site Audit Workflow (audit.ts)

Technical SEO scanning endpoints in [`src/serverFunctions/audit.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/audit.ts):

- `runSiteAudit` – Triggers crawler initialization for comprehensive site analysis
- `getSiteAuditStatus` – Polls crawl progress and completion status

## AI-Driven Search (ai-search.ts)

Artificial intelligence features in [`src/serverFunctions/ai-search.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/ai-search.ts):

- `aiSearch` – Generates SEO recommendations using AI models
- `aiSearchAccess` – Validates subscription tier for AI feature access

## Billing and Subscription (billing.ts)

Payment and plan enforcement in [`src/serverFunctions/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/billing.ts):

- `handleAutumnWebhookRequest` – Processes subscription events from Autumn
- `billing` – Retrieves current subscription status
- `customerHasPaidPlan` – Runtime check enforcing paid-tier restrictions on specific actions

## Real-Time Onboarding Chat (onboardingChat.ts)

Interactive onboarding uses Cloudflare Workers Durable Objects via [`src/serverFunctions/onboardingChat.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/onboardingChat.ts):

- `onboardingChat` – Manages WebSocket connections for real-time setup assistance

## Practical API Call Examples

All endpoints accept POST requests with JSON bodies. Here are implementation examples:

```typescript
// Trigger rank checking for specific keywords
await fetch("/api/rank-tracking/triggerRankCheck", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ 
    configId: "cfg_123", 
    keywordIds: ["kw_1", "kw_2"] 
  }),
});

```

```typescript
// Research keywords for a domain
await fetch("/api/keywords/researchKeywords", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ 
    domain: "example.com", 
    language: "en", 
    location: "US" 
  }),
});

```

```typescript
// Create a new SEO project
await fetch("/api/projects/createProject", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "My New Project" }),
});

```

## Summary

- Open-SEO organizes its API into **domain-specific server functions** under `src/serverFunctions/` using TanStack React Start's `createServerFn` pattern.
- All endpoints use **HTTP POST** with Zod-validated JSON payloads and require authentication via the middleware stack.
- **Keyword research**, **rank tracking**, and **project management** constitute the largest API surface areas.
- **Billing middleware** enforces subscription tiers on paid features like AI search and extended rank tracking.
- Real-time capabilities like the onboarding chat leverage Cloudflare Durable Objects separate from the standard server function pattern.

## Frequently Asked Questions

### What authentication method does Open-SEO use for its API endpoints?

Open-SEO uses middleware-based authentication defined in [`src/serverFunctions/middleware.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/middleware.ts). The `requireAuthenticatedContext` wrapper enforces user sessions via `ensureUserMiddleware`, rejecting unauthenticated requests before they reach business logic. Additional project-level checks via `requireProjectContext` ensure users can only access resources within their authorized projects.

### How does Open-SEO validate API request payloads?

All server functions use **Zod schemas** to validate incoming JSON payloads at runtime. This ensures type safety and data integrity before processing. Invalid payloads trigger validation errors handled by the `globalServerFunctionMiddleware`, which provides consistent error formatting across the API surface.

### Can I use Open-SEO's rank tracking API without a paid subscription?

Certain functions like `estimateRankCheckCost` and configuration management may work on free tiers, but `triggerRankCheck` and data retrieval functions enforce paid plans. The `customerHasPaidPlan` check in [`src/serverFunctions/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/billing.ts) restricts high-cost operations (such as large-scale rank checking) to subscribed users, returning permission errors for unpaid accounts attempting premium actions.

### What technology powers the real-time onboarding chat in Open-SEO?

The onboarding chat functionality in [`src/serverFunctions/onboardingChat.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/onboardingChat.ts) uses **Cloudflare Workers Durable Objects** rather than standard server functions. This allows persistent WebSocket connections for real-time messaging during user setup, distinct from the HTTP POST pattern used by the rest of the API.