feat: add NeuronWriter content optimization API subagent#231
feat: add NeuronWriter content optimization API subagent#231marcusquinn merged 2 commits intomainfrom
Conversation
Add curl-based NeuronWriter API subagent for SEO content optimization. Covers all 7 endpoints: list-projects, new-query, get-query, list-queries, get-content, import-content, evaluate-content. Register in subagent-index.toon under seo/ folder.
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the system's SEO capabilities by integrating the NeuronWriter content optimization API. It provides a robust, curl-based subagent that allows users to programmatically interact with NeuronWriter's NLP-driven recommendations, content scoring, and competitor analysis features. This addition streamlines content creation and optimization workflows, enabling more efficient and data-driven SEO strategies. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdds a new NeuronWriter Content Optimization API guide with curl-based endpoint examples, auth instructions, workflows, and error handling; and updates the SEO subagent index to register NeuronWriter as an integrated tool. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new subagent for the NeuronWriter API, providing comprehensive documentation for its endpoints and common workflows. The implementation is well-structured and follows the existing pattern for curl-based subagents. My review focuses on improving the robustness of the example shell scripts in the documentation. I've suggested changes to add error handling and use safer methods for constructing JSON payloads to prevent potential issues with special characters in variables. These improvements will make the example scripts more reliable for users.
| RESULT=$(curl -s -X POST "$NW_API/new-query" "${NW_HEADERS[@]}" \ | ||
| -d '{"project": "YOUR_PROJECT_ID", "keyword": "your keyword", "engine": "google.com", "language": "English"}') | ||
| QUERY_ID=$(echo "$RESULT" | jq -r '.query') | ||
|
|
||
| # 2. Poll until ready (check every 15s, max 5 min) | ||
| for i in $(seq 1 20); do | ||
| STATUS=$(curl -s -X POST "$NW_API/get-query" "${NW_HEADERS[@]}" \ | ||
| -d "{\"query\": \"$QUERY_ID\"}" | jq -r '.status') | ||
| [ "$STATUS" = "ready" ] && break | ||
| sleep 15 | ||
| done | ||
|
|
||
| # 3. Get recommendations | ||
| curl -s -X POST "$NW_API/get-query" "${NW_HEADERS[@]}" \ | ||
| -d "{\"query\": \"$QUERY_ID\"}" | jq '.terms_txt.content_basic' |
There was a problem hiding this comment.
The script for creating a query and polling for results can be made more robust.
- Error Handling: The script doesn't check if
QUERY_IDwas successfully extracted. If the initialcurlcommand fails,QUERY_IDcould be empty ornull, causing subsequent commands to fail. - Timeout Check: The polling loop does not handle the case where the query is not
readyafter 5 minutes. The script will proceed to the next step regardless, which will likely fail. - Safe JSON Payload: Constructing JSON for the
curl -doption by embedding variables in a string is not robust. Usingjqto build the payload is a safer approach.
Here is a suggested revision for this script block:
RESULT=$(curl -s -X POST "$NW_API/new-query" "${NW_HEADERS[@]}" \
-d '{"project": "YOUR_PROJECT_ID", "keyword": "your keyword", "engine": "google.com", "language": "English"}')
QUERY_ID=$(echo "$RESULT" | jq -r '.query')
if [[ -z "$QUERY_ID" || "$QUERY_ID" == "null" ]]; then
echo "Error: Failed to create query. Response:" >&2
echo "$RESULT" >&2
exit 1
fi
# 2. Poll until ready (check every 15s, max 5 min)
for i in $(seq 1 20); do
PAYLOAD=$(jq -n --arg qid "$QUERY_ID" '{query: $qid}')
STATUS=$(curl -s -X POST "$NW_API/get-query" "${NW_HEADERS[@]}" -d "$PAYLOAD" | jq -r '.status')
[ "$STATUS" = "ready" ] && break
sleep 15
done
if [ "$STATUS" != "ready" ]; then
echo "Error: Query did not become ready in 5 minutes. Last status: $STATUS" >&2
exit 1
fi
# 3. Get recommendations
PAYLOAD=$(jq -n --arg qid "$QUERY_ID" '{query: $qid}')
curl -s -X POST "$NW_API/get-query" "${NW_HEADERS[@]}" -d "$PAYLOAD" | jq '.terms_txt.content_basic'| for kw in "${KEYWORDS[@]}"; do | ||
| echo "Creating query for: $kw" | ||
| curl -s -X POST "$NW_API/new-query" "${NW_HEADERS[@]}" \ | ||
| -d "{\"project\": \"$PROJECT\", \"keyword\": \"$kw\", \"engine\": \"google.com\", \"language\": \"English\"}" \ | ||
| | jq -r '.query' | ||
| sleep 2 | ||
| done |
There was a problem hiding this comment.
The bulk analysis script constructs a JSON payload for curl by interpolating variables directly into a string. This is not robust and can fail if a keyword contains special characters like double quotes. It's safer to use a tool like jq to generate the JSON payload, as it will handle escaping correctly.
Here's a revised version of the loop:
| for kw in "${KEYWORDS[@]}"; do | |
| echo "Creating query for: $kw" | |
| curl -s -X POST "$NW_API/new-query" "${NW_HEADERS[@]}" \ | |
| -d "{\"project\": \"$PROJECT\", \"keyword\": \"$kw\", \"engine\": \"google.com\", \"language\": \"English\"}" \ | |
| | jq -r '.query' | |
| sleep 2 | |
| done | |
| for kw in "${KEYWORDS[@]}"; do | |
| echo "Creating query for: $kw" | |
| PAYLOAD=$(jq -n --arg project "$PROJECT" --arg keyword "$kw" --arg engine "google.com" --arg lang "English" '{project: $project, keyword: $keyword, engine: $engine, language: $lang}') | |
| curl -s -X POST "$NW_API/new-query" "${NW_HEADERS[@]}" \ | |
| -d "$PAYLOAD" \ | |
| | jq -r '.query' | |
| sleep 2 | |
| done |
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Mon Jan 26 00:00:54 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
🤖 Augment PR SummarySummary: Adds a new SEO subagent for NeuronWriter’s REST API so users can run content optimization and scoring workflows via curl. Changes:
Technical Notes: Uses the existing “curl-based, no MCP needed” pattern and expects the API key to be provided via 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| 2. Store securely: | ||
|
|
||
| ```bash | ||
| bash ~/.aidevops/agents/scripts/setup-local-api-keys.sh set NEURONWRITER_API_KEY "your_api_key" |
There was a problem hiding this comment.
This setup command points to ~/.aidevops/agents/scripts/setup-local-api-keys.sh, but the repo’s API key helper script is .agent/scripts/setup-local-api-keys.sh (per the existing credentials docs), so the example path likely won’t work as written.
🤖 Was this useful? React with 👍 or 👎
Address review feedback from Gemini Code Assist: - Add null/empty check after query creation - Add timeout check after polling loop - Use jq for JSON payload construction to handle special characters
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @.agent/seo/neuronwriter.md:
- Around line 275-308: Replace the inline bash snippets in
.agent/seo/neuronwriter.md (the setup command using
~/.aidevops/agents/scripts/setup-local-api-keys.sh and the verification curl
that sources ~/.config/aidevops/mcp-env.sh) with file:line references to the
actual implementation files per the progressive disclosure pattern; point
readers to the setup script (~/.aidevops/agents/scripts/setup-local-api-keys.sh)
and the env loader (~/.config/aidevops/mcp-env.sh) locations and the
verification curl example’s implementation/location instead of embedding the
commands, so the doc shows "see file:line" references rather than inline code.
- Around line 1-27: The markdown contains large inline curl examples and
embedded bash workflows that must be converted to progressive-disclosure
references; replace the inline curl examples and the embedded bash script blocks
in the NeuronWriter doc with pointers to the actual implementation files or
subagents (e.g., reference the corresponding curl wrapper or subagent that
implements the NeuronWriter calls and the bash helper script) and ensure the doc
uses file:line or subagent references instead of full inline commands; update
the "NeuronWriter - Content Optimization API" section and any example headings
so they link to the implementation (the inline curl examples and full bash
scripts currently present) and remove the duplicated inline code while
preserving short explanatory notes and a single example pointer.
🧹 Nitpick comments (2)
.agent/seo/neuronwriter.md (2)
227-233: Add error status handling to polling loop.The polling loop exits only on
"ready"but silently continues if the query fails or returns an unexpected status. Consider handling"not found"or other error states to avoid polling indefinitely on failures.♻️ Suggested improvement
# 2. Poll until ready (check every 15s, max 5 min) for i in $(seq 1 20); do STATUS=$(curl -s -X POST "$NW_API/get-query" "${NW_HEADERS[@]}" \ -d "{\"query\": \"$QUERY_ID\"}" | jq -r '.status') [ "$STATUS" = "ready" ] && break + [ "$STATUS" = "not found" ] && echo "Error: Query not found" && exit 1 sleep 15 done +[ "$STATUS" != "ready" ] && echo "Timeout: Query still processing" && exit 1
266-272: Consider adding error handling and rate limit resilience to bulk workflow.The bulk analysis script iterates without checking for failures. A 429 rate limit (documented in error handling section as requiring a 5-minute wait) would cause subsequent requests to fail silently with a 2-second sleep.
♻️ Suggested improvement with basic error handling
for kw in "${KEYWORDS[@]}"; do echo "Creating query for: $kw" - curl -s -X POST "$NW_API/new-query" "${NW_HEADERS[@]}" \ + RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$NW_API/new-query" "${NW_HEADERS[@]}" \ -d "{\"project\": \"$PROJECT\", \"keyword\": \"$kw\", \"engine\": \"google.com\", \"language\": \"English\"}" \ - | jq -r '.query' + ) + HTTP_CODE=$(echo "$RESPONSE" | tail -1) + BODY=$(echo "$RESPONSE" | sed '$d') + if [ "$HTTP_CODE" = "429" ]; then + echo "Rate limited, waiting 5 minutes..." + sleep 300 + continue + fi + echo "$BODY" | jq -r '.query' sleep 2 done
| --- | ||
| description: NeuronWriter content optimization via REST API (curl-based, no MCP needed) | ||
| mode: subagent | ||
| tools: | ||
| read: true | ||
| write: false | ||
| edit: false | ||
| bash: true | ||
| grep: true | ||
| --- | ||
|
|
||
| # NeuronWriter - Content Optimization API | ||
|
|
||
| <!-- AI-CONTEXT-START --> | ||
|
|
||
| ## Quick Reference | ||
|
|
||
| - **Purpose**: SEO content optimization, NLP term recommendations, content scoring, competitor analysis | ||
| - **API**: `https://app.neuronwriter.com/neuron-api/0.5/writer` | ||
| - **Auth**: API key in `X-API-KEY` header, stored in `~/.config/aidevops/mcp-env.sh` as `NEURONWRITER_API_KEY` | ||
| - **Plan**: Gold plan or higher required | ||
| - **Docs**: https://neuronwriter.com/faqs/neuronwriter-api-how-to-use/ | ||
| - **No MCP required** - uses curl directly | ||
|
|
||
| **API requests consume monthly limits** (same cost as using the NeuronWriter UI). | ||
|
|
||
| <!-- AI-CONTEXT-END --> |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
🧩 Analysis chain
🏁 Script executed:
cat -n .agent/seo/neuronwriter.mdRepository: marcusquinn/aidevops
Length of output: 11659
🌐 Web query:
NeuronWriter API latest version 2025 current stable
💡 Result:
NeuronWriter’s latest (and currently documented) stable API version is 0.5 — the API endpoint is:
https://app.neuronwriter.com/neuron-api/0.5/writer
NeuronWriter’s own docs still describe this as a beta API, but 0.5 is the version they publish and support in the current documentation (including during 2025 and as of today, January 26, 2026). [1], [2]
Sources: [1] [2]
API version verified as current. Version 0.5 is the documented stable NeuronWriter API as of January 2026.
Refactor inline code examples to progressive disclosure pattern. Per .agent/**/*.md coding guidelines, replace inline curl examples and bash workflows with file:line references pointing to actual implementation files, or use pointers to subagents. Lines 41–209 contain inline curl examples and lines 216–272 embed full bash scripts that should reference external implementations instead.
🤖 Prompt for AI Agents
In @.agent/seo/neuronwriter.md around lines 1 - 27, The markdown contains large
inline curl examples and embedded bash workflows that must be converted to
progressive-disclosure references; replace the inline curl examples and the
embedded bash script blocks in the NeuronWriter doc with pointers to the actual
implementation files or subagents (e.g., reference the corresponding curl
wrapper or subagent that implements the NeuronWriter calls and the bash helper
script) and ensure the doc uses file:line or subagent references instead of full
inline commands; update the "NeuronWriter - Content Optimization API" section
and any example headings so they link to the implementation (the inline curl
examples and full bash scripts currently present) and remove the duplicated
inline code while preserving short explanatory notes and a single example
pointer.
| ## Error Handling | ||
|
|
||
| | Code | Meaning | Action | | ||
| |------|---------|--------| | ||
| | `401` | Invalid API key | Regenerate key in profile | | ||
| | `429` | Rate limited | Wait 5 minutes, retry | | ||
| | Status `not found` | Invalid query ID | Check query ID from `/new-query` response | | ||
| | Status `waiting` / `in progress` | Still processing | Retry after 15-60 seconds | | ||
|
|
||
| ## Setup | ||
|
|
||
| 1. Get API key from NeuronWriter profile > "Neuron API access" tab | ||
| 2. Store securely: | ||
|
|
||
| ```bash | ||
| bash ~/.aidevops/agents/scripts/setup-local-api-keys.sh set NEURONWRITER_API_KEY "your_api_key" | ||
| ``` | ||
|
|
||
| 3. Verify: | ||
|
|
||
| ```bash | ||
| source ~/.config/aidevops/mcp-env.sh | ||
| curl -s -X POST "https://app.neuronwriter.com/neuron-api/0.5/writer/list-projects" \ | ||
| -H "X-API-KEY: $NEURONWRITER_API_KEY" \ | ||
| -H "Accept: application/json" \ | ||
| -H "Content-Type: application/json" | jq . | ||
| ``` | ||
|
|
||
| ## Resources | ||
|
|
||
| - **Official Docs**: https://neuronwriter.com/faqs/neuronwriter-api-how-to-use/ | ||
| - **Roadmap**: https://roadmap.neuronwriter.com/p/neuron-api-HOPZZB | ||
| - **Dashboard**: https://app.neuronwriter.com/ | ||
| - **Plan Required**: Gold or higher |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's examine the actual file content around lines 275-308
cat -n .agent/seo/neuronwriter.md | sed -n '270,315p'Repository: marcusquinn/aidevops
Length of output: 1449
🏁 Script executed:
# Also check the file size to ensure we can read it
wc -l .agent/seo/neuronwriter.mdRepository: marcusquinn/aidevops
Length of output: 94
🌐 Web query:
site:neuronwriter.com/faqs neuronwriter-api-how-to-use
💡 Result:
NEURONwriter’s API is documented here: “NEURONwriter API – how to use”. Key points: [1]
- Availability/costs: Requires Gold plan or higher; API usage consumes the same monthly limits as using the UI. [1]
- Get your API key: In the app, go to My profile → “Neuron API access” and copy the key. [1]
- Endpoint: Use
https://app.neuronwriter.com/neuron-api/0.5/writerplus the method path. [1] - Auth header: Send your key in the HTTP header
X-API-KEY. [1] - Common flow:
/list-projectsto get your project IDs. [1]/new-query(POST) to create a query for a keyword (project/keyword/engine/language). [1]- Wait ~60 seconds, then
/get-query(POST) to poll untilstatus == "ready"and retrieve recommendations (metrics/terms, etc.). [1]
- Other methods:
/list-queries,/get-content,/import-content,/evaluate-content. [1]
Sources: [1]
Refactor inline code examples to use file:line references per documentation guidelines.
The error handling table and setup instructions are sound, but the inline bash code snippets (lines 289–291 and 295–301) violate the .agent/**/*.md progressive disclosure pattern. Use file:line references to point to actual implementation files instead of embedding code inline. This maintains architectural clarity and avoids duplication across the documentation.
The external documentation links are accurate and accessible. The setup process correctly follows the framework's secure key storage pattern.
🤖 Prompt for AI Agents
In @.agent/seo/neuronwriter.md around lines 275 - 308, Replace the inline bash
snippets in .agent/seo/neuronwriter.md (the setup command using
~/.aidevops/agents/scripts/setup-local-api-keys.sh and the verification curl
that sources ~/.config/aidevops/mcp-env.sh) with file:line references to the
actual implementation files per the progressive disclosure pattern; point
readers to the setup script (~/.aidevops/agents/scripts/setup-local-api-keys.sh)
and the env loader (~/.config/aidevops/mcp-env.sh) locations and the
verification curl example’s implementation/location instead of embedding the
commands, so the doc shows "see file:line" references rather than inline code.
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Mon Jan 26 00:04:02 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
marcusquinn
dismissed
coderabbitai[bot]’s stale review
Dismissing: The progressive-disclosure suggestion doesn't apply to curl-based API subagents. serper.md and dataforseo.md follow the same inline curl pattern - the examples ARE the implementation (no separate helper script exists). Nitpick about polling error handling was already addressed in commit 096794c.
1 participant
Summary
seo/neuronwriter.md) for SEO content optimizationDetails
NeuronWriter provides NLP-based content optimization recommendations via REST API. This subagent follows the same curl-based pattern as
serper.mdanddataforseo.md.Endpoints documented:
/list-projects/new-query/get-query/list-queries/get-content/import-content/evaluate-contentAlso includes:
Sources:
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.