Auto-update Docs and Blog with Cursor Cloud Agents and the Aveiro API
Set up Magic Blog or Magic Docs to receive draft MDX from Cursor Cloud Agent automations via the Aveiro content API — token setup, sync prompts, and publish workflow.
Create an Aveiro API token, connect a Magic Blog or Magic Docs site, then schedule a Cursor Cloud Agent automation that reads your repo and syncs MDX drafts through POST and PATCH calls. Review dirty pages in Aveiro, then publish in the editor.
Who this is for
You ship product changes in Git and want your blog or documentation to stay current without copy-pasting into a CMS. You already use — or want to try — Cursor Cloud Agents for background coding work.This guide shows how to wire those agents to the Aveiro API so they can create and update draft MDX pages on an Aveiro site, such as Magic Blog or Magic Docs. Publishing still happens in Aveiro (by design), but drafting and syncing can run on a schedule or from a webhook.If you only need a one-off page, use the API manually. If you want recurring sync from a repo, read on.
What you need
Piece
Role
Magic Blog or Magic Docs site
The Aveiro site that receives synced MDX pages
Aveiro API token
Bearer token with content:read and content:write scopes
Cursor Cloud Agent environment
VM with your repo, dependencies, and the API token as a secret
Cursor Automation (optional)
Scheduled or webhook trigger that runs the sync agent
Magic Blog is the right template when you publish articles, release notes, and changelog-style updates. Magic Docs fits reference guides, API pages, and nested sidebar navigation. Both store content as MDX and expose the same content API.
Step 1 — Create an Aveiro API token
Open your Aveiro organization and go to Organization → API tokens.
Click Create token and name it something recognizable (for example Cursor docs sync).
Enable scopes: sites:read, content:read, and content:write.
Optionally restrict the token to specific sites (your Magic Blog or Magic Docs instance).
Copy the secret when shown — it is displayed only once.
Store it as AVEIRO_API_TOKEN in your password manager and in Cursor Cloud Agent secrets.Every request uses:Full reference: API tokens and the Aveiro API docs.
Step 2 — Find your site ID
List every site your token can access:Pick the id for your Magic Blog or Magic Docs site. You will use it in every content endpoint:
Step 3 — Understand the content API
The Aveiro content API is draft-first. Agents create and update unpublished MDX. There is no publish scope — a human reviews in the editor and publishes when ready.
Action
Endpoint
Use when
List pages
GET /api/v1/sites/{siteId}/pages
Checking what already exists before sync
Create page
POST /api/v1/sites/{siteId}/pages
Adding a new MDX file at a path
Update page
PATCH /api/v1/sites/{siteId}/pages/{contentId}
Refreshing content on an existing page
Review changes
GET /api/v1/sites/{siteId}/changes
After CI sync — only dirty drafts
Parent folders must exist. To create /blog/my-post.mdx, the blog collection must already be in the file tree. Root-level pages like /about.mdx work without a parent folder.Idempotency: Pass Idempotency-Key on POST requests so network retries do not create duplicates.Example create call:Docs: Create a page · Update a page
Step 4 — Configure a Cursor Cloud Agent environment
Cloud agents run in isolated VMs with your repo, dependencies, and secrets. Set one up before you automate sync.
Open cursor.com/agents and create an environment for the repository that holds your source content (or the repo you want the agent to read).
Connect source control (GitHub, GitLab, or Bitbucket Cloud).
Add AVEIRO_API_TOKEN as an environment secret.
Run the setup command your project needs (pnpm install, etc.) and save a snapshot when green.
If you sync from MDX or Markdown files in Git, point the agent at that repo. If the agent should write content from code changes (for example generating API reference from OpenAPI), use the repo that contains the source of truth.See Cloud agent setup for multi-repo environments, Dockerfiles, and network access.
Step 5 — Create a Cursor Automation
Automations run cloud agents on a schedule, from webhooks, or in response to GitHub / Slack / Linear events.
Go to cursor.com/automations (or use the /automate skill in a local session).
Choose a trigger:
Cron schedule — nightly or weekly doc sync
Push to branch — sync when main updates
Webhook — trigger from your CI pipeline after a release
Select no repository if the agent only calls the Aveiro API and reads nothing from Git. Select a single repository when it should read local MDX/Markdown files or generate content from code.
Add the API token to the environment secrets (if not already there).
Write the prompt (see the next section).
Automations always run in Max Mode and bill as cloud agent usage. See Cursor Automations.
Example automation prompt
Paste and adapt this for a Magic Docs sync on every push to main:For Magic Blog, change the source folder to your posts directory (for example content/blog/) and map paths under /blog/.
Magic Blog vs Magic Docs
Template
Best for
Typical paths
Sync pattern
Magic Blog
Articles, tutorials, product updates
/blog/post-slug.mdx, /updates/feature.mdx
One POST/PATCH per post; metadata includes publishedAt when known
Magic Docs cares about collection order and sidebar structure — plan folder segments before bulk sync. Magic Blog cares about post metadata (title, summary, image, publishedAt) and collection blocks on index pages.Both accept the same API. Choose one site per automation to keep prompts and path rules simple.
MDX conventions agents should follow
Aveiro MDX is not generic Markdown. Agents that copy-paste from GitHub-flavored Markdown often hit 422 INVALID_MDX. Encode these rules in your automation prompt:
Do
Avoid
Heading, Table, Feedback, Column from the component catalog
Raw HTML layout or pipe tables
title and summary in metadata via the API
YAML frontmatter blocks in content
Short paragraphs and numbered steps
Pasting entire README files without structure
Fetch an existing page with GET .../pages/by-path?path=/blog/example.mdx and use it as a style reference for your agent.
Review and publish
After a sync run:
Call GET /api/v1/sites/{siteId}/changes or open the site in Aveiro.
Review pages marked dirty — these have unpublished draft edits.
Preview in the editor, fix layout in Visual mode if needed, then publish.
The API intentionally has no publish scope. That keeps automations from pushing live copy without a human pass — especially important for blog posts and public docs.
Webhook trigger from CI
For release-driven updates, create an automation with a Webhook trigger. After saving, Cursor gives you a private URL and API key.From GitHub Actions after a successful release:Include the version in the webhook body so the agent can mention it in updated changelog or blog drafts.
Troubleshooting
Error
Meaning
Fix
UNAUTHORIZED
Missing or invalid token
Check Bearer header and token scopes
FOLDER_NOT_FOUND
Parent collection missing
Create the folder in the Aveiro editor first
INVALID_MDX
Content failed validation
Use registered components; fetch a working page as reference
REVISION_CONFLICT
Concurrent edit
Re-fetch page, merge, retry PATCH with If-Match
IDEMPOTENCY_CONFLICT
Same key, different body
Use a new Idempotency-Key or match the original body
Putting it together
A practical stack for teams on Once UI templates:
Magic Docs (or Magic Blog) on Aveiro for the live site.
Source content in Git — optional, but version-controlled copy helps.
Cursor Cloud Agent with AVEIRO_API_TOKEN and a clear sync prompt.
Automation on cron, push, or webhook.
Human publish in Aveiro after reviewing dirty pages.
curl -s -X POST 'https://api.aveiro.app/api/v1/sites/SITE_ID/pages' \
-H 'Authorization: Bearer av_live_…' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: sync-changelog-2026-07-09' \
-d '{
"path": "/blog/auto-update-docs-and-blog-with-cursor-cloud-agents.mdx",
"content": "# Hello\n\nDraft body here.",
"metadata": {
"title": "Auto-update docs and blog with Cursor Cloud Agents",
"summary": "Sync MDX drafts from your repo using the Aveiro API."
}
}'
You sync documentation drafts to Aveiro via the content API.
Environment:
- AVEIRO_API_TOKEN is set
- Site ID: YOUR_MAGIC_DOCS_SITE_ID
Workflow:
1. GET https://api.aveiro.app/api/v1/sites/{siteId}/pages to list existing pages.
2. For each .mdx file under content/docs/ in this repo:
- Map repo path to Aveiro path (e.g. content/docs/get-started/quickstart.mdx → /get-started/quickstart.mdx)
- If the path exists, PATCH content and metadata (title, summary from frontmatter or filename).
- If missing, POST with Idempotency-Key: sync-{path}-{git-sha}.
3. Use Aveiro MDX components (Heading, Table, Feedback) — not raw HTML or pipe tables.
4. GET /api/v1/sites/{siteId}/changes and summarize dirty pages in your final message.
5. Do not attempt to publish — drafts only.
On INVALID_MDX or FOLDER_NOT_FOUND, report the path and stop that file; continue with others.
