Sites

Subscription required. Every endpoint on this page but GET /sites needs an active subscription. Without one the request is refused with 402 payment_required (Pick a plan to keep going.) before the endpoint runs, reads included. GET /sites answers with or without one. See Conventions.

A site is a website you've added to MetaMonster. Sites are the top of the hierarchy — pages, snapshots, analysis, and drafts all belong to a site.

All site endpoints require the sites:read scope.

Site-scoped operations over pages are documented with the pages they act on: GET /sites/{siteId}/pages, PATCH /sites/{siteId}/pages (bulk edit), and POST /sites/{siteId}/analyze (bulk analyze, content:write).

GET /sites

List your organization's sites, newest first. Paginated.

Scope: sites:read

Query parameters

Request

curl "https://app.metamonster.ai/api/v1/sites?page=1&limit=15" \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "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 }
}

Each item (site summary shape):

POST /sites

Add a site to your organization and queue the standard setup job (page discovery → GSC enrichment → crawl) — the API twin of the dashboard's add-site form, minus GSC wiring (API keys carry no user; connect Google Search Console from the dashboard).

Scope: content:write

Request body

Both scopes default to none so adding a site over the API never spends keyword or analysis allowance by itself — pass a wider scope only if you want the setup job to run keyword generation and/or analysis right away.

Adding a site requires an active subscription. An org without one gets 402 payment_required and no site is created; there is no free site and no free audit.

Request

curl -X POST https://app.metamonster.ai/api/v1/sites \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

Response 201

{
  "data": {
    "id": 42,
    "domain": "example.com",
    "url": "https://example.com",
    "name": null,
    "business_context": null,
    "voice_tone": null,
    "gsc_connected": false,
    "gsc_property_url": null,
    "background_status": "discovering",
    "score_curve": null,
    "location": { "country_code": null, "country_name": null, "city_code": null, "city_name": null },
    "llms_txt": null,
    "setup_completed_at": null,
    "discovery_completed_at": null,
    "created_at": "2026-08-19T00:00:00Z",
    "updated_at": "2026-08-19T00:00:00Z",
    "last_crawled_at": null,
    "latest_crawl": null,
    "page_count": 0,
    "draft_count": 0
  }
}

Same site detail shape as GET /sites/{siteId}. background_status starts at discovering — poll GET /sites/{siteId} until it returns to null before expecting a full page list or opportunity scores.

Errors

GET /sites/{siteId}

Fetch a single site with full detail, including its latest crawl.

Scope: sites:read

Path parameters

Request

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

Response 200

{
  "data": {
    "id": 42,
    "domain": "example.com",
    "url": "https://example.com",
    "name": "Example",
    "business_context": "B2B SaaS for SEO teams",
    "voice_tone": "Professional, concise",
    "gsc_connected": true,
    "gsc_property_url": "sc-domain:example.com",
    "background_status": null,
    "score_curve": "proportional",
    "location": {
      "country_code": 2840,
      "country_name": "United States",
      "city_code": null,
      "city_name": null
    },
    "llms_txt": "…",
    "setup_completed_at": "2026-05-01T12:30:00Z",
    "discovery_completed_at": "2026-05-01T13:00:00Z",
    "created_at": "2026-05-01T12:00:00Z",
    "updated_at": "2026-07-20T09:30:00Z",
    "last_crawled_at": "2026-07-20T09:30:00Z",
    "latest_crawl": {
      "id": 900,
      "status": "completed",
      "total_pages": 128,
      "crawled_pages": 128,
      "started_at": "2026-07-20T09:00:00Z",
      "completed_at": "2026-07-20T09:30:00Z"
    },
    "page_count": 128,
    "draft_count": 5
  }
}

Site detail shape:

latest_crawl object:

Errors

GET /sites/{siteId}/email-report-settings

Internal preview: 404 not_found unless email reports are enabled for your organization.

Whether the site's monthly email report is on, and who it goes to. Scope: sites:read.

Request

curl https://app.metamonster.ai/api/v1/sites/42/email-report-settings \
  -H "Authorization: Bearer $METAMONSTER_API_KEY"

Response 200

{
  "data": {
    "enabled": true,
    "recipients": ["jade@client.com", "owner@client.com"]
  }
}

Errors

PUT /sites/{siteId}/email-report-settings

Internal preview: 404 not_found unless email reports are enabled for your organization.

Turn the monthly email report on or off and/or set who it goes to. Scope: content:write.

Request body

Give enabled, recipients or both.

Turning the report on with no recipients is allowed: nothing is sent until one is added.

Request

curl -X PUT https://app.metamonster.ai/api/v1/sites/42/email-report-settings \
  -H "Authorization: Bearer $METAMONSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "recipients": ["Jade@Client.com", "owner@client.com"] }'

Response 200

The saved settings, as GET returns them.

Errors