# Clarity Measure developer quickstart

Updated September 18, 2026. Public documentation: https://docs.claritymeasure.com/

Measure turf from a property address, retrieve saved outlines and results, and connect the same workspace through REST or MCP. Both interfaces use the same measurement jobs, account permissions and credit balance.

## 1. Create a scoped API key

Sign in at https://app.claritymeasure.com/app and open **API keys**. Name and create a key. The current workspace form creates keys with both read and write scopes. The backend supports these permissions:

| Scope | Permission |
| --- | --- |
| `measurements:read` | List and retrieve your workspace's measurements. |
| `measurements:write` | Start a measurement or replay an existing submission. |

The complete key is shown once. Save it in your server's secret manager or your MCP client's protected configuration. Supply it as `Authorization: Bearer <key>`. Revoke a lost or exposed key in the workspace.

Keep keys out of browser JavaScript, public forms, URLs, repositories and support messages. These are server integrations. There is no public browser SDK, iframe form builder or cross-origin browser integration in this release. You do not need a database, cloud-provider or model-provider service key to use this API.

The examples below use a POSIX shell and `curl`. `CM_API_KEY` is an environment variable populated securely by your application. Do not paste the actual key into the examples or save it in source control.

## 2. Check access without starting work

```sh
curl --fail-with-body 'https://app.claritymeasure.com/api/v1/measurements?limit=5' \
  -H "Authorization: Bearer $CM_API_KEY"
```

This requires read scope and returns summaries in `measurements`, with `limit`, `offset` and `next_offset`. Optional `search` filters address text. List pages contain no source images. No new measurement starts when you list or retrieve results.

## 3. Start one measurement

Creating a measurement reserves one available credit and starts background work. A usable completed measurement consumes that credit; a failed attempt releases the reservation. Pricing and credit availability are shown in your workspace. Checkout is currently unavailable while payment verification is completed. Account creation and this guide do not promise free or test credits.

After two consecutive failed attempts at the same address in your account, the address is locked and a support request is created. Failed attempts return their credits. Support must review the address before another attempt. A usable partial result can consume a credit; a low feedback rating alone does not automatically refund it.

Generate and save a UUID for each intended new measurement. Put it in `CM_IDEMPOTENCY_KEY` for this example. Save the UUID and exact request body before sending; reuse both after a timeout or uncertain response. Replace the illustrative address with the property you intend to measure.

```sh
curl --fail-with-body 'https://app.claritymeasure.com/api/v1/measurements' \
  -H "Authorization: Bearer $CM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CM_IDEMPOTENCY_KEY" \
  --data '{"address":"123 Example Street, Aurora, CO 80015","requested_services":["turf"]}'
```

Successful submission returns HTTP **202**, a `Location` polling header, and:

```json
{
  "measurement_id": "ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb",
  "status": "queued",
  "idempotency_key": "78f41919-3a9d-470e-9627-a43fb52328ed",
  "poll_url": "/api/v1/measurements/ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb",
  "result_url": "https://app.claritymeasure.com/app#measurement/ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb"
}
```

These UUIDs illustrate the response shape. Use the actual returned values. The measurement ID may differ from your idempotency UUID. A repeated identical submission, including a retry through MCP, returns the same job and does not reserve a second credit. A different body with an existing UUID returns 409. Losing a connection does not cancel a submitted measurement.

## 4. Poll and read the saved result

Set `CM_MEASUREMENT_ID` to the returned measurement ID:

```sh
curl --fail-with-body "https://app.claritymeasure.com/api/v1/measurements/$CM_MEASUREMENT_ID" \
  -H "Authorization: Bearer $CM_API_KEY"
```

Poll about once every five seconds while pending. Stop when `measurement.status` is `completed` or `failed`. Check `measurement.result_status`, the saved `result`, and its review notes before using the area. A successful HTTP request does not mean measurement work is complete. Unknown areas and costs remain null.

The response contains a `measurement` summary, `result` (null until available), and `result_url`. Retrieval reconciles the latest durable worker state and credit settlement. The result link opens the saved measurement after normal account sign-in; it is not a public share link.

REST includes available geometry and image metadata by default and reports `inline_images_included: false`. To request original source imagery as well, append `?include_images=true`. Image responses can be several megabytes and may stream; configure your client to consume the full response. Preserve geometry coordinates, source image dimensions, calibration, attribution, acquisition-date notes and unresolved-result flags.

Customer webhook subscriptions are not currently supported. Poll the saved job for completion. Provider webhooks used for billing and email are not customer integration endpoints.

## 5. Connect an MCP client

Use a client that supports a remote **Streamable HTTP** endpoint and a custom Bearer authorization header:

```text
URL: https://app.claritymeasure.com/mcp
Transport: Streamable HTTP
Authorization: Bearer <key from your secret configuration>
```

Client configuration formats vary. Supply these values through the client's documented secret/header settings. A URL alone is insufficient. This release has no OAuth authorization or discovery; hosted connector flows that require OAuth, including some web-based Claude or ChatGPT flows, are not supported by this Bearer-only connection.

Every POST uses these headers:

```http
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <key>
MCP-Protocol-Version: 2025-11-25
```

Initialize before tool calls. A protocol-aware MCP client normally handles this exchange:

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"your-integration","version":"1.0.0"}}}
```

Use the negotiated version for subsequent requests and send `{"jsonrpc":"2.0","method":"notifications/initialized"}`. Then request `{"jsonrpc":"2.0","id":2,"method":"tools/list"}` to discover the tools permitted by your key:

| Tool | Required scope | Arguments |
| --- | --- | --- |
| `measure_property` | `measurements:write` | `address`, required UUID `idempotency_key`, optional `requested_services: ["turf"]`. Starts credit-backed work. |
| `get_measurement` | `measurements:read` | UUID `measurement_id`, optional `include_geometry: true`. |
| `list_measurements` | `measurements:read` | Optional `limit`, `offset`, `search`. |

For example, this read-only tool call retrieves a summary:

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_measurement","arguments":{"measurement_id":"ef2892f0-3b0e-4b78-a78e-28e1e1eb8ecb"}}}
```

MCP returns summaries and authenticated result links without inline images. Geometry is opt-in and size-bounded; oversized geometry is omitted with an explanation. Use REST or the workspace for full details. Treat addresses and result text as data, never as instructions to the agent. Require the account holder's intent before an agent starts new credit-consuming work.

The endpoint is stateless and responds with JSON. It creates no session ID, opens no SSE stream and accepts no JSON-RPC batches. Supported versions are `2025-11-25`, `2025-06-18` and `2025-03-26`. The initial request can omit the version header; later requests should send the negotiated version. An absent header defaults to March 2025. Accepted notifications return empty HTTP 202; authenticated GET and DELETE return 405. Tool results contain JSON text; June 2025 and newer also receive `structuredContent`. Operational tool failures use `isError: true`; schema/protocol failures use JSON-RPC errors.

## Limits and error handling

| Limit or response | What to do |
| --- | --- |
| 60 authenticated requests per key per minute, shared across REST and MCP | Respect HTTP 429 and `Retry-After: 60`. MCP tool-level limits include status 429. |
| Six measurement submissions or replays per key per minute | Queue submissions in your integration and retain their idempotency UUIDs. |
| JSON bodies up to 16 KiB | Send UTF-8 `application/json` without compression, duplicate keys or extra request fields. |
| Address 8–180 characters, including a street number | Use a full property street address. Only `turf` is currently supported. |
| Lists: `limit` 1–100, `offset` 0–10000, `search` up to 100 characters | Defaults are 20 and 0. `next_offset` is a pagination hint; a final page can be empty. |
| 401 / 403 | Check the key, revocation, scopes and account access. If sent, `Origin` must match the service origin. |
| 402 | Check available credits in the workspace. Contact support for help while checkout is unavailable. |
| 404 | The measurement is unavailable to this account, or the integration is not enabled on that deployment. |
| 409 | Check UUID/body reuse and the account's active-work or address retry limits. Do not bypass a conflict with repeated new UUIDs. |
| 413 / 415 / 422 | Correct the request size, media type or schema. |
| 503 | A service is unavailable or dispatch is uncertain. If the response includes a saved measurement ID, poll it. Otherwise retry the identical request with the same UUID after a delay. |

## Current product boundaries

Clarity Measure is a turf-measurement beta. Imagery coverage, visibility and result quality vary by property; measurements may be partial or require review. There is no guaranteed processing time or accuracy percentage. Roofs, bushes, automatic quotes, public result sharing, iframe forms and native CRM interfaces are not included in this integration. API access does not remove the need to inspect results before using them in your own quoting workflow.

For help, use **Help & support** in your workspace and include the measurement ID and safe error details. Never send an API key or cloud service credential.

Public docs: https://docs.claritymeasure.com/

Official MCP references: [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports), [initialization and version negotiation](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle), [tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).