> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Authenticate, list workspaces, read your score, start a run, and poll the job.

This guide walks through the full measurement lifecycle in one continuous example. Replace `gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` with a real API key from your workspace.

<Steps>
  <Step title="Authenticate">
    ```bash theme={null}
    export NM_KEY="gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    export NM_WS="your-workspace-slug"
    ```
  </Step>

  <Step title="List workspaces">
    ```bash theme={null}
    curl -H "Authorization: Bearer $NM_KEY" \
         https://ai-cmo.dev/api/v1/workspaces
    ```

    Response:

    ```json theme={null}
    [
      {
        "id": "acme",
        "displayName": "Acme Corp",
        "plan": "free",
        "role": "owner",
        "domains": ["acme.com"]
      }
    ]
    ```

    Every workspace list returns the full array; there is no cursor pagination.
  </Step>

  <Step title="Read the GEO score">
    ```bash theme={null}
    curl -H "Authorization: Bearer $NM_KEY" \
      "https://ai-cmo.dev/api/v1/workspaces/{workspace}/score"
    ```

    Response:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Start a measurement run">
    ```bash theme={null}
    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):

    ```json theme={null}
    {
      "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:

    ```bash theme={null}
    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"}'
    ```
  </Step>

  <Step title="Poll the job">
    ```bash theme={null}
    curl -H "Authorization: Bearer $NM_KEY" \
      "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs/{id}"
    ```

    Eventually returns:

    ```json theme={null}
    {
      "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"]
    }
    ```
  </Step>

  <Step title="Read the run detail">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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` |