SEO WRITING REST API: getting started
Create an API key, make your first request and connect your scripts and AI agents to SEO WRITING.
Full API reference with every endpoint and field: https://api.seowriting.ai/docs
The SEO WRITING REST API lets your own code, scripts and AI agents do what you do in the dashboard: write articles with SEO WRITING, save your own texts, publish them to your WordPress or Shopify site, update posts that are already on your site, and get Google data for a keyword. This guide shows how to start in about 10 minutes. For the exact parameters of each request, use the API reference above.
Who can use the API
The API works on every paid plan, starting with Starter. It is not available on the Free plan or during the trial.
If your subscription ends, your keys stop working within a minute: every request gets the answer 403. When you renew, the same keys work again, there is no need to create new ones.
Step 1. Create an API key
1. Open Settings → Integrations in your SEO WRITING dashboard.
2. In the API Keys block, click Create New API Key.

3. Give the key a name (for example, the name of your script) and click Create.
4. Copy the key and store it in a safe place. You will not be able to see it again.

You can create several keys, for example one per project. To stop a key, click the bin icon next to it and confirm Revoke Key: the key stops working at once.
Keep your key secret: anyone with the key can use your credits and publish to your sites.
Step 2. Make your first request
Send the key in the Authorization header of every request. For example, this request shows your credit balance:
The answer shows your credits for the current billing period. If you see it, your key works.
What you can do
The main tasks and their cost. Each endpoint is described in detail in the API reference.
| Task | Endpoint | Cost |
|---|---|---|
| See your credit balance | GET /v1/account/balance | Free |
| Write an article with SEO WRITING (as the 1-Click Blog Post form) | POST /v1/generation/article | Credits, see the estimate |
| Write many articles at once (Bulk) | POST /v1/generation/bulk | Credits, see the estimate |
| Rewrite or humanize a text, create a Super Page | POST /v1/generation/rewrite, /humanize, /super-page | Credits, see the estimate |
| Save your own article as a document | POST /v1/document | Free |
| Change a document | PUT /v1/document/{document_id} | Free |
| Publish a document to your site (draft, publish or schedule) | POST /v1/document/{document_id}/publish | Free |
| See categories, authors and post types of your site | GET /v1/site/{site_id}/options | Free |
| See the posts and pages already on your WordPress site | GET /v1/site/{site_id}/posts | Free |
| Update any post on your WordPress site | PUT /v1/site/{site_id}/posts/{post_id} | Free |
| Find pages of your site to link to (internal links) | GET /v1/site/{site_id}/pages | Free |
| Get Google data for a keyword: related searches, People also ask, AI Overview | POST /v1/search-data | 0.1 credit |
| Score a document against the top Google results (Content Score) | POST /v1/document/{document_id}/content-score | 0.1 credit |
| Write an article from your own brief, notes and files ("Describe your article") | POST /v1/generation/article with describe | Credits, see the estimate |
| Write an article from your own brief, notes and files ("Describe your article") | POST /v1/generation/article with describe | Credits, see the estimate |
Common scenarios
Write with SEO WRITING and publish
1. POST /v1/generation/article/estimate shows how many credits the article will cost.
2. POST /v1/generation/article starts the article and returns a task_id.
3. Wait until it is ready: check GET /v1/generation/{task_id}/status, or pass a callback_url and SEO WRITING will call your server when the article is done.
4. GET /v1/generation/{task_id}/result returns the article and its document_id.
5. POST /v1/document/{document_id}/publish sends it to your site.
Describe the article instead of giving a keyword
Use describe when you know what the article must say: a product with its specs, an event, a service with prices, your own notes. It works like the "Describe your article" tab of the 1-Click form.
1. Send POST /v1/generation/article with describe and without main_keyword. describe.text: what the article is about and what it must do, in your own words (for example: "A 1,200-word review of our espresso machine for home baristas. Add a table of specs and a FAQ, no conclusion."). describe.texts: pasted texts, such as notes or a draft. describe.files: up to 3 PDF, DOCX or TXT files in base64.
2. SEO WRITING reads the brief first and picks the keyword, the title and the wishes it names: length, headings, keywords, tone, elements such as tables or FAQ, and what each link is for. What the brief asks for in so many words comes before the other fields of the request. If you send main_keyword or title too, they are kept.
3. YouTube links in the brief are watched and their facts go into the article (charged by length: 0.1 credit per started 15 minutes, up to 0.6 credit a video). Pages you link to are read for their facts or shown as links or buttons, as the brief says.
4. If the brief has no clear topic, the task stops with describe_unclear and the credits are returned. Add a sentence about the topic and send it again.
The whole request can be up to 2 MB, so large files may not fit. Use a PDF with text: a scanned page is a picture and has no text to read.
Publish an article you wrote yourself
1. POST /v1/document with the HTML of your article. The first H1 becomes the post title. Images are taken by their URLs and downloaded to your site when you publish. Saving is free.
2. Optional: POST /v1/document/{document_id}/content-score counts the Content Score against the top Google results for your main keyword (usually 1-3 minutes). After that, GET /v1/document/{document_id}/content-score shows the score and what to improve, as often as you need, for free.
3. Optional: GET /v1/site/{site_id}/options gives the categories and authors of your site, so you can choose them.
4. POST /v1/document/{document_id}/publish with the status draft, publish or schedule.
5. Changed the text later? PUT /v1/document/{document_id}, then publish again with republish: true. The same post on your site is updated, no duplicate is created.
Update a post that is already on your site
This works for any post or page of a connected WordPress site, also for posts that were not written in SEO WRITING.
1. GET /v1/site/{site_id}/posts lists your posts. GET /v1/site/{site_id}/posts/{post_id} returns the text of one post.
2. PUT /v1/site/{site_id}/posts/{post_id} with the new text, title, SEO title or meta description. Only what you send is changed.
The date, author, URL, categories, tags, excerpt, featured image and existing images of the post stay as they are. The previous text is saved as a WordPress revision, so you can restore it in the WordPress editor.
This needs the SEO WRITING plugin for WordPress version 1.13.0 or newer. Update the plugin in your WordPress dashboard if the API asks you to.
Research a keyword before writing
POST /v1/search-data returns what people search and ask about a keyword in Google, and what Google's AI Overview answers. It is usually ready in 10-30 seconds.
GET /v1/site/{site_id}/pages?query=... finds the pages of your own site that fit a topic, so you can add internal links. Your site must be connected and indexed, and your plan must include internal linking.
Credits
Before any paid request, ask for the price: every paid action has an /estimate endpoint, and GET /v1/dictionary/generation-models lists the price of each article model.
Search Data costs 0.1 credit and is charged only when Google data is found. Content Score costs 0.1 credit per count; a document can be counted once a week, and reading the score is free.
Saving, changing and publishing documents, reading your sites and posts and updating posts are free.
Credits used through the API are the same credits as in the dashboard. You see them in Settings → Usage and with GET /v1/account/balance.
Limits and errors
Each key can make 60 requests per minute. Over the limit you get 429, and the Retry-After header tells how many seconds to wait. To avoid waiting, use callback_url instead of checking the status often.
401: the key is missing, wrong or revoked. 402: not enough credits. 403: your account has no active paid plan. 409: the action is not possible right now, the message says why (for example, the WordPress plugin needs an update).
Every error comes as {"error": {"code": ..., "message": "..."}}.
describe_unclear (in the task status): the brief in describe has no clear topic; the credits are returned.
Callbacks
Pass callback_url when you start an article, a rewrite, Search Data or an image. When the task is done or failed, SEO WRITING sends a POST request to that URL. Each request is signed with the X-Seowriting-Signature header; the secret for checking the signature is in Settings → Integrations, under Callback signing secret. The API reference shows how to check it.
FAQ
Is the API free?
The API has no extra fee: it is part of every paid plan. Actions that cost credits in the dashboard cost the same credits through the API. Saving and publishing your own articles is free.
Can I use the API on the Free plan?
No. The API is available on paid plans, starting with Starter.
Does the API work with Shopify?
Yes for publishing documents to a Shopify blog. Reading and updating existing posts works for WordPress only.
Where do I see all fields and answers?
In the API reference: https://api.seowriting.ai/docs It always matches the current API.
