Is There a Public API for OpenSEO? Complete Endpoint Reference

Yes, OpenSEO provides a public API with REST endpoints under /api/* and a JSON‑RPC MCP interface at /mcp, supporting health monitoring, Google Search Console integration, and AI agent workflows.

The every-app/open-seo repository exposes a comprehensive public API for OpenSEO designed for external consumption. Whether you are building custom integrations, automating SEO workflows, or connecting AI agents, the API offers programmatic access to core functionality through multiple authenticated and unauthenticated surfaces.

Core API Surfaces

OpenSEO ships several distinct HTTP‑based API surfaces, each serving different integration patterns. These endpoints are defined across the src/routes/api/ directory and automatically generated from server functions.

Health and Diagnostic Endpoints

The simplest entry point is the health check endpoint, which requires no authentication. This returns service status and, in self‑hosted deployments, configuration diagnostics.

• Endpoint: GET /api/health
• Authentication: None required
• Source: src/routes/api/health.ts

OAuth and Authentication Helpers

OpenSEO provides dedicated routes for Google Search Console (GSC) OAuth flows and token exchange. These handle the OAuth callback, self‑hosted token exchange, and authentication initialization.

• Routes: /api/gsc/oauth/*, /api/auth/*, /api/autumn/*
• Source files:
  • src/routes/api/gsc/oauth/callback.ts (GSC OAuth callback handling)
  • src/routes/api/auth/$.ts (generic auth routes)
  • src/routes/api/autumn/$.ts (Autumn billing webhooks)

MCP Tool Server (Model‑Context‑Protocol)

The MCP tool server exposes SEO functionality via a JSON‑RPC‑style endpoint, enabling AI agents (such as Claude, OpenClaw, and Hermes) to invoke tools programmatically.

• Endpoint: POST /mcp
• Protocol: JSON‑RPC 2.0
• Authentication: MCP OAuth flow via /api/auth/oauth2/*
• Source: Route constant defined in src/server/mcp/context.ts; tool registration in src/server/mcp/server.ts

Available tools include keyword research, rank tracking, site audits, and backlink analysis. The server registers all tools in src/server/mcp/server.ts, while the route configuration resides in src/server/mcp/context.ts.

TanStack Server Functions

Every TanStack Server Function exported from src/serverFunctions/* is automatically exposed as a public API endpoint. The router maps these to /api/* paths via the generated route tree.

• Pattern: /api/* (auto‑generated from function names)
• Key functions: listGscSites, setGscSite, searchPerformance
• Source: Route mappings in src/routeTree.gen.ts; implementations in src/serverFunctions/gsc.ts

These functions serve as the low‑level building blocks for both the UI and MCP tools, accepting project‑scoped JWTs or session cookies for authentication.

Authentication Requirements

Access to the public API varies by endpoint:

• No authentication: Health checks (/api/health)
• OAuth tokens: MCP tool invocations (/mcp)
• Project‑scoped JWTs or session cookies: TanStack Server Functions (/api/*)

The authentication system is shared between the API and the web UI, ensuring consistent security across all surfaces.

Practical Code Examples

Ping the Health Endpoint

Verify service availability without credentials:

fetch('https://app.openseo.so/api/health')
  .then(r => r.json())
  .then(console.log);
// → { status: "ok", ... }  (hosted) or diagnostic object (self‑hosted)

Call an MCP Tool via JSON‑RPC

Invoke the list_projects tool using the MCP endpoint:

const payload = {
  jsonrpc: "2.0",
  id: "1",
  method: "list_projects",
  params: {}               // no params for this tool
};

fetch('https://app.openseo.so/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // OAuth token obtained via /api/auth/oauth2/authorize
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify(payload)
})
  .then(r => r.json())
  .then(console.log);
// → { jsonrpc: "2.0", id: "1", result: { projects: [...] } }

Invoke TanStack Server Functions Directly

Call listGscSites via its auto‑generated endpoint:

// The route is automatically generated as /api/gsc/sites (POST)
const body = { projectId: "proj_123" };

fetch('https://app.openseo.so/api/gsc/sites', {
  method: 'POST',
  credentials: 'include', // sends session cookie for auth
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body)
})
  .then(r => r.json())
  .then(console.log);
// → { accounts: [{ accountId, sites: [{ siteUrl, isSelected, … }] }] }

Trigger Self‑Hosted GSC OAuth

Initiate the OAuth flow for self‑hosted installations:

// 1️⃣ Get the URL to which the user should be sent
fetch('https://app.openseo.so/api/gsc/oauth/start-selfhosted', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ callbackURL: 'https://myapp.com/callback' })
})
  .then(r => r.json())
  .then(({ url }) => window.location.href = url);

Summary

OpenSEO offers a robust public API with multiple integration paths:

• Unauthenticated health checks via GET /api/health for monitoring
• REST‑style endpoints auto‑generated from TanStack Server Functions under /api/*
• JSON‑RPC MCP interface at /mcp for AI agent integration
• OAuth routes for Google Search Console authentication and token management
• Type‑safe request schemas defined via Zod in each route handler

All endpoints are versioned through the route definitions in src/routeTree.gen.ts and protected by the same authentication mechanisms used by the OpenSEO web interface.

Frequently Asked Questions

How do I authenticate with the OpenSEO public API?

Authentication depends on the endpoint. The health endpoint requires no credentials. MCP tool calls require an OAuth token obtained through /api/auth/oauth2/authorize. TanStack Server Functions accept either project‑scoped JWTs or session cookies via standard browser credentials.

What is the MCP endpoint used for?

The /mcp endpoint implements the Model‑Context‑Protocol, allowing AI agents to invoke SEO tools via JSON‑RPC. According to the source code in src/server/mcp/server.ts, this exposes methods for keyword research, rank tracking, site audits, and backlink analysis to compatible AI systems like Claude or OpenClaw.

Are the TanStack Server Functions stable for third‑party use?

Yes. As implemented in every-app/open-seo, these functions in src/serverFunctions/* are intentionally public. The createServerFn wrapper automatically generates stable /api/* routes (mapped in src/routeTree.gen.ts), and each function includes Zod‑defined request schemas for type safety.

Can I use the OpenSEO API without hosting the project myself?

Yes. The hosted version at app.openseo.so exposes the same public API surfaces as self‑hosted instances, including the health endpoint, MCP interface, and OAuth flows. Simply target the appropriate base URL for your deployment model.

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