NeuronWriter API - how to use
Introduction
NeuronWriter API gives you programatic access to our recommendations. With it you can for instance:
Add new queries in bulk and retrieve the share URLs
Integrate NeuronWriter recommendations in your content generation process
This is a very first alpha version of our API. If you face any issues or have any thoughts on how we can improve our API, please add your feedback. Thank you!
The quickest way to start might be to jump straight to the usage examples at the end of these docs.
Requirements / costs
This feature requires Gold plan or higher.
API requests consume your monthly limits (there is no difference whether you create a new query via NeuronWriter interface or API, the cost is the same)
It is advised to have a basic understanding of how APIs/HTTP requests work and a bit of experience in your favorite programming language (Python, PHP, Java, ...)
How to obtain your API key?
Open your profile, visit the "Neuron API access" tab and copy your API key:
API access:
API endpoint:
Please use the following API endpoint:
https://app.neuronwriter.com/neuron-api/0.5/writer (+ API method)
Authentication:
Each request to the API has to include the X-API-KEY HTTP header with your Neuron API key.
API methods
The first version includes two basic methods creating queries and generating content recommendations
/new-query
Creates a new content writer query for a given keyword, language and search engine.
Parameters:
parameter | example value | description |
---|---|---|
project | e95fdd229fd98c10 | The ID of your project taken from project's URL: https://app.neuronwriter.com/project/view/75a454f6ae5976e8 -> e95fdd229fd98c10 |
keyword | trail running shoes | The keyword you want to generate a query (and recommendations) for. |
engine | google.co.uk | Preferred search engine. |
language | English | Content language. |
Response:
key | example value | description |
---|---|---|
query | 32dee2a89374a722 | The ID of your new query. |
query_url | https://app.neuronwriter.com/analysis/view/32dee2a89374a722 | The URL of your query (accessible from browser) |
share_url | https://app.neuronwriter.com/analysis/share/32dee2a89374a722/c63b64f6b13a064c12b78dac7dc3410c1 | URL for sharing the query (with edit&save access) |
readonly_url | https://app.contadu.com/analysis/content-preview/32dee2a89374a722/02db6ba3e78557302723220bdef73c771 | URL for sharing the query (readonly preview) |
/get-query
Retrieves content recommendations for a given query. Any query, doesn't have to be created via API.
After creating a new query with /new-query request it usually takes around 60 seconds until we prepare the recommendations.
With /get-query request you can check whether we've finished the analysis (status=='ready') and if we did, the recommendations are available in the response.
Parameters:
parameter | example value | description |
---|---|---|
query | 32dee2a89374a722 | The ID of your query. |
Response:
key | example value | description |
---|---|---|
status | ready | Whether your query has already been processed. Possible values include: not found, waiting, in progress, ready If status=='ready', keys below are added too. |
metrics | {'word_count': {'median': 1864, 'target': 1864}, 'readability': {'median': 40, 'target': 40}} | General recommendations such as typical content length. |
terms_txt | {'title': 'running shoe\nwinter running shoe\nbest winter running shoe\nwinter running shoes of 2024', 'desc_title': 'running shoe\nwinter running shoe\nbest winter running shoe\ntraction\nbest pairs\nwinter running shoes of 2024\n2024\ntrail running\nshoes for running\nrunning in the winter\nfeet warm\nwinter shoes', 'h1': 'running shoe... | Content term suggestions (title, desc, h1, h2, content_basic, content_extended) in text format. Good to be used for Chat GPT prompts, etc. |
terms | {'title': [{'t': 'running shoe', 'usage_pc': 88}, {'t': 'winter running shoe', 'usage_pc': 75}, {'t': 'best winter running shoe', 'usage_pc': 62}, {'t': 'winter running shoes of 2024', 'usage_pc': 50}], 'desc': [{'t': 'running shoe', 'usage_pc': 25}, {'t': 'winter running shoe', 'usage_pc': 25}, {'t': 'best winter running shoe', 'usage_pc': 25}, ... 'content_basic': [{'t': 'running shoe', 'usage_pc': 88, 'sugg_usage': [1, 32]}, {'t': 'winter running shoe', 'usage_pc': 88, 'sugg_usage': [1, 9]}, {'t': 'best winter running shoe', 'usage_pc': 75, 'sugg_usage': [1, 2]}, {'t': 'winter running shoes of 2024', 'usage_pc': 50, 'sugg_usage': [1, 1]}, {'t': '2024', 'usage_pc': 75, 'sugg_usage': [1, 2]}, {'t': 'traction', 'usage_pc': 62, 'sugg_usage': [1, 16]}, {'t': 'outsole', 'usage_pc': 62, 'sugg_usage': [1, 19]}, ... | Detailed information about the content terms. |
/list-queries
Retrieves queries within a project matching your criteria and provides information about their status (whether they're ready, etc.).
Parameters:
parameter | example value | description |
---|---|---|
project | 0c30b6a4f8b2b412 | The ID of your project. |
status | ready | Query status - possible values: waiting, in progress, ready |
source | neuron-api | How was the query created - possible values: neuron, neuron-api |
created | 2024-01-19T14:48:31+00:00 | Creation date for a query |
updated | 2024-01-19T14:49:52+00:00 | Query update (when the query is ready) |
tags | Done | You can limit the results to queries with one or more tags. You can either provide a single tag as a string, e.g.: Done or a list of tags such as (all have to be present): ['MyNewTag', 'Done',] |
Response:
A list of queries:
[{'query': 'a6d0fb2bf9a7a2be', 'created': '2024-01-19T14:48:31+00:00', 'updated': '2024-01-19T14:49:52+00:00', 'source': 'neuron-api', 'tags': ['Done']}, {'query': 'bdc73d8e0057ed8f', 'created': '2024-01-19T14:48:31+00:00', 'updated': '2024-01-19T14:49:52+00:00', 'source': 'neuron-api', 'tags': ['Done']}]
/get-content
Retrieves the last content revision saved for a given query. Any query, doesn't have to be created via API.
You can choose between manually saved revisions (default) or all (including autosave revisions)
Parameters:
parameter | example value | description |
---|---|---|
query | 32dee2a89374a722 | The ID of your query. |
revision_type | all | Whether autosave revisions should be considered or not |
Response:
key | example value | description |
---|---|---|
content | <h1>Top 10 Best Winter Running Shoes of 2024 - Find the Perfect Pair for Cold Weather Runs</h1>\n<p>Winter running shoes are designed to provide the necessary support, comfort, and protection for running in cold and icy conditions. The top winter running shoes of 2024 not only keep your feet warm and dry but also offer traction and stability on slippery surfaces.... | Content in HTML format |
title | Top 10 Best Winter Running Shoes of 2024 - Find the Perfect Pair for Cold Weather Runs | Title |
description | Discover the top 10 best winter running shoes of 2024 for staying warm and steady on your cold weather runs. Find the perfect pair with great traction! | Meta description |
created | 2024-01-19T14:49:52+00:00 | Revision date |
type | manual | Revision type (manual or autosave) |
Usage example (Python 3 + requests library)
Creating a new query:
#coding=utf-8
import json
import requests
API_ENDPOINT = 'https://app.neuronwriter.com/neuron-api/0.5/writer'
API_KEY = 'n-c17ef87a9ab8285ea7ef06064031fad4'
headers = {
"X-API-KEY": API_KEY,
"Accept": "application/json",
"Content-Type": "application/json",
}
### Creating a new query:
payload = json.dumps({
# Project ID can be found in the project's URL: https://app.neuronwriter.com/project/view/c2fe46bce8019bff/optimisation -> c2fe46bce8019bff
"project": "c2fe46bce8019bff",
"keyword": "trail running shoes",
"engine": "google.co.uk",
"language": "English",
})
response = requests.request("POST", API_ENDPOINT + "/new-query", headers=headers, data=payload)
print(response.text)
Output (JSON):
{"query": "79ca6b6b45fb9d67", "query_url": "https://app.neuronwriter.com/analysis/view/79ca6b6b45fb9d67", "share_url": "https://app.neuronwriter.com/analysis/share/79ca6b6b45fb9d67/cceca0f2e01e17e998e72eaa2d4030261562", "readonly_url": "https://app.neuronwriter.com/analysis/content-preview/79ca6b6b45fb9d67/96e0109dea412bb07690999de5cb67ce1562"}
Checking whether your query is ready / printing recommendations:
Use a query ID returned by the /new-query request.
#coding=utf-8
import json
import requests
API_ENDPOINT = 'https://app.neuronwriter.com/neuron-api/0.5/writer'
API_KEY = 'n-c17ef87a9ab8285ea7ef06064031fad4'
headers = {
"X-API-KEY": API_KEY,
"Accept": "application/json",
"Content-Type": "application/json",
}
payload = json.dumps({
"query": "79ca6b6b45fb9d67", # query ID returned by /new-query request
})
response = requests.request("POST", API_ENDPOINT + "/get-query", headers=headers, data=payload)
response_data = response.json()
if response_data['status'] == 'ready': # We've finished the analysis
print('########### word count: ###########')
print(response_data['metrics']['word_count']['target'])
print('########### title terms: ###########')
print(response_data['terms_txt']['title'])
print('########### basic content terms: ###########')
print(response_data['terms_txt']['content_basic'])
print('########### basic content terms with use ranges: ###########')
print(response_data['terms_txt']['content_basic_w_ranges'])
else:
pass # Try again later...
Printed output:
########### word count: ###########
1160
########### title terms: ###########
trail running shoe
best trail running
best trail running shoes
fell running
2024
fell
########### basic content terms: ###########
trail running shoe
trail shoe
salomon
hoka
nike
saucony
cushion
altra
adidas
terrain
asics
gore-tex
peregrine
inov-8
off-road
footwear
gtx
uneven ground
########### basic content terms with use ranges: ###########
trail running shoe: 4-37x
trail shoe: 1-2x
salomon: 1-10x
hoka: 1-17x
nike: 1-8x
saucony: 1-10x
cushion: 1-5x
altra: 1-15x
adidas: 1-5x
terrain: 1-2x
asics: 1-6x
gore-tex: 1-8x
peregrine: 1-5x
inov-8: 1-4x
off-road: 1x
footwear: 1x
gtx: 1-5x
uneven ground: 1x
Getting a list of queries within a project, matching your criteria:
#coding=utf-8
import json
import requests
API_ENDPOINT = 'https://app.neuronwriter.com/neuron-api/0.5/writer'
API_KEY = 'n-c17ef87a9ab8285ea7ef06064031fad4'
headers = {
"X-API-KEY": API_KEY,
"Accept": "application/json",
"Content-Type": "application/json",
}
payload = json.dumps({
"project": "38319e9e7eb7848f",
"status": 'ready',
"source": 'neuron-api',
"tags": ['MyNewTag', 'Done',]
})
response = requests.request("POST", API_ENDPOINT + "/list-queries", headers=headers, data=payload)
response_json = response.json()
print(response_json)
Printed output:
[{'id': '5ecdd5d09a461f58', 'query': '5ecdd5d09a461f58', 'created': '2024-01-19T14:49:52+00:00', 'updated': '2024-01-19T14:49:52+00:00', 'source': 'neuron-api', 'tags': ['Done', 'MyNewTag']}]
Retrieving the last content revision saved for a given query.
#coding=utf-8
import json
import requests
API_ENDPOINT = 'https://app.neuronwriter.com/neuron-api/0.5/writer'
API_KEY = 'n-c17ef87a9ab8285ea7ef06064031fad4'
headers = {
"X-API-KEY": API_KEY,
"Accept": "application/json",
"Content-Type": "application/json",
}
payload = json.dumps({
"query": "79ca6b6b45fb9d67",
})
response = requests.request("POST", API_ENDPOINT + "/get-content", headers=headers, data=payload)
response_json = response.json()
print(response_json)
print('########### title: ###########')
print(response_json['title'])
print('########### description: ###########')
print(response_json['description'])
print('########### HTML content: ###########')
print(response_json['content'])
Printed output:
########### title: ###########
Top 10 Best Winter Running Shoes of 2024 - Find the Perfect Pair for Cold Weather Runs
########### description: ###########
Discover the top 10 best winter running shoes of 2024 for staying warm and steady on your cold weather runs. Find the perfect pair with great traction!
########### HTML content: ###########
<h1>Top 10 Best Winter Running Shoes of 2024 - Find the Perfect Pair for Cold Weather Runs</h1>
<p>Winter running shoes are designed to provide the necessary support, comfort, and protection for running in cold and icy conditions. The top winter running shoes of 2024 not only keep your feet warm and dry but also offer traction and stability on slippery surfaces. These shoes typically feature waterproof membranes, durable outsoles with lugs for enhanced grip, and insulated uppers to shield your feet from the chilly weather.</p>
...
Updated on: 06/02/2024
Thank you!