From address to
reviewed measurement.

Your first measurement#

1. Create your account.

   Open Create account and enter your email, password and company name. Passwords must be 8–128 characters. Confirm your email, then complete your company profile.

2. Check your available credits.

   Your workspace shows the available balance. Each new measurement reserves one credit. Account creation does not promise a free credit allocation. Checkout is currently unavailable; contact support if you need help with access.

3. Enter the property address.

   Choose New measurement and use a full street address, including the street number, city, state and postal code. Check that the returned property is the one you intended.

4. Let the measurement finish.

   The job runs in the background and is saved to your account. Closing the tab does not cancel a submitted measurement. Return to saved history to check its state instead of starting a duplicate.

5. Inspect the result.

   Compare the turf outlines with the overhead image. Read source dates, review notes and any partial-result warnings before using the area in a customer estimate.

How a measurement works#

A submission creates a saved job first. Imagery acquisition and measurement happen afterward, so a successful submission is not a finished result.

The processing status and the result quality answer different questions. completed means processing finished; it does not certify the property boundary or every patch of turf. Check the result status and evidence too. A usable partial result may consume a credit.

Reading saved history, refreshing a result or replaying the same integration request does not start another measurement. A new request is a new attempt. Reusing a request ID with changed input returns a conflict.

Review & saved history#

Open Measurements to find an address, compare completed and failed attempts, and filter by your review rating. Open a row to return to its original result.

Read the image and the numbers together

• Check the target property, visible turf outlines and any gaps caused by trees, shadows or incomplete imagery.
• Review the area, processing status, result quality and run time. Unavailable is not zero. Unknown areas and costs remain empty or null.
• Inspect supporting imagery and its source date separately. A saved reference may be labeled as not used in the measurement.
• Use Open Google Maps for location context. A property location pin does not establish a legal parcel boundary.

Keep a review record

Choose Not reviewed, Terrible, Needs work or Acceptable, add review notes, and select Save feedback. These are your own review labels. Feedback stays with the saved measurement and does not rewrite the original image, outlines or provider evidence.

Use the saved-property map

The map shows loaded measurements that have saved coordinates. Open a point to inspect its measurement. Entries without recorded coordinates still appear in the list; the map is not a completeness check for your entire history.

Export diagnostics for a review

Select the relevant history rows and use the diagnostic export action to download clarity-measure-diagnostics.json. A result also has a Result diagnostics section and a Download result action for its saved JSON. These records help explain timing, status and evidence; they are not a survey or a finished customer quote. For geometry and image data in your own application, use the result API.

Imagery & quality#

Measurements use calibrated overhead imagery. Street View, when available, provides supporting context. It is not the image plane used to calculate turf area.

Use on-site verification when the result cannot support your decision. Current integrations accept turf only. Any roof-edge geometry encountered in research or older records describes horizontal plan lengths, not pitch-corrected installation lengths. Candidate crown counts are not complete tree or plant inventories.

Credits & billing#

How a credit is used

Starting a measurement moves one credit from available to reserved. A usable completed result consumes that reservation. A failed attempt that produces no usable measurement releases it back to the available balance. The reservation can remain while completion is still being reconciled; refreshing saved results or the dashboard checks the saved state.

After two consecutive failed attempts for the same normalized address in your account, the address is locked and a support request is created. The failed attempts return their credits. Support must review and unlock the address before another attempt. Changing address punctuation or sending repeated new request IDs is not a remedy.

Recorded service costs are different from your credits

Unknown costs remain unknown. Model and imagery figures do not include all hosting or operating costs, and are not a new charge to your payment method.

Account & email#

Sign in with your email and password at app.claritymeasure.com. Your email must be confirmed before you can use the workspace. Edit your company name, profile and measurement email preference in Account.

Confirm an account or reset a password

Open verification and password-reset links in the same browser where you requested them. The link uses a browser-bound verification step. If you see a browser or expired-link error, return to sign-in and request the relevant flow again. For a forgotten password, use Forgot password?, follow the email link and choose a new password.

Measurement notifications

When enabled and a verified recipient is available, the service sends a welcome message and notifications for completed or failed measurements. A notification links to the signed-in saved result; it does not make the measurement public. Email delivery can lag behind the saved job, so the workspace is the place to check its state.

Transactional messages use noreply@claritymeasure.com with replies directed to support@claritymeasure.com. Check spam folders if a message is missing. Support replies remain available in your workspace even when an email has not arrived.

API quickstart#

The canonical API origin is https://app.claritymeasure.com. Run these examples from a trusted server or terminal. They assume you have stored your key as CM_API_KEY in a protected environment.

Create a scoped key

Open API keys in your workspace. Name a key for its integration and select Create API key. The current workspace creates keys with both read and write scopes. The complete key is shown only once. Keep it in a secret manager, never in a web page, mobile bundle, source repository or support message.

The backend also supports keys with a single scope, although the current key-creation form does not offer a scope selector. A full submit-and-poll integration needs both scopes. Revoke a lost or exposed key in the workspace, then create and configure a replacement.

1. Confirm access without starting work

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

2. Start a turf measurement

Generate a UUID, save it as CM_IDEMPOTENCY_KEY, and save the exact request body before sending. Replace the illustrative address below with the intended property. This action can consume one credit.

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"]}'

A successful submission returns HTTP 202 and a Location header with the polling path. These UUIDs are illustrative:

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

3. Poll the saved job

Set CM_MEASUREMENT_ID to the returned measurement ID. It may be different from your idempotency UUID.

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, with backoff for errors. Stop when measurement.status is completed or failed. Then inspect measurement.result_status, the saved result and its review notes. The result_url requires the account holder to sign in.

API reference#

All endpoints require Authorization: Bearer <key>. Requests and responses use JSON. The service rejects unexpected fields and duplicate parameters. The API is intended for server integrations; browser origins are restricted.

POST /api/v1/measurements

Requires write scope and one Idempotency-Key header containing a hyphenated UUID.

Returns the submission shape above with HTTP 202. Reuse the same UUID and identical body after a timeout or uncertain response, including retries through MCP. The same request returns the existing job and does not reserve a second credit. Changed input with the same UUID returns 409.

GET /api/v1/measurements

Requires read scope. Returns measurements summaries, limit, offset and next_offset. Results contain no source images.

next_offset is a pagination hint, not a total count. A final page can be empty. This integration list does not accept the workspace’s rating filter.

GET /api/v1/measurements/{measurement_id}

Requires read scope and a hyphenated measurement UUID. Returns measurement, result, inline_images_included and result_url. The result can be null until available. Retrieval reconciles saved worker state and credit settlement.

Available geometry and image metadata are included by default, with inline_images_included: false. Add ?include_images=true to request original source imagery. Large JSON responses may stream; consume the entire body before parsing. Preserve dimensions, calibration, units, attribution and source-date notes with any geometry.

Request limits

• 60 authenticated requests per API key per minute, shared across REST and MCP.
• 6 measurement submissions or replays per key per minute, within that overall limit.
• JSON request bodies up to 16 KiB, UTF-8 application/json, without compression, duplicate keys or non-JSON numbers.

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

Connect with MCP#

Use an MCP client that supports a remote Streamable HTTP endpoint and a custom Bearer authorization header. Enter the key in the client’s protected configuration.

URL: https://app.claritymeasure.com/mcp
Transport: Streamable HTTP
Authorization: Bearer <your API key>

A URL alone is insufficient. This release has no OAuth authorization or discovery. Hosted connector flows that require OAuth are not supported by this Bearer-only connection.

Initialize and discover tools

A protocol-aware MCP client normally performs initialization. Every POST must send these headers; use the negotiated protocol version after initialization:

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

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

Send {"jsonrpc":"2.0","method":"notifications/initialized"}, then request {"jsonrpc":"2.0","id":2,"method":"tools/list"}. The advertised tools depend on your key’s scopes.

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

Results and transport behavior

MCP never returns inline imagery. Geometry is opt-in and size-bounded; oversized geometry is omitted with an explanation instead of truncated. Use REST or the saved result for full detail. Geometry selection is limited to geometry, layers, coordinate_system, units and calibration, when present.

The endpoint is stateless and returns 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. An absent version header defaults to March 2025. Accepted notifications return empty HTTP 202; authenticated GET and DELETE return 405.

Tool results contain JSON text in content; June 2025 and newer also receive structuredContent. Operational tool failures use isError: true, with status and message in the tool payload. Protocol and schema failures use JSON-RPC errors. Inspect both transport and tool results.

Errors & retries#

If the connection drops after submission, first poll the saved measurement if you have its ID. Otherwise resend the same UUID and exact body. A lost response does not mean the job was canceled.

A saved result says “needs review”

Open its evidence and notes before trying again. Poor source imagery may not improve on a second run. After two failed attempts, use the automatically created support conversation. A low feedback rating alone does not automatically refund a usable measurement.

A result or credit balance looks unfinished

Refresh the saved result or dashboard to reconcile the job state. Do not infer a failed run from a delayed email or unknown cost. If it remains unresolved, send support the measurement ID, approximate time and displayed status.

Privacy & permissions#

Workspace history and API keys are scoped to your account. A measurement link requires normal sign-in and permission; it is not a public share link. Original images, geometry and evidence are retained separately from your ratings and review notes.

• Account members work with the measurements and settings available in their own account.
• API keys inherit the owning account’s measurement access and only their assigned read/write scopes. A key cannot choose another account.
• Support staff use the restricted staff workspace to review customer measurements, support tickets and the support inbox, and reply to customers. This role does not include global analytics, billing, credit adjustments, marketing or account controls.
• Owner administrators can manage account controls and approved administrative actions. The Staff page lets them grant or revoke the support role for an existing, verified registered user. It does not send automatic invitations or grant the owner-administrator role.

Registering a customer account does not grant staff access. Staff permissions are assigned separately and checked on the service.

Staff access and administrative actions are subject to service controls and audit records. A suspended account cannot start new measurements; existing jobs can finish and saved history and support remain available through the signed-in workspace.

Keep exported diagnostic files private because they may contain property information. Never send passwords, complete API keys or cloud credentials in a support request. For data-access or deletion requests, contact support. See the Privacy policy and Terms for governing details.

Get support#

Open Help & support to start a request and follow the conversation. You can also email support@claritymeasure.com.

Include the measurement ID, the property address, the status you saw and what needs checking. For an integration issue, include the HTTP status and a safe error message. Attach the relevant diagnostic export when useful, after checking it for information you do not want to share.

Requests can be open, in progress, resolved or closed. Follow the existing conversation for an address that is locked after two failures. Support reviews the failed attempts before deciding whether another measurement is appropriate.

Product availability#

This documentation describes the current turf-measurement beta. Updated September 18, 2026.

For product information, visit claritymeasure.com. For measurements and integrations, use app.claritymeasure.com. These docs live at docs.claritymeasure.com.