Public docsFor site maintainersNext.js sites

SEO content hosting docs

Connect RankOps AI approved SEO articles to your own website. Your site only needs one secure POST endpoint that validates a shared token and returns the published URL.

View API format Prompt for an AI coding assistant

1. Understand the publishing flow

1. RankOps AI generates the article

The workflow starts from keyword discovery, then creates an outline and a reviewable article draft.

2. You review the article

Confirm the title, body, SEO description, and publish status before it leaves RankOps AI.

3. Your site receives the article

RankOps AI calls your POST endpoint and sends the approved content.

4. Your site returns the result

Return the target post ID, public URL, final status, and slug.

2. Endpoint your website needs

Add this endpoint to your website: POST /api/seo-content/publish

Authorization: Bearer SEO_CONTENT_PUBLISH_TOKEN

sourceArticleIdArticle ID from RankOps AI. Use it to trace duplicate publishing attempts.

titleArticle title. Save it as the target post title.

slugURL slug. Return 409 when the slug already exists.

descriptionSEO meta description. It can be empty.

contentFull article body, usually HTML. Save it without truncation.

languageArticle language, such as en or zh.

authorName / authorImageOptional author information.

statusdraft or published. Public publishing must return published.

dryRunOptional. When true, run a connection test only and return a validation response.

Request body example

{
  "sourceArticleId": "rankops-article-id",
  "title": "Article title",
  "slug": "article-url-slug",
  "description": "Meta description",
  "content": "<p>HTML article body</p>",
  "language": "en",
  "authorName": "RankOps AI",
  "authorImage": "https://example.com/avatar.png",
  "status": "published"
}

Success response example

{
  "targetPostId": "post-id-from-your-site",
  "publishedUrl": "https://your-site.com/blog/article-url-slug",
  "status": "published",
  "slug": "article-url-slug"
}

Connection test request

RankOps AI sends a dryRun request when you test the connection. Your website validates the token and endpoint, then returns a validation-only response.

{
  "dryRun": true,
  "source": "rankops",
  "purpose": "connection_test"
}

Connection test success response

{
  "ok": true,
  "dryRun": true
}

3. Configure RankOps AI

Open the RankOps AI console, choose the current site, then fill in the receiving endpoint URL, shared token, and default publish status.

Receiving endpoint URL: https://your-site.com/api/seo-content/publish
Shared token: the same token your website validates
Default publish status: published or draft

The endpoint path is only an example. Your website decides how articles are stored, how public URLs are generated, and whether posts live under /blog or another route.

4. Test in this order before launch

Start your target website locally and make sure the endpoint URL is reachable.
Use the same shared token in RankOps AI and in your target website, but do not expose it in frontend code.
Fill the receiving endpoint URL, shared token, and default publish status in the RankOps AI site settings.
Click Test connection first. If your website supports dryRun, RankOps AI will mark the connection as verified.
Publish one reviewed article first. Do not start with a bulk publish.
Open the returned publishedUrl and confirm the article is publicly visible.

5. Troubleshooting

401

The shared token does not match. Check the Bearer value and the token stored by your website.

400

A required field is missing or invalid. Check title, slug, content, language, and status first.

409

The target website already has this slug. Change the slug or update the existing post intentionally.

Test connection failed

The target website may not support dryRun yet. Add the dryRun branch before relying on the connection test.

Published URL returns 404

The target website returned a URL, but the post may still be a draft or the route cache may need refresh.

RankOps has not called the target site

Confirm the article is generated, reviewed, and ready for the hosting step.

6. Prompt for an AI coding assistant

If you use an AI coding assistant, paste this prompt into your website project so it can implement the endpoint with tests.

Add an SEO content hosting endpoint to my Next.js project.

Goal: receive approved articles from RankOps AI and create posts on my own website.

Endpoint requirements:
1. Add POST /api/seo-content/publish. This path is an example and can be replaced with /api/rankops/publish or another project route.
2. Read Authorization: Bearer <SEO_CONTENT_PUBLISH_TOKEN> from the request headers.
3. If the token does not match, return 401 before any article write.
4. If the body is { dryRun: true, source: "rankops", purpose: "connection_test" }, validate only the token and endpoint, then return { ok: true, dryRun: true } as a validation-only response.
5. For normal publish requests, read sourceArticleId, title, slug, description, content, language, authorName, authorImage, and status.
6. title, slug, content, and language are required. status only allows draft or published.
7. If the slug already exists, return 409 with a clear message.
8. The target website decides how posts are stored and how public URLs are generated. After creating the article, return targetPostId, publishedUrl, status, and slug.
9. publishedUrl must be a public http or https URL.
10. Keep the token on the server, avoid hardcoding it in frontend code, and return real success or error states.
11. Add tests for dryRun, 401, 400, 409, and successful publishing.