--- title: "New Article (Advanced Mode)" method: POST path: "/v1/new-article" --- # New Article (Advanced Mode) `POST /v1/new-article` Submit a request to create a new advanced mode article. For more examples, visit [Example Payloads Documentation](https://apidocs.agilitywriter.ai/example-payloads.html). ## Query parameters - `api_key` string, required ## Request body - object - `article_title` string, required — The title of the article. If left empty, ensure that the main keyword is provided. - `main_keyword` string — The main keyword used to search top-ranking websites for generating article outlines and collecting entities. If left empty, the article title will be used by default, so please ensure that the article title is provided. (Optional) - `region` 'ar' | 'au' | 'be' | 'br' | 'ca' | 'cl' | 'cn' | 'hr' | 'dk' | 'fi' | 'fr' | 'de' | 'hk' | 'hu' | 'in' | 'id' | 'ie' | 'il' | 'it' | 'jp' | 'my' | 'mx' | 'nl' | 'nz' | 'no' | 'ph' | 'pl' | 'pt' | 'ro' | 'rs' | 'sg' | 'za' | 'kr' | 'es' | 'lk' | 'se' | 'ch' | 'tw' | 'th' | 'uk' | 'ua' | 'us' | 'vn' | 'bh' | 'eg' | 'kw' | 'ma' | 'om' | 'sa' | 'tn' | 'ae', required — The region for which the article is targeted. - `search_source` 'google_web' | 'google_news' | 'bing_web' — The search source that the system will crawl to create the outline and use as the data source. Defaults to google_web. - `search_time_period` 'any_time' | 'last_hour' | 'last_day' | 'last_week' | 'last_month' | 'last_year' — The time period for the system to filter the search results. Defaults to any_time. - `project_id` integer — The ID of the project to which the article belongs. Defaults to 0 (none). (Optional) - `output_language` 'American English' | 'Australian English' | 'British English' | 'Canadian English' | 'Simplified Chinese' | 'Traditional Chinese' | 'Malay' | 'Arabic' | 'Brazilian Portuguese' | 'Croatian' | 'Danish' | 'Dutch' | 'German' | 'French' | 'Hebrew' | 'Hungarian' | 'Indonesian' | 'Italian' | 'Japanese' | 'Korean' | 'Norwegian' | 'Polish' | 'Portuguese' | 'Romanian' | 'Serbian' | 'Spanish' | 'Swedish' | 'Tagalog' | 'Vietnamese', required — The language in which the article will be written. - `article_length` 'auto' | 'h2_focus' | '750' | '751_1250' | '1251_2000' | '2001_3000' | '3001_4000' | '4001_5000', required — The article length for the article. Defaults to auto. - `main_headings` 'auto' | 'h2_focus' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' — Deprecated - Use article_length. The number of main headings (H2 headings) to be used in the article. Defaults to auto. (Optional) - `target_word_count` integer — The target word count for the article. This option only applicable when main headings is set to auto or h2_focus. (Optional) - `article_structure` 'advanced_standard' | 'advanced_detail' | 'text_standard' | 'text_long' — The structure of the content for each heading. Defaults to advanced_standard. (Optional) - `ai_model` 'standard' | 'gpt4o_mini' | 'gpt4o' | 'gpt4.1' | 'gpt4.1_mini' | 'gpt5' | 'gpt5_mini' | 'gpt5.2' | 'o3_mini' | 'o4_mini' | 'claude4_sonnet' | 'claude4.5_sonnet' | 'claude4.6_sonnet' | 'deepseek_v3' | 'grok3' | 'grok3_mini' | 'grok4' | 'gemini_pro_2.5' | 'gemini_pro_3.1' | 'gemini_flash_2.0', required — The AI model to be used for generating the article. Defaults to standard. (Optional) - `factual_data` 'none' | 'custom' | 'indepth_research' | 'indepth_research_cite' | 'standard' — The level of factual data to be included in the article. Defaults to custom. (Optional) - `factual_data_custom_url` string — Only applicable when factual_data is set to custom. Provide the factual data sources (maximum of 3 URLs) for the article, with each URL on a new line. If left empty, the system will automatically select 3 URLs from the top search results. If none of the URLs are accessible, the writing job will be canceled. (Optional) - `audience` string — The target audience for the article. (Optional) - `tone_of_voice` string — The tone of voice to be used in the article. (Optional) - `point_of_view` 'point_of_view_auto' | 'first_person_singular' | 'first_person_plural' | 'second_person' | 'third_person' — The point of view to be used in the article. Defaults to point_of_view_auto. (Optional) - `writing_style` 'default' | 'auto_from_serp' | 'all_authoritative_conversational' | 'all_authoritative_instructional' | 'all_expository_technical' | 'all_humanize' | 'all_precision_optimization' | 'all_precision_semantic_triples' | 'all_unfluffpro_1_authoritative' | 'all_unfluffpro_2_authoritative' | 'health_authoritative' | 'local_biz_authoritative_persuasion' | 'news' | 'seo_nlp_friendly' | 'seo_authoritative' | 'travel_narrative' | 'anti_ai_detection_concise_tone' | 'anti_ai_detection_informal_tone' — The writing style to be used in the article. Defaults to default. (Optional) - `introduction_style` 'concise' | 'engaging' | 'authoritative' | 'comprehensive_insight' — The style of the introduction. Defaults to concise. (Optional) - `conclusion_style` 'concise' | 'engaging' | 'expert_opinion' — The style of the conclusion. Defaults to concise. (Optional) - `include_custom_instruction` boolean — Option to include custom instructions for the article. Defaults to false. (Optional) - `custom_knowledge` string — Custom knowledge to be included in the article. Do not include writing instruction. (Optional) - `customize_outline_method` 'instructions' | 'fixed_template' | 'dynamic_template' — The method for customizing the outline. Defaults to instructions. (Optional) - `customize_outline_instruction` string — Instructions for customizing the outline. (Optional) - `writing_instruction_for_heading` string — Writing instructions for all headings. (Optional) - `create_outline` boolean — Option to create an outline for the article. Defaults to false. (Optional) - `article_outline` string — The outline of the article. If empty, an outline will be auto-generated. - `keywords` string — List of keywords to be included in the article. Each keyword should be on a new line. (Optional) - `key_takeaways` boolean — Option to generate key takeaways for the article. Defaults to true. (Optional) - `faqs_title_description` boolean — Option to generate FAQs, meta title, and description for the article. Defaults to true. (Optional) - `image_prompts` boolean — Option to generate image prompts for the article. Defaults to false. (Optional) - `youtube_videos` boolean — Option to include relevant YouTube videos in the article. Defaults to false. (Optional) - `add_styling` boolean — Option to add bold formatting style to the article. Defaults to false. (Optional) - `readability_level` 'default' | '5th_grade' | '6th_grade' | '7th_grade' | '8th_9th_grade' | '10th_12th_grade' | '13th_15th_grade' | '16th_grade' — This option enhances the article's readability. Defaults to default. (Optional) - `improve_readability` boolean — Deprecated - Use readability_level. This option enhances the article's readability but will be ignored if readability_level is specified. Defaults to true. (Optional) - `authority_links` boolean — Option to include authority links in the article. Defaults to false. (Optional) - `internal_links` boolean — Option to include internal links in the article. Defaults to false. (Optional) - `internal_links_references` string — A list of internal link references to be incorporated into the article. Each link should be on a new line. (Optional) - `entity_enrichment` boolean — Option to include entities from top-ranking sites in the article. Defaults to true. (Optional) - `change_h3_to_bold` boolean — Option to change H3 headings to bold in the article. Defaults to false. (Optional) - `disable_transition` boolean — Option to exclude transition words between each heading. Defaults to true. (Optional) - `exclude_quotes` boolean — Option to exclude quotes in the article. Defaults to true. (Optional) - `negative_terms` boolean — Option to remove negative terms from the article. Defaults to false. (Optional) - `negative_terms_references` string — A list of negative terms to be removed from the article. If left empty, common negative terms will be used. (Optional) - `first_hand_experience` boolean — Option to include first-hand experience in the article. Defaults to false. (Optional) - `shoutout_posts` boolean — Option to generate shoutout posts from the article. Defaults to false. (Optional) - `images_placement` 'none' | 'free' | 'standard_20' | 'standard_40' | 'standard_60' | 'premium_6' | 'premium_13' | 'premium_19' — Option to include number of images in the article. Defaults to none. (Optional) - `images_style` 'photo' | 'cinematic' | 'creative_photo' | 'anime' | 'comic_book' | 'digital_art' | 'fantasy_art' | 'flat_design' — The style of images to be included in the article. Defaults to photo. (Optional) - `images_size` 'landscape_16_9' | 'landscape_3_2' | 'portrait_9_16' | 'square' | 'landscape_16_9_small' | 'landscape_3_2_small' | 'portrait_9_16_small' | 'square_small' — The size of images to be included in the article. Defaults to landscape_3_2. (Optional) - `images_alt_tag` 'none' | 'short' | 'long' | 'short_keyword' | 'long_keyword' — The alt tag for images included in the article. Defaults to short. (Optional) - `images_text_overlay` 'none' | '1_none' | '1_black' | '1_blue' | '1_green' | '1_red' | '2_none' | '2_black' | '2_blue' | '2_green' | '2_red' — The number of text overlay images included in the article. Defaults to none. (Optional) - `images_no_people` 'auto' | 'less' | 'more' | 'none' — The presence of people in the images included in the article. Defaults to auto. (Optional) - `images_ethnicity` 'auto' | 'black' | 'caucasian' | 'east_asian' | 'south_asian' | 'hispanic' — The ethnicity of people in the images included in the article. Defaults to auto. (Optional) - `images_same_person` 'no' | 'yes' — Option to use the same person in all images included in the article. Defaults to no. (Optional) - `publish_to` string — The URL of the site where the article will be published. This URL must match the site specified in the Agility Writer WordPress integration. If left empty, the system will not auto-publish the article. (Optional) - `publish_type` 'post' | 'page' — The type of publication (post or page). Defaults to post. (Optional) - `publish_status` 'draft' | 'publish' — The status of the publication (draft or publish). Defaults to draft. (Optional) - `publish_date` string, date-time — The publish date of the article. Defaults to current date time. (Optional) - `publish_category_id` integer — The category ID for the publication. (Optional) - `publish_slug_type` 'default' | 'keyword' | 'title' — The type of slug for the publication. (Optional) - `publish_tags` string — The tags for the publication. (Optional) - `nw_api_key` string — The API key for NeuronWriter. (Optional) - `nw_query_id` string — The query ID for NeuronWriter. (Optional) - `nw_project_id` string — The project ID for NeuronWriter. (Optional) - `nw_word_count` integer — The word count from NeuronWriter. (Optional) - `nw_to_content_editor` boolean — Option to auto-push the article to NeuronWriter once completed. Defaults to false. (Optional) ## Response `200` Successful response - object - `status` string — The status of the response. - `article_id` integer — The ID of the created article. - `message` string — The message related to the status. ## Other responses - `400` — Invalid request - `401` — Unauthorized --- [API](https://skmtc.net/agilitywriter/apis/agility-writer-api-beta.md) · [All operations](https://skmtc.net/agilitywriter/apis/agility-writer-api-beta/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agilitywriter/agility-writer-api-beta/revisions/91fc72cb99f6/schema)