SemanticPen API Documentation

Article Generation API

Our API allows you to generate high-quality articles programmatically, perfect for integrating with custom CMS, performing bulk article generation, or creating your own user interface.

All paid plans can use our API without additional costs. The usage will be the same as using the article generation feature from our website.

Key Features:

Asynchronous article generation
Multiple article modes including Pro Mode, Quick Mode, URL to Article, Bulk Writer, Amazon Product Reviews, and YouTube to Article
Customizable parameters for tone, language, SEO optimization, and more
Optional automatic integration to WordPress, Wix, Webflow, Webhook like Pabbly Connect, Zapier, Integromat, Make, Bubble, Landbot, Integromat, Flowmattic etc.

To use the API, you need an active, paid subscription. Visit your Account page to generate an API key once you have an active plan.

Endpoint

POST https://www.semanticpen.com/api/articles

Authentication

API requests must be authenticated using a Bearer token in the Authorization header.

You can find your API key on your Account page.

You need to have an active paid plan to use the API. If you are not registered yet, you can register here.

Then go to your Account page inside the settings section to generate an API key.

Do note that the API key is only shown once and cannot be retrieved later from the API, so make sure you save it.

API key will look something like this:

b0cf9c2f-60ad-8ujd-87eb-bd8nm042e092

To authenticate your request, you need to pass the API key in the Authorization header like this in every request:

Authorization: Bearer YOUR_API_KEY

Semantic Pen Article generation API works with a number of articles. We don't charge anything extra for the word count.

Request Body

The request body should be a JSON object containing the following properties:

Parameter	Type	Required	Description
targetKeyword	string	Yes	The main keyword or topic for the article. Multiple keywords can be provided, separated by newlines.
articleMode	string	No	The mode of article generation (e.g., "Bulk Writer", "Pro Mode", "Quick Mode"). Default is "Bulk Writer".
targetArticleTopic	string	No	Additional context for the article topic.
language	string	No	The language for the article. Default is "english".
country	string	No	The target country for the article.
toneOfVoice	string	No	The desired tone of voice for the article. Default is "professional".
pointOfView	string	No	The point of view to use in the article. Default is "firstPersonSingular".
includeTableOfContent	boolean	No	Whether to include a table of contents.
includeFAQSection	boolean	No	Whether to include an FAQ section.
includeKeyTakeaways	boolean	No	Whether to include key takeaways.
disableConclusion	boolean	No	Whether to disable the conclusion.
disableIntroduction	boolean	No	Whether to disable the introduction.
aiSeoOptimzation	boolean	No	Whether to apply AI-based SEO optimization.
customWritingStyle	string	No	Custom writing style instructions.
extraTitlePrompt	string	No	Additional prompt for title generation.
backgroundContextEntities	string	No	Additional context or entities for the article.
customLinks	array	No	Custom links to include in the article.
customCTAHeading	string	No	Custom call-to-action heading.
customCTALink	string	No	Custom call-to-action link.
customCTAInstruction	string	No	Instructions for the custom call-to-action.
customOutline	array	No	Custom outline for the article structure.
extraSectionPrompt	string	No	Additional prompt for section generation.
amazonProductURL	string	Conditional	Required for "Amazon Product Review Articles" mode. URL of the Amazon product.
amazonAffiliateTag	string	No	Amazon affiliate tag for product review articles.
youtubeVideoURL	string	Conditional	Required for "Youtube to Article" mode. URL of the YouTube video.
gptVersion	string	No	The GPT model version to use.
maximumExternalLinks	number	No	Maximum number of external links to include.
maximumInternalLinks	number	No	Maximum number of internal links to include.
includeInternalLinks	boolean	No	Whether to include internal links.
includeExternalLinks	boolean	No	Whether to include external links.
readabilityController	string	No	Controls the readability level of the generated content.
sectionLength	string	No	Desired length for each section (e.g., "200" or "400" words).

Parameter Values

Here are the possible values for some of the parameters:

Parameter	Possible Values
articleMode	"Quick Mode", "Pro Mode", "URL to Article", "Youtube to Article", "Amazon Product Review Articles", "Bulk Writer"
language	ISO 639-1 language codes (e.g., "en" for English, "es" for Spanish, etc.). Full list available in the LanguageData array.
country	Country names (e.g., "United States", "United Kingdom", etc.). Full list available in the LanguageData array.
toneOfVoice	"Professional", "Casual", "Friendly", "Authoritative", "Humorous", "Formal", "Inspirational", "Empathetic", "Neutral", "Confident", "Conversational", etc. Custom tones can also be specified.
pointOfView	"firstPersonSingular", "firstPersonPlural", "secondPerson", "thirdPerson"
gptVersion	"gpt-4o-mini", "gpt-3.5-turbo-0125", "gpt-4o", "openai/gpt-4o-mini", "openai/gpt-4o", "anthropic/claude-3.5-sonnet", "anthropic/claude-3-sonnet", "google/gemini-flash-1.5", "google/gemini-pro-1.5", "google/gemini-pro"
readabilityController	"very_easy", "easy", "medium", "hard", "expert", "advanced", "professional"
introStyle	"zero_search_result", "engagement_hook"
imageStyle	"digital-art", "photographic", "fantasy-art", "isometric", "3d-model", "anime", "neon-punk"
imageSize	"1024x1024", "1152x896", "1216x832", "1344x768", "1536x640", "640x1536", "768x1344", "832x1216", "896x1152"
mediaPreference	"None", "Auto", "Images", "Videos"
imageProvider	"stock-pixabay", "stable-diffusion-v3"
numberofOutline	String values from "2" to "15", representing the number of main headings

Note: For boolean parameters (e.g., includeTableOfContent, includeFAQSection, etc.), use true or false.

For numeric parameters (e.g., maximumExternalLinks, maximumInternalLinks, etc.), use integer values.

Response

The API responds with a JSON object containing the following properties:

Property	Type	Description
data	array	An array of generated article IDs.
error	string	Error message if the request fails.

Example Requests

Basic Article Generation

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "sustainable living tips",
    articleMode: "Bulk Writer",
    language: "english",
    country: "United States",
    toneOfVoice: "informative",
    pointOfView: "secondPerson",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true
  }),
});

Amazon Product Review Article

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "best eco-friendly water bottle",
    articleMode: "Amazon Product Review Articles",
    amazonProductURL: "https://www.amazon.com/Redragon-S101-Keyboard-Ergonomic-Programmable/dp/B00NLZUM36/",
    amazonAffiliateTag: "your-affiliate-tag-20",
    language: "english",
    country: "United States",
    toneOfVoice: "persuasive",
    pointOfView: "firstPersonSingular",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true
  }),
});

YouTube to Article

fetch("https://www.semanticpen.com/api/articles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "machine learning basics",
    articleMode: "Youtube to Article",
    youtubeVideoURL: "https://www.youtube.com/watch?v=creuUvqslYg",
    language: "english",
    country: "United States",
    toneOfVoice: "educational",
    pointOfView: "thirdPerson",
    includeTableOfContent: true,
    includeFAQSection: true,
    aiSeoOptimzation: true
  }),
});

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of requests. In case of an error, the response will include an `error` field with a description of the issue.

Common error codes:

400: Bad Request - The request was invalid or cannot be served.
401: Unauthorized - The request requires authentication or the provided API key is invalid.
403: Forbidden - The server understood the request but refuses to authorize it.
500: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.

Available Languages

Language Code	Language Name	Country
ar	Arabic	Saudi Arabia
bg	Bulgarian	Bulgaria
zh	Chinese (Simplified)	China
zh-tw	Chinese (Traditional)	Taiwan
hr	Croatian	Croatia
cs	Czech	Czech Republic
da	Danish	Denmark
nl	Dutch	Netherlands
en	English	United States
et	Estonian	Estonia
fi	Finnish	Finland
fr	French	France
de-formal-sie	German Formal (Sie)	Germany
de-informal-du	German Informal (du)	Germany
el	Greek	Greece
iw	Hebrew	N/A
hi	Hindi	India
hu	Hungarian	Hungary
id	Indonesian	Indonesia
ga	Irish	Ireland
it	Italian	Italy
ja	Japanese	Japan
ko	Korean	South Korea
la	Latin	Vatican City
lv	Latvian	Latvia
lt	Lithuanian	Lithuania
no	Norwegian	Norway
pl	Polish	Poland
pt	Portuguese	Portugal
ro	Romanian	Romania
ru	Russian	Russia
gd	Scottish Gaelic	Scotland
sr	Serbian	Serbia
sk	Slovak	Slovakia
sl	Slovenian	Slovenia
es	Spanish (idioma español)	Spain
sv	Swedish (svenska språket)	Sweden
th	Thai (ภาษาไทย)	Thailand
tr	Turkish	Turkey
uk	Ukrainian	Ukraine
vi	Vietnamese	Vietnam

Note: This list includes the main supported languages. Some languages may have additional variants or dialects.

SERP Countries and Codes

AngolaAO

ArgentinaAR

ArmeniaAM

AustraliaAU

AustriaAT

BahrainBH

BangladeshBD

BelgiumBE

BoliviaBO

BrazilBR

BulgariaBG

CanadaCA

ChileCL

ColombiaCO

Costa RicaCR

CroatiaHR

CyprusCY

Czech RepublicCZ

DenmarkDK

EcuadorEC

EgyptEG

El SalvadorSV

EstoniaEE

FinlandFI

FranceFR

GermanyDE

GreeceGR

GuatemalaGT

Hong KongHK

HungaryHU

IndiaIN

IndonesiaID

IrelandIE

IsraelIL

ItalyIT

JapanJP

JordanJO

KenyaKE

LatviaLV

LithuaniaLT

MalaysiaMY

MaltaMT

MexicoMX

MoroccoMA

NetherlandsNL

New ZealandNZ

NicaraguaNI

NigeriaNG

NorwayNO

PakistanPK

ParaguayPY

PeruPE

PolandPL

PortugalPT

RomaniaRO

Russian FederationRU

Saudi ArabiaSA

SerbiaRS

SingaporeSG

SlovakiaSK

SloveniaSI

South AfricaZA

South KoreaKR

SpainES

Sri LankaLK

SwedenSE

SwitzerlandCH

TaiwanTW

ThailandTH

TunisiaTN

TurkeyTR

UkraineUA

United Arab EmiratesAE

United KingdomGB

United StatesUS

UruguayUY

VenezuelaVE

Viet NamVN

Note: This list represents countries available for SERP data. Use the country code when making API requests.

Rate Limiting

API requests are subject to rate limiting to ensure fair usage. If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response. Please contact support for information about your specific rate limits.

Additional Notes

The `articleMode` parameter determines the type of article generation. Available modes include "Bulk Writer", "Pro Mode", "Quick Mode", "Amazon Product Review Articles", and "Youtube to Article".
When using the "Amazon Product Review Articles" mode, the `amazonProductURL` is required.
For the "Youtube to Article" mode, the `youtubeVideoURL` is required.
The API supports multiple target keywords. Provide them as a newline-separated string in the `targetKeyword` field.
The generated articles are queued for processing. The response includes article IDs that can be used to check the status or retrieve the completed articles later.

For any questions or support, please contact contact@semanticpen.com.