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

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 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 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. 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, 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:

• 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 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

// 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"] 
  }),
});

// 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" 
  }),
});

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}