# Where to Find the API Endpoints for OpenSEO: Complete Route Reference

> Find OpenSEO API endpoints easily. This reference details all public routes within the every-app/open-seo repository, guiding you to efficient API integration.

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

---

**OpenSEO exposes six public API endpoints through TanStack React Router file-based routes located in `src/routes/api` and `web/src/routes/api`, with each endpoint defined as a `Route` object that maps HTTP methods via `server.handlers`.**

The **every-app/open-seo** repository implements its server-side API using TanStack React Router's file-based routing convention. If you are looking for the **API endpoints for OpenSEO**, you will find them organized under specific directory hierarchies that automatically generate URL paths, where each file exports a configuration object declaring its supported HTTP verbs.

## Core API Routes in `src/routes/api`

The primary backend endpoints reside in the `src/routes/api` directory. Each file imports `createFileRoute` from **@tanstack/react-router** and exports a `Route` object containing a `server.handlers` map that binds HTTP methods to handler functions.

### Health Check Endpoint (`GET /api/health`)

The health check endpoint is implemented in [`src/routes/api/health.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/health.ts). This route returns the instance status and self-host configuration details, commonly used for Docker **HEALTHCHECK** directives and uptime monitoring.

### Authentication Endpoint (`POST /api/auth`)

Located at `src/routes/api/auth/$.ts`, this endpoint handles login flows and token exchange. It accepts a JSON payload with `email` and `password` fields and returns an authentication token along with user identification.

### DataForSEO Webhook Handler (`POST /api/autumn`)

The `src/routes/api/autumn/$.ts` file receives webhook callbacks from DataForSEO's "Autumn" service. This endpoint processes asynchronous usage callbacks and billing events from the SEO data provider.

### Google Search Console OAuth Callback (`GET /api/gsc/oauth/callback`)

Found in [`src/routes/api/gsc/oauth/callback.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/gsc/oauth/callback.ts), this route handles the OAuth redirect from Google after a user authorizes Search Console access. It completes the authentication flow and provisions the necessary tokens for GSC data access.

## Web Workspace API Routes (`web/src/routes/api`)

The `web` workspace contains additional endpoints primarily for client-side interactions and telemetry.

### Subscription Handler (`POST /api/subscribe`)

Defined in [`web/src/routes/api/subscribe.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/subscribe.ts), this endpoint manages newsletter signups and plan subscription requests from the frontend application.

### Event Ingestion (`POST /api/event`)

The [`web/src/routes/api/event.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/event.ts) file implements client-side telemetry collection. It ingests analytics events and diagnostic data from the OpenSEO web interface.

## How Route Files Define HTTP Handlers

Unlike traditional Express or FastAPI applications, OpenSEO uses TanStack React Router's convention where the exported `Route` object contains a `server.handlers` property. This map explicitly defines which HTTP verbs the route responds to, with each verb pointing to a handler function that processes the request and returns a standard web `Response`.

```typescript
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/health')({
  server: {
    handlers: {
      GET: async () => {
        return new Response(JSON.stringify({ status: 'ok' }), {
          headers: { 'Content-Type': 'application/json' }
        })
      }
    }
  }
})

```

## Example API Requests

When interacting with a self-hosted OpenSEO instance, use the following patterns to access these endpoints.

Check instance health:

```javascript
fetch('https://my-openseo-instance.com/api/health')
  .then(r => r.json())
  .then(console.log);
// Returns: { status: "ok", ...setupDetails }

```

Authenticate a user:

```javascript
await fetch('https://my-openseo-instance.com/api/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    email: 'you@example.com', 
    password: 'secret' 
  })
})
  .then(r => r.json())
  .then(console.log);
// Returns: { token: "...", userId: "..." }

```

Handle Google Search Console OAuth:

The `/api/gsc/oauth/callback` endpoint is accessed automatically by Google's OAuth redirect. Your application should redirect users to the authorization URL, and OpenSEO handles the callback at this route to complete the token exchange.

## Summary

- OpenSEO's **API endpoints for open-seo** are located in `src/routes/api` (core backend) and `web/src/routes/api` (web-specific).
- Each endpoint is a **TanStack React Router** file-based route created with `createFileRoute`.
- HTTP methods are declared explicitly in the `server.handlers` object exported by each route file.
- Key endpoints include health checks at `/api/health`, authentication at `/api/auth`, DataForSEO webhooks at `/api/autumn`, and Google Search Console OAuth callbacks at `/api/gsc/oauth/callback`.
- Subscription handling resides in [`web/src/routes/api/subscribe.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/subscribe.ts) and event tracking in [`web/src/routes/api/event.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/event.ts).

## Frequently Asked Questions

### What is the base path for all API endpoints in OpenSEO?

All API routes are prefixed with `/api` and are defined by their file location relative to the `src/routes` or `web/src/routes` directory. The file path after the `routes` directory determines the URL path, with dynamic segments using the `$` filename convention.

### How do I add a new API endpoint to OpenSEO?

Create a new file in `src/routes/api` using the `$.ts` naming convention for dynamic segments or standard names for static paths. Export a `Route` object using `createFileRoute` that includes a `server.handlers` map defining your HTTP methods (GET, POST, etc.) and handler functions that return Response objects.

### Where is the authentication logic implemented?

The authentication endpoint is implemented in `src/routes/api/auth/$.ts`. This file handles login requests by validating credentials and issuing authentication tokens, supporting both hosted and self-hosted deployment modes.

### Can I use these endpoints with the hosted version of OpenSEO?

Yes, these endpoints are available in both self-hosted and hosted versions of OpenSEO, though the base URL will differ. Self-hosted instances use your configured domain, while the hosted version uses the official OpenSEO API domain. The request and response formats remain identical across deployment types.