# Is There a Public API for OpenSEO? Complete Endpoint Reference

> Access the OpenSEO public API with REST endpoints and JSON-RPC MCP for health monitoring, Google Search Console, and AI agent workflows. Discover complete endpoint references.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts); tool registration in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts), while the route configuration resides in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts); implementations in [`src/serverFunctions/gsc.ts`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
// 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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.