InsertSEO
Backend API to insert new SEO pages programmatically. Usage is charged from your credit balance.
Server-side only.
insertSeoPageand the raw API must be called from the server only. Never use them in client-side code (e.g. React components, browser JavaScript)—the secret key would be exposed. Use API routes, server actions, or backend scripts instead.
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| pageIdentifiers | array of PageIdentifiers | Yes | An array of PageIdentifiers to identify each page (path required). Must match pageSEO by index. |
| pageSEO | array of PageSEO | Yes | An array of PageSEO objects to insert. |
PageIdentifiers
| Property | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | The page path. Must begin with '/'. |
| pageId | string | No | The pageId of the SEO page. Optional alternative to path for identifying a page. |
PageSEO
| Property | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | The page path. Must begin with '/'. |
| title | string | Yes | Page title. |
| description | string | No | Page description. |
| follow | "follow" or "nofollow" | No | Default: "follow" |
| index | "index" or "noindex" | No | Default: "index" |
| changeFreq | "daily" or "monthly" or "weekly" | No | Default: "weekly" |
| keywordsArray | string[] | No | Array of keywords. |
| priority | "1" to "0.1" | No | Default: "0.5" |
| ldsJSON | string | No | JSON-LD structured data as a string. Visit https://json-ld.org/ for more information. |
| image | object with url | No | The url property must point to an externally hosted image file. |
API Reference
Endpoint: POST https://v1.seomanager.dev/backend_api/seo/insert
Headers
| Header | Required | Description |
|---|---|---|
| Content-Type | Yes | application/json |
| x-projectid | Yes | Your project ID. |
| x-projectkey | Yes | Your project key. |
| x-projectsecretkey | Yes | Your secret key. Keep this private and never expose it client-side. |
Request Body
{
"pageIdentifiers": [{ "path": "/example" }, { "path": "/about" }],
"pageSEO": [
{ "path": "/example", "title": "Example Page" },
{ "path": "/about", "title": "About Us", "description": "Learn about us" }
]
}
pageIdentifiers and pageSEO must be parallel arrays: the item at index i in pageIdentifiers corresponds to the item at index i in pageSEO.
Response Shape
// Success
{ message: "Successful", results: { succeeded: true }, error: false, statusCode: 200 }
// Error
{ results: false, error: true, message: "Error description" }
Examples
cURL
curl -X POST https://v1.seomanager.dev/backend_api/seo/insert \
-H "Content-Type: application/json" \
-H "x-projectid: YOUR_PROJECT_ID" \
-H "x-projectkey: YOUR_PROJECT_KEY" \
-H "x-projectsecretkey: YOUR_SECRET_KEY" \
-d '{"pageIdentifiers":[{"path":"/example"},{"path":"/about"}],"pageSEO":[{"path":"/example","title":"Example Page"},{"path":"/about","title":"About Us","description":"Learn about us"}]}'
Python
import requests
url = "https://v1.seomanager.dev/backend_api/seo/insert"
headers = {
"Content-Type": "application/json",
"x-projectid": "YOUR_PROJECT_ID",
"x-projectkey": "YOUR_PROJECT_KEY",
"x-projectsecretkey": "YOUR_SECRET_KEY",
}
payload = {
"pageIdentifiers": [{"path": "/example"}, {"path": "/about"}],
"pageSEO": [
{"path": "/example", "title": "Example Page"},
{"path": "/about", "title": "About Us", "description": "Learn about us"},
],
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
PHP
<?php
$url = "https://v1.seomanager.dev/backend_api/seo/insert";
$payload = [
"pageIdentifiers" => [["path" => "/example"], ["path" => "/about"]],
"pageSEO" => [
["path" => "/example", "title" => "Example Page"],
["path" => "/about", "title" => "About Us", "description" => "Learn about us"],
],
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"x-projectid: YOUR_PROJECT_ID",
"x-projectkey: YOUR_PROJECT_KEY",
"x-projectsecretkey: YOUR_SECRET_KEY",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Node.js (fetch)
const response = await fetch("https://v1.seomanager.dev/backend_api/seo/insert", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-projectid": process.env.SEO_MANAGER_PROJECT_ID,
"x-projectkey": process.env.SEO_MANAGER_PROJECT_KEY,
"x-projectsecretkey": process.env.SEO_MANAGER_SECRET_KEY,
},
body: JSON.stringify({
pageIdentifiers: [{ path: "/example" }, { path: "/about" }],
pageSEO: [
{ path: "/example", title: "Example Page" },
{ path: "/about", title: "About Us", description: "Learn about us" },
],
}),
});
const data = await response.json();
Node.js with nextjs-seo-manager (Next.js)
The nextjs-seo-manager package normalizes the payload and only requires pageSEO; it derives pageIdentifiers from the paths in each PageSEO object. These examples run in API routes (server-side only)—never in client components.
Pages Router (API route)
// pages/api/insert-seo.js
import SEOInit from "nextjs-seo-manager/init";
import { insertSeoPage } from "nextjs-seo-manager";
SEOInit({
projectId: process.env.SEO_MANAGER_PROJECT_ID,
secretKey: process.env.SEO_MANAGER_SECRET_KEY,
});
export default async function handler(req, res) {
try {
const response = await insertSeoPage([
{ title: "Example Page", path: "/example" },
{ title: "About Us", path: "/about", description: "Learn about us" },
]);
return res.status(200).json(response);
} catch (err) {
return res.status(500).json({ error: err.message });
}
}
App Router (API route)
// app/api/insert-seo/route.ts
import { NextRequest, NextResponse } from "next/server";
import SEOInit from "nextjs-seo-manager/init";
import { insertSeoPage } from "nextjs-seo-manager";
SEOInit({
projectId: process.env.SEO_MANAGER_PROJECT_ID,
secretKey: process.env.SEO_MANAGER_SECRET_KEY,
});
export async function POST(request: NextRequest) {
try {
const { pages } = await request.json();
const response = await insertSeoPage(pages);
return NextResponse.json(response);
} catch (err: any) {
return NextResponse.json({ error: err.message }, { status: 500 });
}
}
Limitations
- The
pageSEOarray is limited to 50 items per call. - If any page in the batch has an error, none of them will be inserted (all-or-nothing).
- Will not update existing pages. Use UpdateSEO or set
upsert: trueinstead.