# Main API Routes in Open-SEO: Complete Guide to the Every-App SEO Platform Endpoints

> Explore the five main API routes in Open-SEO, including health checks, OAuth callbacks for Google Search Console and GA4, plus dynamic routes for Autumn integration. Master Every-App SEO platform endpoints.

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

---

**Open-SEO defines five primary API routes using TanStack React Router's file-based routing system, including health checks, OAuth callbacks for Google Search Console and Google Analytics 4, plus dynamic routes for Autumn integration and authentication providers.**

Open-SEO is an open-source SEO platform built by **every-app** that exposes a clean REST API for health monitoring, third-party integrations, and OAuth authentication. This guide walks through each endpoint defined in the `src/routes/api/` directory, explains their implementation, and provides working code examples you can run against any Open-SEO instance.

## How Open-SEO Routes Are Structured

Unlike traditional Express or FastAPI servers, Open-SEO uses **TanStack React Router's file-based routing**. Each `.ts` file under `src/routes/api/` automatically maps to a URL path matching its directory structure. The [`routeTree.gen.ts`](https://github.com/every-app/open-seo/blob/main/routeTree.gen.ts) file (auto-generated at build time) registers these routes for server-side resolution.

Dynamic segments use the `$` filename convention. For example, `src/routes/api/autumn/$.ts` matches `/api/autumn/:slug` where `:slug` captures any path segment after `/api/autumn/`.

## GET /api/health — Service Health Check

The simplest route, located at **[`src/routes/api/health.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/health.ts)**, provides a lightweight liveness probe.

```typescript
// src/routes/api/health.ts
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/health')({
  loader: async () => {
    return { ok: true }
  },
})

```

This endpoint returns a static JSON payload with no external dependencies, making it ideal for load balancers, Kubernetes health probes, and uptime monitoring.

```bash
curl -s https://your-instance.com/api/health | jq

# Output: { "ok": true }

```

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

The **[`src/routes/api/gsc/oauth/callback.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/gsc/oauth/callback.ts)** file handles the OAuth 2.0 callback from Google Search Console. After a user authorizes Open-SEO to access their GSC data, Google redirects to this route with an authorization `code` query parameter.

The route implementation exchanges this code for an access token and stores it for subsequent API calls to the Google Search Console API. This enables Open-SEO to fetch search analytics, sitemap data, and indexing status on behalf of connected users.

```bash

# Example callback URL after user authorization

curl -s "https://your-instance.com/api/gsc/oauth/callback?code=4%2F0A...&state=xyz" | jq

```

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

Mirroring the GSC flow, **[`src/routes/api/ga4/oauth/callback.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/ga4/oauth/callback.ts)** handles OAuth callbacks for **Google Analytics 4**. This separate endpoint exists because GA4 and GSC use different OAuth scopes and token management requirements.

The route parses the authorization grant, exchanges it for GA4-specific credentials, and persists them for reporting features. Having distinct callback URLs prevents scope collisions and simplifies debugging authentication failures.

## Dynamic Routes with Path Parameters

Open-SEO implements two dynamic routes using the TanStack `$` splat convention:

### Autumn Integration: GET /api/autumn/:slug

The file **`src/routes/api/autumn/$.ts`** creates a catch-all route matching `/api/autumn/<any-segment>`. The "Autumn" integration appears to be a custom or partner service where `:slug` resolves to a project token, identifier, or configuration key.

```typescript
// Example client call with dynamic slug
const slug = 'my-project-token';

const response = await fetch(`https://your-instance.com/api/autumn/${slug}`);
const data = await response.json();

console.log('Autumn integration result:', data);

```

The route handler likely uses TanStack's `params.slug` to branch logic based on the specific identifier provided.

### Authentication Providers: GET /api/auth/:provider

The **`src/routes/api/auth/$.ts`** file implements a unified authentication entry point. The `:provider` segment selects which identity provider to invoke—common values include `github`, `google`, or other configured SSO sources.

This design centralizes auth initialization without requiring separate files per provider. The handler inspects `params.provider` and delegates to the appropriate OAuth or SAML flow.

```bash

# Initiate GitHub authentication

curl -s https://your-instance.com/api/auth/github

# Initiate Google authentication  

curl -s https://your-instance.com/api/auth/google

```

## Complete Route Reference Table

| URL Path | Source File | Purpose | Auth Required |
|----------|-------------|---------|---------------|
| `/api/health` | [`src/routes/api/health.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/health.ts) | Liveness probe | No |
| `/api/gsc/oauth/callback` | [`src/routes/api/gsc/oauth/callback.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/gsc/oauth/callback.ts) | GSC OAuth completion | No (receives token) |
| `/api/ga4/oauth/callback` | [`src/routes/api/ga4/oauth/callback.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/ga4/oauth/callback.ts) | GA4 OAuth completion | No (receives token) |
| `/api/autumn/:slug` | `src/routes/api/autumn/$.ts` | Dynamic Autumn integration | Varies by slug |
| `/api/auth/:provider` | `src/routes/api/auth/$.ts` | Provider-specific auth initiation | No |

## Working with the API Programmatically

Here's a complete TypeScript client showing all five endpoints:

```typescript
interface HealthResponse {
  ok: boolean;
}

class OpenSeoClient {
  private baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl.replace(/\/$/, '');
  }

  async health(): Promise<HealthResponse> {
    const res = await fetch(`${this.baseUrl}/api/health`);
    if (!res.ok) throw new Error(`Health check failed: ${res.status}`);
    return res.json();
  }

  async autumn<T = unknown>(slug: string): Promise<T> {
    const res = await fetch(`${this.baseUrl}/api/autumn/${encodeURIComponent(slug)}`);
    if (!res.ok) throw new Error(`Autumn request failed: ${res.status}`);
    return res.json();
  }

  getAuthUrl(provider: 'github' | 'google'): string {
    return `${this.baseUrl}/api/auth/${provider}`;
  }

  // GSC/GA4 callbacks are typically invoked by Google, not called directly
}

// Usage
const client = new OpenSeoClient('https://api.example.com');

const healthy = await client.health();
console.log('Service healthy:', healthy.ok);

const autumnData = await client.autumn('project-123');

```

## Summary

- **Five main API routes** power Open-SEO's external interface: health checks, GSC OAuth, GA4 OAuth, Autumn integration, and provider-based authentication.
- **File-based routing** via TanStack React Router eliminates manual route registration—files automatically map to URL paths.
- **`$.ts` files** create dynamic segments for extensible integrations like Autumn and multi-provider auth.
- **Zero health-check dependencies** make `/api/health` suitable for infrastructure monitoring without risk of cascading failures.

## Frequently Asked Questions

### How do I add a new API route to Open-SEO?

Create a new file under `src/routes/api/` following the directory conventions. Static paths use literal filenames ([`analytics.ts`](https://github.com/every-app/open-seo/blob/main/analytics.ts) → `/api/analytics`). Dynamic paths use `$` (`reports/$.ts` → `/api/reports/:id`). Run `npm run dev` or your build command to regenerate [`routeTree.gen.ts`](https://github.com/every-app/open-seo/blob/main/routeTree.gen.ts) with the new route.

### Why are GSC and GA4 OAuth callbacks separate routes instead of a unified handler?

Separate routes allow distinct error handling, token storage logic, and scope validation for each Google service. GSC and GA4 maintain different API contracts and permission models—unified handling would complicate debugging and increase the blast radius of authentication bugs.

### What authentication is required to call these API routes?

The health endpoint requires no authentication. OAuth callback routes receive bearer tokens from Google, not the caller. The Autumn and auth routes may enforce session or API key validation depending on the specific slug or provider configuration—check the implementation in `autumn/$.ts` and `auth/$.ts` for your deployment.

### Can I use Open-SEO's API routes from a server-side application?

Yes. All routes return JSON and accept standard HTTP methods. For server-to-server calls, instantiate `OpenSeoClient` with your instance URL. Note that OAuth callbacks expect specific query parameters from Google's authorization server—direct server calls to these endpoints without a valid `code` will fail.