Open-SEO API Endpoints: Complete Reference for Developers

Open-SEO exposes six public API endpoints under the /api path, built with TanStack React Router's file-based routing system in the src/routes/api directory.

The every-app/open-seo repository implements a lightweight, self-hostable SEO platform with a clearly structured server-side API. All endpoints follow a consistent pattern using createFileRoute from @tanstack/react-router, where the file path determines the route and the exported Route object declares HTTP methods via a server.handlers map.

---

How Open-SEO API Endpoints Are Structured

In src/routes/api/health.ts and sibling files, each endpoint exports a Route object created with createFileRoute. The HTTP method (e.g., GET, POST) maps to a handler function that processes the request and returns a standard Response.

This file-based approach means:

• The route path mirrors the file location after /api/
• Multiple HTTP methods can coexist in a single file
• Server logic remains co-located with route definitions

---

Complete List of Open-SEO API Endpoints

Health Check Endpoint

Attribute	Value
Method	GET
Path	/api/health
Source	src/routes/api/health.ts

Used by Docker HEALTHCHECK and self-hosting diagnostics. Returns instance status and configuration details when running outside hosted mode.

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

---

Authentication Endpoint

Attribute	Value
Method	POST
Path	/api/auth
Source	src/routes/api/auth/$.ts

Handles login and token exchange for both hosted and self-hosted deployments. Expects a JSON body with email and password fields.

// Authenticate and receive access token
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);
// → { token: "...", userId: "..."}

---

DataForSEO Webhook Endpoint

Attribute	Value
Method	POST
Path	/api/autumn
Source	src/routes/api/autumn/$.ts

Receives callback webhooks from DataForSEO's "Autumn" service. Processes usage data and billing events asynchronously.

---

Google Search Console OAuth Callback

Attribute	Value
Method	GET
Path	/api/gsc/oauth/callback
Source	src/routes/api/gsc/oauth/callback.ts

Completes the OAuth flow after user authorization. The handler exchanges the authorization code for access tokens and establishes GSC integration.

Users are typically redirected here automatically from Google's consent screen; direct API calls to this endpoint are rare in normal operation.

---

Subscription Endpoint

Attribute	Value
Method	POST
Path	/api/subscribe
Source	web/src/routes/api/subscribe.ts

Manages newsletter signups and plan subscription requests. Located in the web workspace rather than core src.

---

Event Ingestion Endpoint

Attribute	Value
Method	POST
Path	/api/event
Source	web/src/routes/api/event.ts

Collects client-side telemetry events. Accepts batched or single events for analytics processing.

---

Key Implementation Files for Open-SEO API Development

• src/routes/api/health.ts — Health check implementation with Docker integration
• src/routes/api/auth/$.ts — Authentication handler supporting dual deployment modes
• src/routes/api/autumn/$.ts — Third-party webhook processor for DataForSEO
• src/routes/api/gsc/oauth/callback.ts — OAuth completion handler for GSC integration
• web/src/routes/api/subscribe.ts — Subscription management (web workspace)
• web/src/routes/api/event.ts — Telemetry ingestion (web workspace)

---

Summary

• Open-SEO provides six documented API endpoints covering health, auth, webhooks, OAuth, subscriptions, and events
• All endpoints use TanStack React Router's createFileRoute pattern with server.handlers for HTTP method routing
• Self-hosted instances rely heavily on the /api/health endpoint for operational monitoring
• The $.ts filename convention (as in auth/$.ts) enables dynamic route segments in TanStack Router
• Webhook integrations (DataForSEO, Google) follow standard OAuth 2.0 and POST-callback patterns

---

Frequently Asked Questions

What authentication method does Open-SEO use?

Open-SEO uses email/password authentication exchanged for bearer tokens via the POST /api/auth endpoint. The src/routes/api/auth/$.ts file implements both hosted and self-hosted auth flows, returning a JSON response containing token and userId fields for subsequent authenticated requests.

How do I verify my self-hosted Open-SEO instance is running correctly?

Query the GET /api/health endpoint defined in src/routes/api/health.ts. This endpoint returns instance status and configuration diagnostics and is specifically designed for Docker HEALTHCHECK integration. A successful response includes { status: "ok" } along with deployment-specific details.

Can I extend Open-SEO with custom API endpoints?

Yes. Create a new file under src/routes/api/ using the createFileRoute helper from @tanstack/react-router. Export a Route object with a server.handlers map specifying your HTTP methods and handler functions. The route path automatically derives from your file location.

What is the DataForSEO "Autumn" webhook for?

The POST /api/autumn endpoint in src/routes/api/autumn/$.ts receives usage and billing callbacks from DataForSEO's Autumn service. This enables Open-SEO to track SEO data consumption costs and update user quotas in real-time without polling.

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