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 read your brand and affiliate data, publish content, and run the Content Agent from your own stack. This reference covers both.

All REST requests are made to:

http

https://alterionlabs.com/v1

Authentication

The REST API uses OAuth 2.0 with the client_credentials grant — the standard machine-to-machine flow. Create an API client in your dashboard under Settings → API access: you get a client_id and a client_secret (shown once). Keep the secret server-side.

Discovery is fully self-describing. Protected resource metadata (RFC 9728) names the authorization server that issues tokens for this API; authorization server metadata (RFC 8414) gives the token URL, JWKS, and scopes:

http

https://alterionlabs.com/.well-known/oauth-protected-resource
https://alterionlabs.com/.well-known/oauth-authorization-server

Exchange your credentials for a short-lived access token, then send it as a bearer token on every request. The token endpoint is the token_endpoint from the metadata above.

bash

# 1) Get an access token
curl -s -X POST "$TOKEN_ENDPOINT" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=https://api.alterionlabs.com/brand.read https://api.alterionlabs.com/affiliate.read"

# Response: { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

# 2) Call the API with the token
curl https://alterionlabs.com/v1/brand \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Access tokens expire after 60 minutes — request a new one when it expires. A missing or invalid token returns 401; a valid token without the required scope returns 403 — both carry a WWW-Authenticate header.

The MCP server authenticates separately, with a connection token you create under Settings (see Connect) — not an OAuth client.

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=\"...\">"
    }
  ]
}

Brand & Affiliate API

Read your program data

Read your brand profile, program stats, and affiliates over REST. These endpoints are live today — an agent with brand.read and affiliate.read can pull everything it needs to report on your program. Monetary fields are integer cents paired with a currencycode.

Objects

The brand object describes your account; the affiliate object describes a partner in your program.

idstring

Unique brand identifier.

slugstring

URL-safe brand handle.

namestring

Brand name.

planstring

Subscription plan.

websiteUrlstring

Program website. Null until a campaign is active.

campaignobject

Active campaign { name, rewardType, rewardValue }, or null.

createdAttimestamp

ISO 8601 creation time.

Endpoints

GET/v1/brand

Retrieve your brand profile. Scope: brand.read.

bash

curl https://alterionlabs.com/v1/brand \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Response
{
  "brand": {
    "id": "9f2c81e4-3a6b-4d2f-8c10-1e7a9b0c4d5e",
    "slug": "acme",
    "name": "Acme",
    "plan": "pro",
    "websiteUrl": "https://acme.com",
    "createdAt": "2026-01-12T09:30:00.000Z",
    "campaign": { "name": "Acme Partners", "rewardType": "percentage", "rewardValue": 20 }
  }
}

GET/v1/brand/stats

Program totals: revenue, clicks, conversions, and commissions. Scope: brand.read.

bash

curl https://alterionlabs.com/v1/brand/stats \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Response
{
  "stats": {
    "currency": "USD",
    "revenueCents": 4820000,
    "clicks": 18342,
    "conversions": 263,
    "conversionRate": 0.0143,
    "activeAffiliates": 47,
    "commissions": { "paidCents": 612000, "pendingCents": 88400 }
  }
}

GET/v1/affiliate

List your affiliates (up to 100, newest first). Scope: affiliate.read.

bash

curl https://alterionlabs.com/v1/affiliate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Response
{
  "affiliates": [
    {
      "id": "a1b2c3d4-5e6f-4789-90ab-cdef01234567",
      "email": "partner@example.com",
      "firstName": "Jordan",
      "lastName": "Lee",
      "accountStatus": "active",
      "createdAt": "2026-03-04T14:08:00.000Z"
    }
  ]
}

GET/v1/affiliate/stats

Per-affiliate clicks, conversions, and earnings. Scope: affiliate.read.

bash

curl https://alterionlabs.com/v1/affiliate/stats \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Response
{
  "affiliates": [
    {
      "affiliateId": "a1b2c3d4-5e6f-4789-90ab-cdef01234567",
      "email": "partner@example.com",
      "name": "Jordan Lee",
      "clicks": 1203,
      "conversions": 21,
      "earningsCents": 84300
    }
  ]
}

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://alterionlabs.com/v1/posts \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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://alterionlabs.com/v1/posts?status=published&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET/v1/posts/{id}

Retrieve a single post by id.

bash

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

PATCH/v1/posts/{id}

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

bash

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

DELETE/v1/posts/{id}

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

bash

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

GET/v1/feed

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

bash

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

GET/v1/posts/{id}/metrics

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

bash

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

POST/v1/newsletter/subscribers

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

bash

curl https://alterionlabs.com/v1/newsletter/subscribers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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://alterionlabs.com/v1/content/generate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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://alterionlabs.com/v1/content/jobs/job_q1z9 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST/v1/content/schedule

Schedule a post for publication at a future time.

bash

curl https://alterionlabs.com/v1/content/schedule \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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://alterionlabs.com/v1/content/publish \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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://alterionlabs.com/v1/content/calendar?month=2026-07" \
  -H "Authorization: Bearer $ACCESS_TOKEN"