{"definitions":{"Authentication":{"properties":{"email":{"example":"kwi@keywordinsights.ai","type":"string"},"password":{"example":"test12345","type":"string"}},"required":["email","password"],"type":"object"},"CreateAdvancedRankingBatchOrder":{"properties":{"device":{"enum":["desctop","mobile"],"example":"desctop","type":"string"},"domain":{"example":"domain","type":"string"},"include_word_count":{"example":false,"type":"boolean"},"keywords":{"example":["keyword1","keyword2"],"items":{"type":"string"},"type":"array"},"language":{"example":"en","type":"string"},"location":{"example":"United States","type":"string"}},"required":["keyword","language","location","domain"],"type":"object"},"CreateAdvancedRankingOrder":{"properties":{"device":{"enum":["desctop","mobile"],"example":"desctop","type":"string"},"domain":{"example":"domain","type":"string"},"include_word_count":{"example":false,"type":"boolean"},"keyword":{"example":"keyword","type":"string"},"language":{"example":"en","type":"string"},"location":{"example":"United States","type":"string"}},"required":["keyword","language","location","domain"],"type":"object"},"CreateContentBrief":{"properties":{"keyword":{"example":"keyword","type":"string"},"language":{"example":"en","type":"string"},"location":{"example":"Canada","type":"string"}},"required":["keyword","language","location"],"type":"object"},"CreateKeywordContentOrder":{"properties":{"content_insights":{"enum":["paa","reddit_questions","meta_titles","meta_descriptions","quora_questions"],"example":["paa"],"items":{"type":"string"},"type":"array"},"device":{"enum":["desktop","mobile"],"example":"desktop","type":"string"},"keyword":{"example":"keyword","type":"string"},"language":{"example":"en","type":"string"},"location":{"example":"United States","type":"string"}},"required":["keyword","language","location","content_insights"],"type":"object"},"CreateOrder":{"properties":{"clustering_method":{"enum":["volume","agglomerative"],"example":"volume","type":"string"},"device":{"enum":["desktop","tablet","mobile"],"example":"desktop","type":"string"},"folder_id":{"example":"bbb5bbc9-8409-4b08-a023-769c94f8f226 // Can be retrieved from the browser url in the keyword insights dashboard.","type":"string"},"grouping_accuracy":{"enum":[1,2,3,4,5,6,7],"example":4,"type":"integer"},"hub_creation_method":{"enum":["soft","medium","hard"],"example":"medium","type":"string"},"insights":{"enum":["cluster","context","rank"],"example":["cluster","rank","context"],"items":{"type":"string"},"type":"array"},"keywords":{"example":["tesla","tesla s","tesla 3","tesla x"],"items":{"type":"string"},"type":"array"},"language":{"example":"en","type":"string"},"location":{"example":"United States","type":"string"},"mobile_type":{"enum":["iphone","android"],"example":"android","type":"string"},"project_name":{"example":"project_name","type":"string"},"search_volumes":{"example":[213,1561,616,777],"items":{"type":"number"},"type":"array"},"tablet_type":{"enum":["ipad","android"],"example":"android","type":"string"},"url":{"example":"https://tesla.com/","type":"string"}},"required":["project_name","keywords","search_volumes","language","location","insights"],"type":"object"}},"host":"api.keywordinsights.ai/","info":{"contact":{"email":"abod@snippet.digital","responsibleDeveloper":"Abdulqader Mohammed","responsibleOrganization":"Snippet Digital"},"description":"The integration point to automate your process","termsOfService":"https://www.keywordinsights.ai/terms-conditions/","title":"Keyword Insights Public API","version":"1.0.1"},"operationId":"getmyData","paths":{"/api/advanced-ranking/batch/order/":{"get":{"description":"Example: /api/advanced-ranking/batch/order/?order_id=
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order unique identifier, that was issued upon order creation. **example: 2879fa0b-deae-4aab-ad87-fd8fb8db9717**\n","in":"query","name":"order_id","required":true,"type":"string"}],"responses":{"200":{"description":"Order status.","schema":{"properties":{"error":{"description":"Error description.","type":"string"},"payload":{"properties":{"order_id":{"description":"Id of the order.","type":"string"},"results":{"items":{"properties":{"domain_rankings":{"description":"List of URLs which rank in top 100 for a domain provide in order data.","items":{"properties":{"rank":{"description":"The position in SERP of a given URL.","type":"integer"},"url":{"description":"Ranked URL.","type":"string"}},"type":"object"},"type":"array"},"keyword":{"type":"string"},"n_domain_rankings":{"description":"Total number of URLs ranked for a domain in the top 100 SERP results.","type":"integer"},"related_questions":{"description":"People Also Asked parsed from SERP if available.","items":{"type":"string"},"type":"array"},"related_searches":{"description":"Related Searches parsed from SERP if available.","items":{"type":"string"},"type":"array"},"top_rankings":{"description":"Top 10 URLs from SERP with optional word count.","items":{"properties":{"url":{"type":"string"},"word_count":{"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"type":"list"},"status":{"description":"Current status of the order.","enum":["created","done"],"type":"string"}},"type":"object"},"status":{"description":"The status of endpoint run.","type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Check Advanced Ranking batch order status. Get order results once ready. Parameters accepted as URL string.","tags":["Keyword Ranking"]},"post":{"description":"word count for top ranking URLs, list of top 10 ranking URLs from a given domain, number of URLs ranking in top
100 from a given domain. Parameters accepted as JSON object.
Cost:
1 credit per keyword without wordcount.
10 credits per keyword with wordcount.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"```keywords*```: Array of target queries (keywords).\n\n```language*```: Language code to use for SERP results scraping. To get available languages use\n the /api/keywords-insights/languages/ endpoint from insights API.\n\n```location*```: Location name to use for SERP results scraping.To get available locations use\n the /api/keywords-insights/locations/ and /api/keywords-insights/locations-live/some_locations/\n endpoint from insights API.\n\n```domain*```: The domain to track rankings for.\n\n**device**: The device for the SERP scraping. [\"desktop\", \"mobile\"]\n\n**include_word_count**: Set true if require to include wordcount for top ranking pages.\n","in":"body","name":"body","schema":{"$ref":"#/definitions/CreateAdvancedRankingBatchOrder"}}],"responses":{"200":{"description":"The result of creating of the order in the system.","schema":{"properties":{"cost":{"description":"Amount of credits spent from users account to create the order.","type":"integer"},"order_id":{"description":"Id of created order.","type":"string"},"status":{"description":"The status of the order creation. True if order created successfully.","type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Batch interface for ranking advanced report. Main features: list of top ranking URLs,","tags":["Keyword Ranking"]}},"/api/advanced-ranking/order/":{"get":{"description":"Example: /api/advanced-ranking/order/?order_id=
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order unique identifier, that was issued upon order creation. **example: 2879fa0b-deae-4aab-ad87-fd8fb8db9717**\n","in":"query","name":"order_id","required":true,"type":"string"}],"responses":{"200":{"description":"Order status.","schema":{"properties":{"error":{"description":"Error description.","type":"string"},"payload":{"properties":{"order_id":{"description":"Id of the order.","type":"string"},"results":{"properties":{"domain_rankings":{"description":"List of URLs which rank in top 100 for a domain provide in order data.","items":{"properties":{"rank":{"description":"The position in SERP of a given URL.","type":"integer"},"url":{"description":"Ranked URL.","type":"string"}},"type":"object"},"type":"array"},"n_domain_rankings":{"description":"Total number of URLs ranked for a domain in the top 100 SERP results.","type":"integer"},"related_questions":{"description":"People Also Asked parsed from SERP if available.","items":{"type":"string"},"type":"array"},"related_searches":{"description":"Related Searches parsed from SERP if available.","items":{"type":"string"},"type":"array"},"top_rankings":{"description":"Top 10 URLs from SERP with optional word count.","items":{"properties":{"url":{"type":"string"},"word_count":{"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"status":{"description":"Current status of the order.","enum":["created","done"],"type":"string"}},"type":"object"},"status":{"description":"The status of endpoint run.","type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Check Advanced Ranking order status. Get order results once ready. Parameters accepted as URL string.","tags":["Keyword Ranking"]},"post":{"description":"list of top 10 ranking URLs from a given domain, number of URLs ranking in top 100 from a given domain.
Parameters accepted as JSON object.
Cost:
1 credit per request without wordcount.
10 credits per request with wordcount.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"```keyword*```: Target query (keyword)\n\n```language*```: Language code to use for SERP results scraping. To get available languages use\n the /api/keywords-insights/languages/ endpoint from insights API.\n\n```location*```: Location name to use for SERP results scraping.To get available locations use\n the /api/keywords-insights/locations/ and /api/keywords-insights/locations-live/some_locations/\n endpoint from insights API.\n\n```domain*```: The domain to track rankings for.\n\n**device**: The device for the SERP scraping. [\"desktop\", \"mobile\"]\n\n**include_word_count**: Set true if require to include wordcount for top ranking pages.\n","in":"body","name":"body","schema":{"$ref":"#/definitions/CreateAdvancedRankingOrder"}}],"responses":{"200":{"description":"The result of creating of the order in the system.","schema":{"properties":{"cost":{"description":"Amount of credits spent from users account to create the order.","type":"integer"},"order_id":{"description":"Id of created order.","type":"string"},"status":{"description":"The status of the order creation. True if order created successfully.","type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Keyword ranking advanced report. Main features: list of top ranking URLs, word count for top ranking URLs,","tags":["Keyword Ranking"]}},"/api/content-brief/languages/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"Content brief status and content.","schema":{"payload":{"items":{"type":"object"},"type":"array"}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Content Briefs supported languages.","tags":["Content Brief"]}},"/api/content-brief/order/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order unique identifier, that was issued upon order creation. **example: 2879fa0b-deae-4aab-ad87-fd8fb8db9717**\n","in":"query","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"Content brief status and content.","schema":{"properties":{"payload":{"properties":{"brief_description_suggests":{"description":"AI generated suggested meta descriptions.","items":{"type":"object"},"type":"array"},"brief_title_suggests":{"description":"AI generated suggested meta titles.","items":{"type":"object"},"type":"array"},"headings_count":{"description":"Total number of headings, scraped from top SERPs.","type":"number"},"keyword":{"type":"string"},"language":{"type":"string"},"location":{"type":"string"},"pages_count":{"description":"Total number of organic SERPs scraped.","type":"number"},"processing_status":{"description":"Status for different parts of the brief. Useful for lazy loading.","type":"object"},"raw":{"description":"Raw items of the content brief.","items":{"properties":{"description":{"description":"Meta description from SERP snippet. Applicable to serp_page object.","type":"string"},"domain":{"description":"Domain from SERP snippet. Applicable to serp_page object.","type":"string"},"h_tags_count":{"description":"number of headings scraped from SERP. Applicable to serp_page object.","type":"number"},"id":{"description":"Unique identifier of the item. Applicable to all types of objects.","type":"string"},"key":{"description":"The type of content item. Content items have slightly different properties.","enum":["serp_page","title_ai","reddit_question","people_also_asked","brief_ai","quora_question"],"type":"string"},"parsed_page_structure":{"description":"The list of serp_heading types of objects, which form the page structure. Applicable to serp_page object.","items":{"properties":{"bullet_points":{"description":"Bullet points extracted from the text under the heading.","items":{"properties":{"content_weight":{"description":"The weights of the bullet point content within the whole amount of content from top SERPs.","type":"number"},"heading":{"description":"The content of the bullet point.","type":"string"},"id":{"type":"string"},"tag":{"type":"string"}},"type":"object"},"type":"array"},"cluster_id_max":{"description":"Semantic content similarity to the rest of content items cluster, with the strongest similarity level. Helps to identify the similar content.","type":"number"},"cluster_id_med":{"description":"Semantic content similarity to the rest of content items cluster, with medium similarity level. Helps to identify the similar content.","type":"number"},"cluster_id_min":{"description":"Semantic content similarity to the rest of content items cluster, with low similarity level. Helps to identify the similar content.","type":"number"},"content_weight":{"description":"The weights of the bullet point content within the whole amount of content from top SERPs","type":"number"},"heading":{"description":"The text from the heading.","type":"string"},"id":{"type":"string"},"index":{"description":"The relative position of the heading item on the page.","type":"number"},"page_id":{"description":"The id of a parent page.","type":"string"},"tag":{"description":"The original HTML tag of the heading.","type":"string"},"word_count":{"description":"The number of words in the text located under the heading.","type":"number"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"word_count_avg":{"type":"number"},"word_count_max":{"type":"number"},"word_count_min":{"type":"number"}},"type":"object"},"status":{"description":"Current status of the order.","type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Get the content brief results.","tags":["Content Brief"]},"post":{"description":"Cost:
1 content brief search.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"```keyword*```: Target query (keyword).\n\n```language*```: Language code to use for SERP results scraping. To get available languages use\n the /api/content-brief/languages/ endpoint.\n\n```location*```: Location name to use for SERP results scraping.To get available locations use\n the /api/keywords-insights/locations/ and /api/keywords-insights/locations-live/\n endpoint from insights API.\n","in":"body","name":"body","schema":{"$ref":"#/definitions/CreateContentBrief"}}],"responses":{"200":{"description":"The result of creating of the order in the system.","schema":{"properties":{"cost":{"description":"Amount of credits spent from users account to create the order.","type":"integer"},"id":{"description":"Id of created content brief order.","type":"string"},"status":{"description":"The status of the order creation. True if order created successfully.","type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Content Briefs creation.","tags":["Content Brief"]}},"/api/content-brief/order/{order_id}/outline/":{"get":{"description":"
Poll this endpoint after triggering outline generation (POST) until
status is \"done\". Pass the ``auto_generate_order_id`` returned by POST
as a query parameter.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Content brief order ID.","in":"path","name":"order_id","required":true,"type":"string"},{"description":"The auto_generate_order_id returned by the POST outline endpoint.","in":"query","name":"auto_generate_order_id","required":true,"type":"string"}],"responses":{"200":{"description":"Outline items payload.","schema":{"properties":{"content_brief_id":{"type":"string"},"list":{"items":{"type":"object"},"type":"array"},"status":{"description":"True if outline generation is complete (\"done\").","example":true,"type":"boolean"},"string":{"description":"Concatenated outline string.","type":"string"}},"type":"object"}},"400":{"description":"Invalid request data."},"401":{"description":"Unauthorized."},"403":{"description":"Insufficient permissions."}},"summary":"Get AI Outline status and items for Content Brief.","tags":["Content Brief"]},"post":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Content brief order ID.","in":"path","name":"order_id","required":true,"type":"string"},{"description":"Optional additional context for outline generation. (e.g. \"Focus on comparison with alternative tools.\")","in":"body","name":"body","schema":{"properties":{"additional_context":{"example":"","type":"string"}},"type":"object"}}],"responses":{"200":{"description":"Outline generation task triggered.","schema":{"properties":{"auto_generate_order_id":{"description":"ID of the auto-generated outline order.","type":"string"}},"type":"object"}},"400":{"description":"Invalid request data or task not finished."},"401":{"description":"Unauthorized."},"403":{"description":"Subscription paused or insufficient permissions."}},"summary":"Generate AI Outline for existing Content Brief.","tags":["Content Brief"]}},"/api/content-brief/orders/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Page number (1-indexed, default 1).","in":"query","name":"page","required":false,"type":"integer"},{"description":"Number of orders per page (default 10, max 100).","in":"query","name":"page_size","required":false,"type":"integer"}],"responses":{"200":{"description":"Paginated list of content brief orders.","schema":{"properties":{"payload":{"properties":{"orders":{"items":{"type":"object"},"type":"array"},"page":{"type":"integer"},"page_size":{"type":"integer"},"total_orders":{"type":"integer"},"total_pages":{"type":"integer"}},"type":"object"},"status":{"type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Get the list of Content Briefs (paginated).","tags":["Content Brief"]}},"/api/keyword-content/order/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order unique identifier, that was issued upon order creation. **example: 2879fa0b-deae-4aab-ad87-fd8fb8db9717**\n","in":"query","name":"order_id","required":true,"type":"string"}],"responses":{"200":{"description":"Order status.","schema":{"properties":{"order_id":{"description":"Id of the order.","type":"string"},"results":{"properties":{"files":{"properties":{"csv":{"description":"Download links of the reports csv files.","properties":{"meta_descriptions":{"type":"string"},"meta_titles":{"type":"string"},"paa":{"type":"string"},"quora_questions":{"type":"string"},"reddit_questions":{"type":"string"}},"type":"object"}},"type":"object"},"meta_descriptions":{"items":{"type":"string"},"type":"array"},"meta_titles":{"items":{"type":"string"},"type":"array"},"paa":{"items":{"type":"string"},"type":"array"},"quora_questions":{"items":{"type":"string"},"type":"array"},"reddit_questions":{"items":{"type":"string"},"type":"array"}},"type":"object"},"status":{"description":"Current status of the order.","enum":["created","done"],"type":"string"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Check keyword content order status. Parameters accepted as JSON object.","tags":["Keyword Content"]},"post":{"description":"as sum of cost per insight selected
paa - 1 c
reddit_questions - 2 c
quora_questions - 2 c
meta_titles - 100 c
meta_descriptions - 100 c
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"```keyword*```: Target query (keyword).\n\n```language*```: Language code to use for SERP results scraping. To get available languages use\n the /api/keywords-insights/languages/ endpoint from insights API.\n\n```location*```: Location name to use for SERP results scraping.To get available locations use\n the /api/keywords-insights/locations/ and /api/keywords-insights/locations-live/some_locations/\n endpoint from insights API.\n\n```content_insights*```: The types of keyword content insights to perform within the order. The API call cost calculated\n as sum of cost per insight selected\n paa - 50 c\n reddit_questions - 50 c\n quora_questions - 50 c\n meta_titles - 200 c\n meta_descriptions - 200 c\n [\"paa\", \"reddit_questions\", \"meta_titles\", \"meta_descriptions\", \"quora_questions\"]\n\n**device**: The device for the SERP scraping. [\"desktop\", \"mobile\"]\n","in":"body","name":"body","schema":{"$ref":"#/definitions/CreateKeywordContentOrder"}}],"responses":{"200":{"description":"The result of creating of the order in the system.","schema":{"properties":{"cost":{"description":"Amount of credits spent from users account to create the order.","type":"integer"},"order_id":{"description":"Id of created order.","type":"string"},"status":{"description":"The status of the order creation. True if order created successfully.","type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Create the keyword content order in KWI system. Parameters accepted as JSON object. The API call cost calculated","tags":["Keyword Content"]}},"/api/keyword-discovery/languages/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"Languages fetched successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"items":{"properties":{"code":{"example":"en","type":"string"},"name":{"example":"English","type":"string"}},"type":"object"},"type":"array"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"401":{"description":"User is unauthorised"},"403":{"description":"User does not have the public API permissions"}},"summary":"List languages supported by keyword discovery.","tags":["Keyword Discovery"]}},"/api/keyword-discovery/locations/":{"get":{"description":"
The full list is large; prefer /api/keyword-discovery/locations/{search}/
to search for a specific location.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"Locations fetched successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"items":{"properties":{"code":{"example":"us","type":"string"},"name":{"example":"United States","type":"string"}},"type":"object"},"type":"array"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"401":{"description":"User is unauthorised"},"403":{"description":"User does not have the public API permissions"}},"summary":"List locations supported by keyword discovery.","tags":["Keyword Discovery"]}},"/api/keyword-discovery/locations/{location_input}/":{"get":{"description":"
Returns up to 10 fuzzy matches for the given input.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Location name (or part of it) to search for","example":"united","in":"path","name":"location_input","required":true,"type":"string"}],"responses":{"200":{"description":"Matching locations fetched successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"items":{"properties":{"code":{"example":"us","type":"string"},"name":{"example":"United States","type":"string"}},"type":"object"},"type":"array"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"401":{"description":"User is unauthorised"},"403":{"description":"User does not have the public API permissions"}},"summary":"Search locations supported by keyword discovery.","tags":["Keyword Discovery"]}},"/api/keyword-discovery/order/":{"post":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"properties":{"folder_id":{"description":"The folder ID where the keyword discovery order will be saved. This is typically a UUID v4.\n\n**How to retrieve folder_id:**\n- Navigate to the folder in the KWI dashboard (app.keywordinsights.ai)\n- The folder_id is visible in the browser URL when viewing a folder\n- Example URL format: `https://app.keywordinsights.ai/orders/folders/personal/{folder_id}/...`\n- Copy the folder_id from the URL path\n- If not provided, the order will be saved to the user's default folder (user ID) on the legacy workspace.\n\n**How folder_id is used:**\n- Organizes keyword discovery orders within your workspace\n- Associates orders with domain-specific settings if the folder is linked to a domain\n- Enables filtering and organization of projects by workspace/domain context\n- Pulls relevant workspace information such as domain language, location, and other domain-specific configurations\n","type":"string"},"language":{"default":"en","description":"ISO 639-1 language code","example":"en","type":"string"},"location":{"default":"United States","description":"Human-readable location name, see /api/keyword-discovery/locations/ for available locations","example":"United States","type":"string"},"seed_keyword":{"description":"The main keyword for order","example":"content marketing strategies","type":"string"}},"required":["language","location","seed_keyword"],"type":"object"}}],"responses":{"201":{"description":"Resource created successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"properties":{"folder":{"description":"Folder UUID, nullable","example":null,"format":"uuid","type":"string"},"id":{"example":"339ca10b-80c1-4248-b8d0-c11377c204c7","format":"uuid","type":"string"},"language":{"example":"en","type":"string"},"location":{"example":"us","type":"string"},"location_name":{"example":"United-States","type":"string"},"order_type":{"example":"google_autocomplete","type":"string"},"processing_status":{"properties":{"enrich_status":{"example":"done","type":"string"},"google_autocomplete_status":{"example":"processing","type":"string"},"google_search_console_status":{"example":"processing","type":"string"},"people_also_ask_status":{"example":"processing","type":"string"},"quora_status":{"example":"processing","type":"string"}},"type":"object"},"property":{"example":"content marketing strategies","type":"string"},"seed_keyword":{"example":"content marketing strategies","type":"string"},"status":{"example":"created","type":"string"}},"type":"object"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Create a keyword discovery order.","tags":["Keyword Discovery"]}},"/api/keyword-discovery/order/{order_id}/":{"delete":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order UUID returned by the create-order endpoint","format":"uuid","in":"path","name":"order_id","required":true,"type":"string"}],"responses":{"200":{"description":"Order deleted successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"properties":{"status":{"example":"deleted","type":"string"}},"type":"object"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"400":{"description":"Invalid request data (e.g. order_id is not a valid UUID)"},"401":{"description":"User is unauthorised"},"403":{"description":"User is not the owner of this order"},"404":{"description":"Order not found"}},"summary":"Delete a keyword discovery order.","tags":["Keyword Discovery"]},"get":{"description":"
Orders are processed asynchronously. Poll this endpoint until
`payload.status` is `done` (or `error`); per-source progress is
reported in `payload.processing_status`.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order UUID returned by the create-order endpoint","format":"uuid","in":"path","name":"order_id","required":true,"type":"string"}],"responses":{"200":{"description":"Order details fetched successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"properties":{"folder":{"description":"Folder info, nullable","example":null,"type":"object"},"id":{"example":"339ca10b-80c1-4248-b8d0-c11377c204c7","format":"uuid","type":"string"},"keywords":{"description":"Preview of the first keywords; use the keywords endpoint for the full list","items":{"properties":{"competition":{"format":"float","type":"number"},"cpc":{"format":"float","type":"number"},"id":{"format":"uuid","type":"string"},"keyword":{"type":"string"},"source":{"type":"string"},"volume":{"type":"integer"}},"type":"object"},"type":"array"},"language":{"example":"en","type":"string"},"location":{"example":"us","type":"string"},"location_name":{"example":"United-States","type":"string"},"n_keywords":{"description":"Total number of keywords discovered so far","example":250,"type":"integer"},"order_type":{"example":"google_autocomplete","type":"string"},"processing_status":{"properties":{"enrich_status":{"example":"done","type":"string"},"google_autocomplete_status":{"example":"processing","type":"string"},"google_search_console_status":{"example":"processing","type":"string"},"people_also_ask_status":{"example":"processing","type":"string"},"quora_status":{"example":"processing","type":"string"}},"type":"object"},"property":{"example":"content marketing strategies","type":"string"},"seed_keyword":{"example":"content marketing strategies","type":"string"},"seed_keyword_data":{"description":"Keyword metrics for the seed keyword, nullable","type":"object"},"status":{"description":"Poll until this is `done` (or `error`)","enum":["created","processing","done","error"],"example":"processing","type":"string"}},"type":"object"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"400":{"description":"Invalid request data (e.g. order_id is not a valid UUID)"},"401":{"description":"User is unauthorised"},"403":{"description":"User does not have access to this order"},"404":{"description":"Order not found"}},"summary":"Get keyword discovery order details and processing status.","tags":["Keyword Discovery"]}},"/api/keyword-discovery/order/{order_id}/keywords":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order UUID to fetch order keywords","format":"uuid","in":"path","name":"order_id","required":true,"type":"string"},{"default":"volume","description":"Field to sort results by","enum":["keyword","source","volume","cpc","competition"],"in":"query","name":"sort_by","required":false,"type":"string"},{"default":"desc","description":"Sort order","enum":["asc","desc"],"in":"query","name":"sort_order","required":false,"type":"string"},{"default":false,"description":"Include hidden keywords","in":"query","name":"include_hidden","required":false,"type":"boolean"},{"description":"Single keyword source","in":"query","name":"source","required":false,"type":"string"},{"collectionFormat":"multi","description":"Filter by multiple sources (?sources=a&sources=b)","in":"query","items":{"enum":["seed_keyword","google_autocomplete","google_related_searches","people_also_ask","quora","reddit","google_search_console","generated_keywords"],"type":"string"},"name":"sources","required":false,"type":"array"},{"collectionFormat":"multi","description":"Include keywords containing these terms","in":"query","items":{"type":"string"},"name":"keywords_included","required":false,"type":"array"},{"collectionFormat":"multi","description":"Exclude keywords containing these terms","in":"query","items":{"type":"string"},"name":"keywords_excluded","required":false,"type":"array"},{"default":50,"description":"Number of items per page","in":"query","name":"page_size","required":false,"type":"integer"},{"default":1,"description":"Page number","in":"query","name":"page_number","required":false,"type":"integer"},{"description":"Minimum search volume","in":"query","name":"volume_from","required":false,"type":"integer"},{"description":"Maximum search volume","in":"query","name":"volume_to","required":false,"type":"integer"},{"description":"Minimum CPC","format":"float","in":"query","name":"cpc_from","required":false,"type":"number"},{"description":"Maximum CPC","format":"float","in":"query","name":"cpc_to","required":false,"type":"number"},{"description":"Minimum competition value","format":"float","in":"query","name":"competition_from","required":false,"type":"number"},{"description":"Maximum competition value","format":"float","in":"query","name":"competition_to","required":false,"type":"number"},{"default":"all","description":"Competition category","enum":["all","low","medium","high"],"in":"query","name":"competition_cat","required":false,"type":"string"},{"description":"Minimum CTR","format":"float","in":"query","name":"ctr_from","required":false,"type":"number"},{"description":"Maximum CTR","format":"float","in":"query","name":"ctr_to","required":false,"type":"number"},{"description":"Minimum clicks","in":"query","name":"clicks_from","required":false,"type":"integer"},{"description":"Maximum clicks","in":"query","name":"clicks_to","required":false,"type":"integer"},{"description":"Minimum SERP position","format":"float","in":"query","name":"position_from","required":false,"type":"number"},{"description":"Maximum SERP position","format":"float","in":"query","name":"position_to","required":false,"type":"number"},{"description":"Minimum impressions","in":"query","name":"impressions_from","required":false,"type":"integer"},{"description":"Maximum impressions","in":"query","name":"impressions_to","required":false,"type":"integer"}],"responses":{"200":{"description":"Keywords list fetched successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"properties":{"list":{"items":{"properties":{"clicks":{"type":"integer"},"competition":{"format":"float","type":"number"},"competition_cat":{"type":"string"},"cpc":{"format":"float","type":"number"},"ctr":{"format":"float","type":"number"},"id":{"format":"uuid","type":"string"},"impressions":{"type":"integer"},"is_hidden":{"type":"boolean"},"is_selected":{"type":"boolean"},"keyword":{"type":"string"},"order_id":{"format":"uuid","type":"string"},"position":{"format":"float","type":"number"},"relevancy_score":{"format":"float","type":"number"},"source":{"type":"string"},"status":{"type":"string"},"trends":{"items":{"properties":{"month":{"type":"string"},"timestamp":{"type":"integer"},"value":{"type":"integer"},"year":{"type":"integer"}},"type":"object"},"type":"array"},"volume":{"type":"integer"}},"type":"object"},"type":"array"},"total_list_length":{"type":"integer"}},"type":"object"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"400":{"description":"Invalid request data"},"401":{"description":"User is unauthorised"},"403":{"description":"User does not have the public API permissions"}},"summary":"Get keywords by order with filters and sorting.","tags":["Keyword Discovery"]}},"/api/keyword-discovery/orders/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Field to sort results by","enum":["seed_keyword","created_date"],"in":"query","name":"sort_by","required":false,"type":"string"},{"default":"asc","description":"Sort order","enum":["asc","desc"],"in":"query","name":"sort_order","required":false,"type":"string"},{"description":"Filter orders by seed keyword","in":"query","name":"search_query","required":false,"type":"string"},{"default":1,"description":"Page number","in":"query","name":"page_number","required":false,"type":"integer"},{"default":10,"description":"Number of items per page (max 10001). Note the default is 10, unlike the keywords endpoint's 50.","in":"query","name":"page_size","required":false,"type":"integer"}],"responses":{"200":{"description":"Orders list fetched successfully","schema":{"properties":{"error":{"example":null,"type":"string"},"payload":{"properties":{"list":{"items":{"properties":{"created_date":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"language":{"type":"string"},"location":{"type":"string"},"location_name":{"type":"string"},"n_keywords":{"type":"integer"},"order_type":{"type":"string"},"seed_keyword":{"type":"string"},"status":{"enum":["created","processing","done","error"],"type":"string"},"updated_date":{"format":"date-time","type":"string"}},"type":"object"},"type":"array"},"total_list_length":{"type":"integer"}},"type":"object"},"status":{"example":true,"type":"boolean"}},"type":"object"}},"401":{"description":"User is unauthorised"},"403":{"description":"User does not have the public API permissions"}},"summary":"List your keyword discovery orders.","tags":["Keyword Discovery"]}},"/api/keywords-insights/languages/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"List of language objects.","schema":{"properties":{"code":{"description":"Code of supported language.","type":"string"},"insights":{"description":"List of insights which support current language.","items":{"name":"insight","type":"string"},"type":"array"},"name":{"description":"Name of supported language.","type":"string"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Get the list of objects with languages supported by different insights.","tags":["Keyword Insights"]}},"/api/keywords-insights/locations-live/{input}/":{"get":{"description":"interacting with the API. Parameters accepted as URL string.
Example: /api/keywords-insights/locations-live//
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"String to match the suggested locations to.","in":"path","name":"input","required":true,"type":"string"}],"responses":{"200":{"description":"List of language objects.","schema":{"properties":{"code":{"description":"Code of supported location.","type":"string"},"name":{"description":"Name of supported location.","type":"string"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Get suggested locations for user input. This method is useful if you are going to create the dynamic UI for","tags":["Keyword Insights"]}},"/api/keywords-insights/locations/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"List of locations objects.","schema":{"properties":{"code":{"description":"Code of supported location.","type":"string"},"name":{"description":"Name of supported location.","type":"string"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Get list of locations available for insights orders.","tags":["Keyword Insights"]}},"/api/keywords-insights/order/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order unique identifier, that was issued upon order creation. **example: 2879fa0b-deae-4aab-ad87-fd8fb8db9717**\n","in":"query","name":"order_id","required":true,"type":"string"}],"responses":{"200":{"description":"Order status.","schema":{"properties":{"order_id":{"description":"Id of the order.","type":"string"},"progress":{"description":"Order processing progress. From 0 to 1.","type":"number"},"results_files":{"properties":{"google_sheets":{"description":"Sharing link to the Google Sheets report file","type":"string"},"google_sheets_id":{"description":"The id of google sheets report.","type":"string"},"xlsx":{"description":"Download link of the report xlsx file.","type":"string"}},"type":"object"},"status":{"description":"Current status of the order.","type":"string"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Check insights order status. Parameters accepted as JSON object.","tags":["Keyword Insights"]},"post":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"```project_name*```: Name of the project for easier identification in the keywordinsights.ai UI.\n\n```keywords*```: List of keywords. [\"keyword 1\", \"keyword 2\", \"keyword 3\"]\n\n```search_volumes*```: List of search volumes. [213, 1561, 616] Or any data really doesn't matter, as that is always provided by the user\n\n```language*```: Language code to use for SERP results scraping.\n\n```location*```: Location name to use for SERP results scraping.\n\n```insights*```: The types of insights to perform within the order (**cluster required**).\n\n**clustering_method**: The method to be used for grouping the keywords into clusters.\n\n**grouping_accuracy**: Parameter used with clustering method \"volume\". Describes minimum number of SERP URLs\n in common between every keyword in cluster and cluster lead keyword.\n\n**hub_creation_method**: Describes the level of similarity of keywords within the cluster for the HUB algorithm.\n\n**device**: The device for the SERP scraping.\n\n**mobile_type**: The type of mobile device. Applied if device=mobile.\n\n**tablet_type**: The type of tablet device. Applied if device=tablet.\n\n**url**: The url for ranking. Required if \"rank\" is specified within the \"insights\" property.\n\n**folder_id**: The folder id of which the project will be saved, usually is a UUID v4.\n","in":"body","name":"body","schema":{"$ref":"#/definitions/CreateOrder"}}],"responses":{"200":{"description":"The result of creating of the order in the system.","schema":{"properties":{"cost":{"description":"Amount of credits spent from users account to create the order.","type":"integer"},"order_id":{"description":"Id of created order.","type":"string"},"status":{"description":"The status of the order creation. True if order created successfully.","type":"boolean"}}}},"400":{"description":"Invalid request data. The error message names the offending field (missing key, wrong type, mismatched lengths, unsupported value)."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Create the insights order in KWI system. Parameters accepted as JSON object.","tags":["Keyword Insights"]}},"/api/keywords-insights/order/cost/":{"get":{"description":"Parameters accepted as JSON object.
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Number of keywords. **example: 2**\n","in":"query","name":"n_keywords","required":true,"type":"integer"},{"description":"The types of insights to perform within the order. Some from [cluster, rank, context] **example: cluster**\n","enum":["cluster","rank","context"],"in":"query","name":"insights","required":true,"schema":{"items":{"type":"string"},"type":"array"}}],"responses":{"200":{"description":"Estimated cost of the order.","schema":{"properties":{"cost":{"description":"Number of credits that will be used to run the order.","type":"integer"}}}},"400":{"description":"Invalid request data"},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Check the cost of the insights order. Needed for estimation of the order cost before creating the order.","tags":["Keyword Insights"]}},"/api/keywords-insights/order/json/{order_id}/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order UUID (returned when the order was created)","in":"path","name":"order_id","required":true,"type":"string"},{"default":50,"description":"Number of rows per page (max 1000)","in":"query","name":"page_size","required":false,"type":"integer"},{"default":1,"description":"Page number starting from 1","in":"query","name":"page_number","required":false,"type":"integer"},{"default":"search_volume","description":"Sort field (e.g. search_volume, keyword, cluster_id)","in":"query","name":"sort_by","required":false,"type":"string"},{"default":false,"description":"Sort direction. false = descending","in":"query","name":"ascending","required":false,"type":"boolean"},{"description":"Filter ID. Can be obtained from the filters endpoint.","in":"query","name":"filter_id","required":false,"type":"string"}],"responses":{"200":{"description":"Paginated cluster data for the order.","schema":{"properties":{"clusters":{"description":"List of cluster objects","items":{"properties":{"ai_overview":{"nullable":true,"properties":{"ai_overview_data":{"items":{"properties":{"text":{"type":"string"},"title":{"type":"string"}},"type":"object"},"type":"array"},"urls":{"items":{"type":"string"},"type":"array"}},"type":"object"},"cluster_id":{"type":"string"},"difficulty_score":{"type":"number"},"dominant_intent":{"type":"string"},"intent_explanation":{"type":"string"},"keywords":{"items":{"properties":{"content_brief_order_id":{"type":"string"},"dominant_intent":{"type":"string"},"is_lead_keyword":{"type":"boolean"},"keyword":{"type":"string"},"keyword_id":{"type":"string"},"opportunity":{"type":"number"},"rank":{"type":"number"},"ranks_lists":{"items":{"type":"integer"},"type":"array"},"score":{"type":"number"},"search_volume":{"type":"integer"},"serp_explorer_order_id":{"type":"string"},"url":{"type":"string"},"urls_lists":{"items":{"type":"string"},"type":"array"},"writer_agent_order_id":{"type":"string"},"writer_assistant_order_id":{"type":"string"}},"type":"object"},"type":"array"},"label":{"type":"string"},"name":{"type":"string"},"number_of_keywords":{"type":"integer"},"opportunity_score":{"type":"number"},"priority_score":{"type":"number"},"rank":{"type":"number"},"score":{"type":"number"},"search_volume":{"type":"integer"},"serp_features":{"items":{"type":"string"},"type":"array"},"url":{"nullable":true,"type":"string"}},"type":"object"},"type":"array"},"currentPage":{"type":"integer"},"keywords_suggestion":{"items":{"type":"string"},"type":"array"},"n_clusters":{"description":"Clusters on current page","type":"integer"},"n_keywords":{"description":"Keywords on current page","type":"integer"},"n_pages":{"type":"integer"},"n_total_clusters":{"type":"integer"},"n_total_keywords":{"type":"integer"},"nextPage":{"nullable":true,"type":"integer"},"remaining_clusters":{"type":"integer"}},"type":"object"}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized"},"403":{"description":"User does not have the public API permissions"},"404":{"description":"Order not found"}},"summary":"Get clustered (paginated) keyword data for an order.","tags":["Keyword Insights"]}},"/api/keywords-insights/order/xlsx/{order_id}/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"ID of the order to export","in":"path","name":"order_id","required":true,"type":"string"}],"produces":["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/json"],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file with insights report"},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Export insights order to xlsx file.","tags":["Keyword Insights"]}},"/api/keywords-insights/orders/":{"get":{"description":"Parameters accepted as JSON object.
Examples:
{
\"n_orders\": None,
\"n_days\": 5
}
{
\"n_orders\": 5,
\"n_days\": None
}
","parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Number of last orders to fetch. Do not use n_days with this parameter. **example: 2**\n","in":"query","name":"n_orders","type":"integer"},{"description":"Number of last days to fetch. Do not use n_orders with this parameter. **example: 2**\n","in":"query","name":"n_days","type":"integer"}],"responses":{"200":{"description":"List of order objects.","schema":{"properties":{"orders":{"items":{"type":"object"},"type":"array"}}}},"400":{"description":"Invalid request data"},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Fetch the orders posted to the system. N last orders and N last days available.","tags":["Keyword Insights"]}},"/api/user/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"User data","schema":{"properties":{"result":{"properties":{"balance":{"type":"integer"},"balance_subscription":{"type":"integer"},"balance_top_up":{"type":"integer"},"content_briefs_data":{"properties":{"content_briefs_allowed":{"description":"Number of Content Briefs runs available for user","type":"integer"},"content_briefs_used":{"description":"Number of Content Briefs runs used","type":"integer"}},"type":"object"},"email":{"type":"string"},"has_cc_linked":{"description":"Identifies either user has credit card information linked to their account","type":"boolean"},"id":{"type":"string"},"kwd_data":{"properties":{"kwd_searches_allowed":{"description":"Number of Keyword Discovery runs available for user","type":"integer"},"kwd_searches_used":{"description":"Number of Keyword Discovery runs used","type":"integer"}},"type":"object"},"last_name":{"type":"string"},"name":{"type":"string"},"organisation_data":{"properties":{"is_org_admin":{"description":"Identifies either user is an organisation administrator","type":"boolean"},"organisation_id":{"type":"string"},"user_seats_allowed":{"description":"Number of user seats allowed in users organisation","type":"integer"},"user_seats_used":{"description":"Number of members of users organisation","type":"integer"}},"type":"object"},"phone":{"type":"string"},"stripe_data":{"properties":{"credits_rollover_date":{"description":"Date of credits rollover in milliseconds","type":"integer"}},"type":"object"}},"type":"object"}}}}},"summary":"Get the user data","tags":["User"]}},"/api/writer-agent/options/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"Available options for POV, tone of voice, content types.","schema":{"properties":{"error":{"nullable":true,"type":"object"},"payload":{"properties":{"content_types":{"description":"Available content type options","example":["article","landing_page"],"items":{"type":"string"},"type":"array"},"points_of_view":{"description":"Available point of view options","example":["first_person","second_person","third_person"],"items":{"type":"string"},"type":"array"},"tones_of_voice":{"description":"Available tone of voice presets","items":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"status":{"example":true,"type":"boolean"}}}},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Get writer agent options.","tags":["Writer Agent"]}},"/api/writer-agent/order/":{"get":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Order unique identifier (UUID).","example":"550e8400-e29b-41d4-a716-446655440000","in":"query","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"Order details including generated outline/plan/article.","schema":{"properties":{"error":{"nullable":true,"type":"object"},"payload":{"properties":{"generated_article":{"description":"Full AI-generated article","nullable":true,"type":"string"},"id":{"description":"Order UUID","type":"string"},"keyword":{"type":"string"},"processing_status":{"description":"Current processing status for each stage","type":"object"},"status":{"description":"Overall order status","type":"string"}},"type":"object"},"status":{"example":true,"type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Get a writer agent order.","tags":["Writer Agent"]},"post":{"parameters":[{"description":"API key (e.g. kwi_sk_...). Generate one at https://app.keywordinsights.ai.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"properties":{"additional_insights":{"description":"Additional context or instructions for the AI","example":"Focus on B2B companies and include case studies","type":"string"},"content_type":{"default":"article","description":"Type of content to generate","enum":["article","landing_page"],"example":"article","type":"string"},"folder_id":{"description":"The folder ID where the writer agent order will be saved. This is typically a UUID v4.\n\n**How to retrieve folder_id:**\n- Navigate to the folder in the KWI dashboard (app.keywordinsights.ai)\n- The folder_id is visible in the browser URL when viewing a folder\n- Example URL format: `https://app.keywordinsights.ai/orders/folders/personal/{folder_id}/...`\n- Copy the folder_id from the URL path\n- If not provided, the order will be saved to the user's default folder (user ID) on the legacy workspace.\n\n**How folder_id is used:**\n- Organizes writer agent orders within your workspace\n- Associates orders with domain-specific settings if the folder is linked to a domain\n- Enables filtering and organization of projects by workspace/domain context\n- Pulls relevant workspace information such as domain language, location, and other domain-specific configurations\n","type":"string"},"keyword":{"description":"The main keyword/topic for the article","example":"content marketing strategies","type":"string"},"language_code":{"default":"en","description":"ISO 639-1 language code","example":"en","type":"string"},"location_name":{"default":"United States","description":"Human-readable location name, see /api/keywords-insights/locations/ for available locations","example":"United States","type":"string"},"point_of_view":{"default":"First person (I/We)","description":"Point of view for the article","enum":["First person (I/We)","Second Person (You)","Third Person (He/She/They/It)"],"example":"First person (I/We)","type":"string"}},"required":["keyword","language_code","location_name"],"type":"object"}}],"responses":{"201":{"description":"Writer agent order created successfully.","schema":{"properties":{"error":{"nullable":true,"type":"object"},"payload":{"properties":{"id":{"description":"Order UUID","type":"string"},"keyword":{"type":"string"},"language_code":{"type":"string"},"processing_status":{"description":"Current processing status for each stage","type":"object"}},"type":"object"},"status":{"example":true,"type":"boolean"}}}},"400":{"description":"Invalid request data."},"401":{"description":"User is unauthorised. Use authentication endpoint to get bearer token."},"403":{"description":"User does not have the public API permissions. Upgrade account, or contact sales."}},"summary":"Create a writer agent order.","tags":["Writer Agent"]}},"/authentication/login/":{"post":{"description":"Parameters accepted as JSON object.
The headers object:
{
\"Connection\": \"keep-alive\",
\"Pragma\": \"no-cache\",
\"Accept\": \"application/json, text/plain, */*\",
\"Authorization\": \"Bearer {token}\"
}
Headers with bearer token required for every API request except /authentication/login/
","parameters":[{"description":"```email*```: Email is used as user id during registration\n\n```password*```: User password\n","in":"body","name":"body","schema":{"$ref":"#/definitions/Authentication"}}],"responses":{"200":{"description":"Authentication success","schema":{"properties":{"result":{"properties":{"access_token":{"type":"string"},"logged_in_as":{"type":"string"},"refresh_token":{"type":"string"}},"type":"object"}}}},"429":{"description":"Too many requests or too many failed login attempts"}},"summary":"Authentication endpoint to get the bearer token to include in API calls headers.","tags":["Authentication"]}}},"schemes":["https"],"security":[{"ApiKeyAuth":[]}],"securityDefinitions":{"ApiKeyAuth":{"description":"API key (e.g. kwi_sk_...). Generate one from the Keyword Insights dashboard.","in":"header","name":"X-API-Key","type":"apiKey"},"BearerAuth":{"description":"Bearer token (deprecated \u2014 use API key instead).","in":"header","name":"Authorization","type":"apiKey"}},"swagger":"2.0","uiversion":3}