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

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

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:

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

Authenticate a user:

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 and event tracking in 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.

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