# Open-SEO API Endpoints: Complete Reference for Developers

> Explore the Open-SEO API endpoints. Access six public API endpoints built with TanStack React Router for seamless integration into your applications. Complete developer reference available.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/routes/api/health.ts) |

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

```ts
// 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.

```ts
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/routes/api/gsc/oauth/callback.ts)** — OAuth completion handler for GSC integration
- **[`web/src/routes/api/subscribe.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/subscribe.ts)** — Subscription management (web workspace)
- **[`web/src/routes/api/event.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.