Documentation

Connect Alterion Labs to your AI tools over MCP, or call the REST APIs directly. One brand key, every marketing agent.

Introduction

Alterion Labs gives your AI tools and your code direct access to every marketing agent. Connect over the Model Context Protocol (MCP) to let your AI coding tool apply marketing-grade changes, or call the REST APIs to publish content and run the Content Agent from your own stack. This reference covers both.

All REST requests are made to:

http

https://api.alterionlabs.com/v1

Authentication

Every request authenticates with your brand API key, sent as a bearer token. Find your key in your Alterion Labs dashboard under Settings → API keys. Keep it server-side — it grants full access to your brand's agents.

bash

curl https://api.alterionlabs.com/v1/posts \
  -H "Authorization: Bearer $ALTERION_API_KEY"

The MCP server uses the same key. Pass it as the token in your mcp-config.json (see Connect).

Errors

Alterion Labs uses conventional HTTP status codes. Codes in the 2xx range indicate success, 4xx indicate a problem with the request, and 5xx indicate a server error. Every error returns a JSON body:

json

{
  "error": {
    "type": "invalid_request",
    "code": "missing_field",
    "message": "Field 'title' is required."
  }
}

400invalid_request

The request was malformed or missing a required field.

401authentication_error

No valid API key was provided.

403permission_error

The key is valid but lacks access to this resource.

404not_found

The requested resource does not exist.

429rate_limit_exceeded

Too many requests. Back off and retry.

500api_error

Something went wrong on our end.

Rate limits

Requests are rate limited per brand. Current limits and remaining quota are returned on every response:

http

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1717977600

Exceeding the limit returns 429 rate_limit_exceeded. Back off until the Unix timestamp in X-RateLimit-Reset, then retry.

MCP Server

Connect your AI tool to every agent

The MCP server exposes each marketing agent as a callable tool. Your AI coding tool calls them; Alterion Labs returns structured, ready-to-apply changes — so you ship marketing-grade code without writing it.

Connect

Add Alterion Labs to any MCP-compatible tool — Cursor, Claude Code, Windsurf, VS Code + Copilot, JetBrains AI — with one config block. On connection, the server authenticates your token and exposes the tools below.

mcp-config.json

{
  "mcpServers": {
    "alterion-marketing": {
      "url": "https://mcp.alterionlabs.com",
      "token": "your_brand_token"
    }
  }
}

Tools

Each tool maps to an agent capability. Inputs and outputs are JSON.

audit_marketingtool

Run a full marketing audit for a URL. Returns scored findings across SEO, content, GEO, analytics, and retention.

get_seo_fixestool

Return prioritized, ready-to-apply SEO fixes — meta tags, schema, headings, internal links.

get_content_plantool

Return a content calendar and article briefs based on keyword gaps.

get_geo_recommendationstool

Return structure and schema changes that surface your content in AI search engines.

get_tracking_setuptool

Return analytics and conversion tracking scripts to install.

get_retention_actionstool

Return retention logic and cancel-flow changes to reduce churn.

Example — calling get_seo_fixes:

json

// Input
{ "url": "https://yourapp.com" }

// Output
{
  "fixes": [
    {
      "id": "meta-description-missing",
      "priority": "high",
      "page": "/pricing",
      "change": "Add a 155-character meta description.",
      "snippet": "<meta name=\"description\" content=\"...\">"
    }
  ]
}

Blog API

Publish and manage content

A REST API for the Content Marketing Agent's blog engine. Create and update posts, pull feeds, read engagement, and manage newsletter subscribers — programmatically.

The Post object

idstring

Unique identifier, prefixed post_.

titlestring

Post title.

slugstring

URL slug. Generated from the title if omitted.

statusenum

One of draft, scheduled, or published.

bodystring

Post content in Markdown.

excerptstring

Short summary. Auto-generated if omitted.

tagsstring[]

Topic tags.

authorobject

{ name, url }.

seoobject

{ title, description } for search and social.

published_attimestamp

ISO 8601 publish time. Null for drafts.

created_attimestamp

ISO 8601 creation time.

updated_attimestamp

ISO 8601 last-update time.

Endpoints

POST/v1/posts

Create a post. Returns the created Post object.

bash

curl https://api.alterionlabs.com/v1/posts \
  -H "Authorization: Bearer $ALTERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How we cut churn 30%",
    "body": "## The problem\n...",
    "tags": ["retention", "saas"],
    "status": "published"
  }'

GET/v1/posts

List posts. Filter with status and tag; paginate with limit and starting_after. Returns { data, has_more }.

bash

curl "https://api.alterionlabs.com/v1/posts?status=published&limit=20" \
  -H "Authorization: Bearer $ALTERION_API_KEY"

GET/v1/posts/{id}

Retrieve a single post by id.

bash

curl https://api.alterionlabs.com/v1/posts/post_8fk2 \
  -H "Authorization: Bearer $ALTERION_API_KEY"

PATCH/v1/posts/{id}

Update a post. Send only the fields you want to change.

bash

curl -X PATCH https://api.alterionlabs.com/v1/posts/post_8fk2 \
  -H "Authorization: Bearer $ALTERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "draft" }'

DELETE/v1/posts/{id}

Delete a post. Returns { id, deleted: true }.

bash

curl -X DELETE https://api.alterionlabs.com/v1/posts/post_8fk2 \
  -H "Authorization: Bearer $ALTERION_API_KEY"

GET/v1/feed

Pull the published feed. Set format to rss or json.

bash

curl "https://api.alterionlabs.com/v1/feed?format=json" \
  -H "Authorization: Bearer $ALTERION_API_KEY"

GET/v1/posts/{id}/metrics

Read engagement. Returns { views, unique_visitors, comments, avg_read_time }.

bash

curl https://api.alterionlabs.com/v1/posts/post_8fk2/metrics \
  -H "Authorization: Bearer $ALTERION_API_KEY"

POST/v1/newsletter/subscribers

Add a subscriber to your newsletter. Returns the subscriber object.

bash

curl https://api.alterionlabs.com/v1/newsletter/subscribers \
  -H "Authorization: Bearer $ALTERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "reader@example.com", "name": "Alex" }'

Content Agent API

Run the agent from your stack

Call the AI Content Marketing Agent directly. Generation runs asynchronously: you create a job, poll until it completes, then schedule or publish the resulting post.

The Job object

idstring

Unique identifier, prefixed job_.

statusenum

One of queued, processing, completed, or failed.

typestring

The job type, e.g. generate.

resultobject

{ post_id } when completed; null otherwise.

errorobject

Error detail when failed; null otherwise.

created_attimestamp

ISO 8601 creation time.

completed_attimestamp

ISO 8601 completion time. Null until finished.

Endpoints

POST/v1/content/generate

Generate a draft from a topic. tone defaults to professional, length to medium. Returns a Job with status queued.

bash

curl https://api.alterionlabs.com/v1/content/generate \
  -H "Authorization: Bearer $ALTERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Reducing SaaS churn with onboarding",
    "keywords": ["saas churn", "user onboarding"],
    "tone": "professional",
    "length": "medium",
    "target_url": "https://yourapp.com"
  }'

GET/v1/content/jobs/{id}

Retrieve a job. Poll until status is completed, then read result.post_id.

bash

curl https://api.alterionlabs.com/v1/content/jobs/job_q1z9 \
  -H "Authorization: Bearer $ALTERION_API_KEY"

POST/v1/content/schedule

Schedule a post for publication at a future time.

bash

curl https://api.alterionlabs.com/v1/content/schedule \
  -H "Authorization: Bearer $ALTERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "post_8fk2",
    "publish_at": "2026-07-01T09:00:00Z"
  }'

POST/v1/content/publish

Publish a post now to a destination. destination.type is one of blog, webhook, or cms.

bash

curl https://api.alterionlabs.com/v1/content/publish \
  -H "Authorization: Bearer $ALTERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "post_8fk2",
    "destination": { "type": "webhook", "url": "https://yourapp.com/hooks/blog" }
  }'

GET/v1/content/calendar

List scheduled content. Filter by month (YYYY-MM). Returns { data: [{ post_id, title, publish_at, status }] }.

bash

curl "https://api.alterionlabs.com/v1/content/calendar?month=2026-07" \
  -H "Authorization: Bearer $ALTERION_API_KEY"