API Reference

Name: SeoAuto.ai
Brand: SeoAuto.ai

Complete reference for the AutoSEO REST API. All endpoints require a valid Bearer token unless stated otherwise. Base URL: https://panel.seoauto.ai

Overview

The AutoSEO PSEO Automation API lets you programmatically create websites (PSEOs), trigger AI-based content generation, track generation jobs, and manage your content pipeline. All endpoints live under the path prefix /pseo-endpoints, mounted on the Directus backend.

Base URL

https://panel.seoauto.ai

Auth

Bearer Token (JWT)

Format

JSON (REST)

Authentication

All API calls (except the health check) require a Directus user token passed as a Bearer header. Obtain a short-lived access token by logging in, or use a long-lived static token generated from your dashboard.

Option 1 — Login (short-lived JWT)

POSThttps://panel.seoauto.ai/auth/login

json — request body

{
  "email": "you@example.com",
  "password": "••••••••"
}

json — response

{
  "data": {
    "access_token": "eyJhbGciO...",
    "expires": 3600000,
    "refresh_token": "..."
  }
}

Option 2 — Static token (dashboard)

Go to Dashboard → API Key and generate a permanent static token. Use it directly as the Bearer value — no expiry to track.

Using the token

http header

Authorization: Bearer <your_access_token>

Health Check

GEThttps://panel.seoauto.ai/pseo-endpoints/

Returns the extension status and a list of available endpoints. No authentication required.

json — response 200

{
  "status": "ok",
  "extension": "pseo-automation",
  "version": "1.0.0",
  "timestamp": "2026-03-10T12:00:00.000Z",
  "endpoints": [
    "GET /",
    "POST /pseo",
    "POST /trigger/on-demand-generation",
    "POST /trigger/bulk-generation",
    "GET /generations/:id",
    "GET /generations?pseo_id=X",
    "POST /generate/main-json",
    "GET /fetch-sitemap?pseo_id=X"
  ]
}

Create Website

POSThttps://panel.seoauto.ai/pseo-endpoints/pseo

Creates a new PSEO (website entry) for the authenticated user. The PSEO record is the root entity that holds all content generation settings for a specific website.

Request Body

Field	Type	Required	Description
website_url	string	required	Full URL of the target website (e.g. https://example.com)
master_prompt	string	required	Instructions that guide the AI when generating content for this website
website_software	string	optional	CMS/platform identifier. Defaults to "wordpress"

json — request body

{
  "website_url": "https://example.com",
  "website_software": "wordpress",
  "master_prompt": "This website sells handmade leather bags targeting fashion-conscious adults in the US. Write SEO-friendly product content in English using a professional yet warm tone."
}

json — response 201

{
  "success": true,
  "message": "PSEO created successfully",
  "data": {
    "id": 42,
    "website_url": "https://example.com",
    "website_software": "wordpress",
    "directus_user_id": "uuid-...",
    "post_counts_total": 0
  },
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Start Generation (Test)

POSThttps://panel.seoauto.ai/pseo-endpoints/trigger/on-demand-generation

Starts a test on-demand content generation job for a PSEO. Limited to 1 page — for generating more pages use Bulk Generation. The job runs asynchronously; use the returned generation_id to poll the status. Tokens are deducted immediately at the token_per_page rate.

Test mode — max 1 page

On-demand generation is limited to 1 page and is intended for testing your setup. To generate multiple pages at once, use the Bulk Generation endpoint which uses Claude Batch API.

Request Body

Field	Type	Required	Description
pseo_id	number	required	ID of the PSEO (website) to generate content for
post_count	number	required	Number of pages to generate. Must be 1 (test limit)

json — request body

{
  "pseo_id": 42,
  "post_count": 1
}

json — response 202

{
  "success": true,
  "message": "Generation started in background",
  "generation_id": 7,
  "status": "pending",
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Concurrent generation limit

Only one active generation per PSEO is allowed at a time. If a job with status pending or running already exists, the request will return 409 Conflict.

Bulk Generation

POSThttps://panel.seoauto.ai/pseo-endpoints/trigger/bulk-generation

Starts a bulk AI content generation job using Claude Batch API. Supports any number of pages in a single request. The job runs asynchronously in the background — use the returned generation_id to poll the status. Tokens are deducted immediately at the token_per_batch_page rate.

Request Body

Field	Type	Required	Description
pseo_id	number	required	ID of the PSEO (website) to generate content for
post_count	number	required	Number of pages to generate (positive integer, no upper limit)

json — request body

{
  "pseo_id": 42,
  "post_count": 100
}

json — response 202

{
  "success": true,
  "message": "Bulk generation started in background",
  "generation_id": 12,
  "status": "pending",
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Concurrent generation limit

Only one active generation per PSEO is allowed at a time. If a job with status pending or running already exists, the request will return 409 Conflict.

Get Generation

GEThttps://panel.seoauto.ai/pseo-endpoints/generations/:id

Returns the full status record for a single generation job. Poll this endpoint after starting a generation to track progress.

Path Parameters

Field	Type	Required	Description
id	number	required	The generation_id returned by the start generation endpoint

json — response 200

{
  "success": true,
  "data": {
    "id": 7,
    "pseo_id": 42,
    "status": "running",        // pending | running | completed | failed
    "requested_count": 10,
    "created_count": 4,
    "failed_count": 0,
    "failed_routes": [],
    "date_created": "2026-03-10T12:00:00.000Z",
    "date_updated": "2026-03-10T12:01:30.000Z",
    "date_completed": null
  },
  "timestamp": "2026-03-10T12:01:35.000Z"
}

Status	Meaning
pending	Job queued, not yet started
running	AI is actively generating pages
completed	All pages generated successfully
failed	Job stopped due to a critical error; check failed_routes

List Generations

GEThttps://panel.seoauto.ai/pseo-endpoints/generations?pseo_id=:pseo_id

Returns a list of up to 50 most recent generation jobs for a given PSEO, ordered newest first. Only returns jobs owned by the authenticated user.

Query Parameters

Field	Type	Required	Description
pseo_id	number	required	The PSEO (website) ID to list generations for

http — example request

GET https://panel.seoauto.ai/pseo-endpoints/generations?pseo_id=42
Authorization: Bearer <token>

json — response 200

{
  "success": true,
  "data": [
    {
      "id": 8,
      "pseo_id": 42,
      "status": "completed",
      "requested_count": 5,
      "created_count": 5,
      "failed_count": 0,
      "failed_routes": [],
      "date_created": "2026-03-10T13:00:00.000Z",
      "date_completed": "2026-03-10T13:04:21.000Z"
    },
    { "id": 7, "status": "completed", "..." : "..." }
  ],
  "timestamp": "2026-03-10T14:00:00.000Z"
}

Generate Site Map

POSThttps://panel.seoauto.ai/pseo-endpoints/generate/main-json

Uses AI to generate a structured content plan (main_json) for the PSEO — essentially a list of page routes, titles, and metadata that will be used as the blueprint for content generation. Tokens are deducted at the token_per_main_json rate.

Request Body

Field	Type	Required	Description
pseo_id	number	required	ID of the target PSEO
language_code	string	required	Language for the content plan, e.g. en-US, tr-TR, de-DE
description	string	required	Business description (150–1000 chars). Should cover sector, services, target audience, and goals.

json — request body

{
  "pseo_id": 42,
  "language_code": "en-US",
  "description": "We sell premium handmade leather goods including bags, wallets, and belts targeting fashion-conscious adults aged 25–45 in the United States. Our USP is ethically sourced full-grain leather with lifetime repair guarantee."
}

json — response 200

{
  "success": true,
  "message": "main_json generated and saved successfully",
  "data": {
    "main_json": {
      "pages": [
        { "route": "/leather-bags", "title": "Premium Leather Bags", "priority": 1 },
        { "route": "/leather-wallets", "title": "Handmade Leather Wallets", "priority": 2 }
      ]
    },
    "total_pages": 28
  },
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Concurrent generation limit

Only one main_json generation per user can run at a time. Concurrent requests return 409 Conflict.

Fetch Sitemap

GEThttps://panel.seoauto.ai/pseo-endpoints/fetch-sitemap?pseo_id=:pseo_id

Fetches and parses the sitemap of the website associated with a PSEO. Tries multiple common sitemap paths automatically (including sitemap indexes). Returns a flat list of all page URLs found. Useful for importing an existing website's URL structure.

Query Parameters

Field	Type	Required	Description
pseo_id	number	required	PSEO ID — the sitemap is fetched from the website_url stored in this record

Tried sitemap paths (in order): /sitemap.xml → /sitemap_index.xml → /wp-sitemap.xml → /sitemap

http — example request

GET https://panel.seoauto.ai/pseo-endpoints/fetch-sitemap?pseo_id=42
Authorization: Bearer <token>

json — response 200

{
  "success": true,
  "urls": [
    "https://example.com/",
    "https://example.com/leather-bags",
    "https://example.com/leather-wallets",
    "https://example.com/about"
  ]
}

Returns an empty urls array when no sitemap is found or the site is unreachable. Does not throw an error.

Error Codes

All error responses follow the same shape:

json — error shape

{
  "success": false,
  "error": "Human-readable error message",
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Status	Meaning
400Bad Request	Missing or invalid request parameters
401Unauthorized	Missing or invalid Bearer token
402Payment Required	Insufficient token balance for the requested operation
403Forbidden	Authenticated user is not the owner of the requested resource
404Not Found	PSEO or generation record does not exist
409Conflict	A concurrent generation job is already active
500Internal Server Error	Unexpected server-side error; check extension logs