Quickstart - ai-cmo.dev

The ai-cmo.dev REST API measurement lifecycle can be completed in a few curl commands. This guide walks through authentication, listing workspaces, reading the GEO score, starting a run, and polling the job — all in one continuous example.

Authenticate

export NM_KEY="gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export NM_WS="your-workspace-slug"

List workspaces

curl -H "Authorization: Bearer $NM_KEY" \
     https://ai-cmo.dev/api/v1/workspaces

Response:

[
  {
    "id": "acme",
    "displayName": "Acme Corp",
    "plan": "free",
    "role": "owner",
    "domains": ["acme.com"]
  }
]

Every workspace list returns the full array; there is no cursor pagination.

Read the GEO score

curl -H "Authorization: Bearer $NM_KEY" \
  "https://ai-cmo.dev/api/v1/workspaces/{workspace}/score"

Response:

{
  "score": 62,
  "version": "geo-score-v1",
  "components": {
    "visibility": { "weight": 0.25, "value": 58 },
    "relativeSov": { "weight": 0.35, "value": 65 },
    "position": { "weight": 0.15, "value": 70 },
    "sentiment": { "weight": 0.10, "value": 55 },
    "volume": { "weight": 0.15, "value": 50 }
  },
  "missingComponents": [],
  "date": "2026-08-10"
}

The score is 0–100. Five weighted components: visibility (0.25), relativeSov (0.35), position (0.15), sentiment (0.10), volume (0.15). Missing components are reported in missingComponents and the remaining weights renormalize.

Start a measurement run

curl -X POST "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs" \
  -H "Authorization: Bearer $NM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset": "standard"}'

Response (202):

{
  "id": "run_abc123",
  "brand": "acme",
  "kind": "measurement",
  "status": "running",
  "progress": { "completedCalls": 0, "totalCalls": 150, "percent": 0, "source": "calls" },
  "startedAt": "2026-08-10T10:00:00Z",
  "finishedAt": null,
  "pid": 12345,
  "logPath": "/tmp/geo/run_acme_20260810_100000.log",
  "lastLines": []
}

Four presets: standard (150 active prompts), lite (50), smoke (2), and exa (150). The run starts if credits are sufficient, no other measurement is running for this brand, and the pipeline worker cap has not been reached.Optionally include an idempotencyKey to make the start safe for retries:

curl -X POST "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs" \
  -H "Authorization: Bearer $NM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset": "standard", "idempotencyKey": "start-run-20260810-01"}'

Poll the job

curl -H "Authorization: Bearer $NM_KEY" \
  "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs/{id}"

Eventually returns:

{
  "id": "run_abc123",
  "brand": "acme",
  "kind": "measurement",
  "status": "succeeded",
  "progress": { "completedCalls": 150, "totalCalls": 150, "percent": 100, "source": "calls" },
  "startedAt": "2026-08-10T10:00:00Z",
  "finishedAt": "2026-08-10T10:15:00Z",
  "pid": 12345,
  "logPath": "/tmp/geo/run_acme_20260810_100000.log",
  "lastLines": ["Measurement complete"]
}

Read the run detail

curl -H "Authorization: Bearer $NM_KEY" \
  "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs/{id}/detail"

The detail response groups results by engine, with brand mentions, citations, sentiments, and visible prompt results per engine.

Copyable workflow

Run the full measurement lifecycle in one terminal session:

Terminal

export NM_KEY="gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export NM_WS="your-workspace-slug"

# List workspaces
curl -H "Authorization: Bearer $NM_KEY" https://ai-cmo.dev/api/v1/workspaces

# Read GEO score
curl -H "Authorization: Bearer $NM_KEY" "https://ai-cmo.dev/api/v1/workspaces/$NM_WS/score"

# Start a measurement run
curl -X POST "https://ai-cmo.dev/api/v1/workspaces/$NM_WS/runs" \
  -H "Authorization: Bearer $NM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset": "standard", "idempotencyKey": "start-run-01"}'

# Poll the job (replace {id})
curl -H "Authorization: Bearer $NM_KEY" "https://ai-cmo.dev/api/v1/workspaces/$NM_WS/runs/{id}"

# Read run detail
curl -H "Authorization: Bearer $NM_KEY" "https://ai-cmo.dev/api/v1/workspaces/$NM_WS/runs/{id}/detail"

Common errors

Scenario	HTTP	Code
Wrong or missing key	401	`invalid_key`
Insufficient credits	402	`insufficient_credits`
Workspace mismatch	404	`workspace_not_found`
Measurement already running	409	`job_already_running`
Pipeline at capacity	429	`pipeline_capacity_reached`

​Copyable workflow

​Common errors

Copyable workflow

Common errors