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

> Explore the Open-SEO API with this guide to its endpoints and integration. Connect to health checks, authentication, OAuth, and webhook processing easily.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/src/routes/api/health.ts) provides service status monitoring.

**Response format:**
- Healthy: `{ status: "ok" }`
- Degraded: `{ status: "issues", ... }`

```javascript
// 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

```javascript
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`](https://github.com/every-app/open-seo/blob/main/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:**

```javascript
// 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`](https://github.com/every-app/open-seo/blob/main/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

```javascript
// 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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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.