MetaMonster

Getting started

Getting started

This guide takes you from zero to your first authenticated API call in about five minutes. You'll create an API key in the MetaMonster dashboard, verify it works, and then read one of your sites.

Prerequisites

  • A MetaMonster account with at least one site added. If you don't have a site yet, add one in the dashboard first — the API reads the data MetaMonster has already crawled and analyzed.
  • A terminal with curl (or any HTTP client — the examples use curl, but nothing here is curl-specific).

Step 1 — Create an API key

API keys are created and managed in the MetaMonster dashboard. They can't be created through the API itself.

  1. Sign in to MetaMonster at new.metamonster.ai.
  2. Go to Settings → API Keys (/settings/api-keys).
  3. Click Create key.
  4. Give the key a name (a label to help you recognize it later, e.g. "Production integration") and choose an expiration (Never, 30 days, 90 days, or 1 year).
  5. Click Create key.

Your new key is shown once, right after creation. It looks like this:

mm_aB3xK9pQ2rL7mN4vT1sY6wD8fH5gJ0cZ...

Copy it somewhere safe now. If you lose it, you can reveal it again later from the keys list (click the eye icon next to the key) — but store it securely regardless. Treat it like a password: anyone with your key can read and modify your MetaMonster data.

Scopes: Keys created in the dashboard are granted full access to your organization's data (all scopes). See Authentication → Scopes for what each scope allows.

Step 2 — Verify your key

Call GET /me to confirm the key works. Send it in the Authorization header as a Bearer token:

curl https://new.metamonster.ai/api/v1/me \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

A working key returns its identity:

{
  "name": "Production integration",
  "prefix": "mm_aB3x",
  "scopes": ["sites:read", "content:write", "cms:publish"]
}

If you see 401 Unauthorized, double-check that you copied the whole key and included the Bearer prefix. See Authentication for the full list of auth errors.

Step 3 — List your sites

Now read something real. GET /sites returns your organization's sites:

curl https://new.metamonster.ai/api/v1/sites \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

{
  "data": [
    {
      "id": 42,
      "domain": "example.com",
      "url": "https://example.com",
      "name": "Example",
      "created_at": "2026-05-01T12:00:00Z",
      "last_crawled_at": "2026-07-20T09:30:00Z",
      "page_count": 128,
      "draft_count": 5
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 15 }
}

Note the shape: list endpoints wrap results in data and include a meta object for pagination. See Conventions for the details.

Step 4 — Drill into a site's pages

Grab a site's id from the previous response and list its pages:

curl "https://new.metamonster.ai/api/v1/sites/42/pages?limit=5" \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

{
  "data": [
    {
      "id": 5001,
      "url": "https://example.com/pricing",
      "path": "/pricing",
      "site_id": 42,
      "title": "Pricing — Example",
      "primary_keyword": "example pricing",
      "is_priority": true,
      "opportunity_score": 78
    }
  ],
  "meta": { "total": 128, "page": 1, "per_page": 5 }
}

From here you can read a page's full detail (GET /pages/{id}), its current content (GET /pages/{id}/content), its SEO analysis (GET /pages/{id}/analysis), and more.

The golden path

Most integrations follow this shape:

  1. GET /sites → find the site you care about.
  2. GET /sites/{siteId}/pages → find the pages (filter by search, is_priority, min_score, etc.).
  3. GET /pages/{pageId} → read a page's detail, including its latest snapshot and analysis summary.
  4. GET /pages/{pageId}/content → read the page's body content as markdown.
  5. PATCH /pages/{pageId} or POST /pages/{pageId}/content or PUT /pages/{pageId}/drafts/{field} → make changes.

Next steps