Open-SEO API: Complete Guide to Available Endpoints and Integration Methods

Yes, Open-SEO provides a built-in HTTP API implemented as file-based routes using @tanstack/react-router, with endpoints for health checks, authentication, OAuth callbacks, and webhook processing.

The Open-SEO platform includes a self-hosted API surface that runs alongside its Remix-style front end. This article explores every available endpoint, their implementation details, and practical integration patterns using real code from the every-app/open-seo repository.

How the Open-SEO API Is Architected

Open-SEO uses TanStack Router's file-based routing to expose HTTP endpoints. Each file under src/routes/api/ automatically maps to a URL path through createFileRoute("<path>") declarations.

This design choice means:

• No separate API server process is required
• Routes are co-located with front-end code but return Response.json(...) instead of React components
• Adding new endpoints requires only creating a new file in the src/routes/api/ directory

All API responses follow a consistent JSON format, with the Content-Type: application/json header set automatically by the framework.

Core Open-SEO API Endpoints

Health Check: /api/health

The health endpoint in src/routes/api/health.ts provides service status monitoring.

Response format:

• Healthy: { status: "ok" }
• Degraded: { status: "issues", ... }

// Node.js/Fetch example
fetch('https://your-open-seo-instance.com/api/health')
  .then(r => r.json())
  .then(data => console.log('Open-SEO status:', data.status));

Use this endpoint for load balancer health probes, uptime monitoring, or startup readiness checks.

Authentication: /api/auth/*

The dynamic route src/routes/api/auth/$.ts handles all identity flows:

• Login/logout — Session creation and destruction
• API key validation — Programmatic access authentication
• Delegated login flows — Third-party authentication handoffs

async function login(email, password) {
  const resp = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });
  const data = await resp.json();
  if (data.success) {
    // Session cookie is set by the server
    console.log('Logged in!');
  }
}

The $.ts filename pattern creates a catch-all route that matches any subpath under /api/auth/.

Google Services Integration Endpoints

Google Search Console OAuth: /api/gsc/oauth/callback

File: src/routes/api/gsc/oauth/callback.ts

Handles the OAuth 2.0 callback after a user authorizes GSC access. Exchanges the authorization code for access tokens and stores credentials for subsequent API calls.

Initiating the flow:

// Redirect users to start GSC connection
window.location.href = '/api/gsc/oauth/callback?redirect_uri=' +
  encodeURIComponent('https://your-open-seo-instance.com/dashboard');

Google Analytics 4 OAuth: /api/ga4/oauth/callback

File: src/routes/api/ga4/oauth/callback.ts

Mirrors the GSC implementation for GA4 property access. Both endpoints share identical response patterns but maintain separate token storage to scope permissions appropriately.

Webhook Processing: /api/autumn/*

File: src/routes/api/autumn/$.ts

The "Autumn" endpoint receives background job completion events from Open-SEO's internal data pipeline. This includes:

• SEO audit job completions
• Crawl result processing
• Scheduled report generation

// Server-side handler example (Next.js App Router style)
export async function POST(req) {
  const payload = await req.json();
  // Process webhook payload — update UI, trigger notifications, etc.
  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

The catch-all $.ts route allows Autumn to version its webhook paths without requiring Open-SEO updates.

Self-Hosting the Open-SEO API

A key advantage of this architecture: the API requires no separate deployment. The same Node.js process serving the React front end handles API requests, simplifying:

• Infrastructure management
• Environment variable sharing
• Session cookie domain alignment

For production deployments, place Open-SEO behind a reverse proxy (nginx, Caddy, or cloud load balancer) and configure the health endpoint as your availability probe.

Extending the Open-SEO API

To add custom endpoints, create a new file under src/routes/api/ following the TanStack Router convention:

// src/routes/api/custom-feature.ts
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/custom-feature')({
  loader: async () => {
    // Your business logic
    return Response.json({ custom: 'data' })
  },
})

The framework automatically registers this at /api/custom-feature on the next build.

Summary

• Core health endpoint at src/routes/api/health.ts returns JSON status for monitoring
• Authentication flows consolidated in src/routes/api/auth/$.ts with session and API key support
• Google OAuth callbacks at dedicated paths for GSC (/api/gsc/oauth/callback) and GA4 (/api/ga4/oauth/callback)
• Autumn webhook processor at src/routes/api/autumn/$.ts handles async job notifications
• File-based routing via @tanstack/react-router eliminates API server complexity
• Self-host ready — single deployable unit with no microservice overhead

Frequently Asked Questions

Is the Open-SEO API RESTful?

Yes, though it uses TanStack Router's conventions rather than traditional REST frameworks. Endpoints accept standard HTTP methods (GET, POST) and return JSON responses. The file-based routing in src/routes/api/ maps directly to URL paths, producing a predictable API surface that behaves like conventional REST.

Can I use the Open-SEO API without the front-end interface?

Absolutely. The API endpoints are publicly accessible HTTP resources. Any client—curl, Python requests, a custom dashboard—can authenticate via the /api/auth/* endpoints and consume data programmatically. The same-session cookies used by the React UI also work for API clients running in browser contexts.

How does Open-SEO API authentication work?

The src/routes/api/auth/$.ts route supports multiple mechanisms: password-based sessions (with HTTP-only cookies), API key validation in the Authorization header, and delegated flows for SSO providers. All methods converge on the same session abstraction stored server-side.

What is the Autumn webhook used for?

Autumn is Open-SEO's internal job queue. The /api/autumn/* endpoint receives completion notifications when background tasks—like site crawls or report generation—finish. This enables real-time UI updates without polling and decouples heavy processing from the request/response cycle.

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