---
title: "[beta] Create a watchpoint"
method: POST
path: "/ground-intelligence/watchpoints"
tags: ["Beta APIs"]
---

# \[beta\] Create a watchpoint

`POST /ground-intelligence/watchpoints`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/ground-intelligence/watchpoints`
- Auth: HTTP bearer

Creates a Ground Intelligence watchpoint for the organization. The submitted location may be snapped to a road within 75 meters. Use the location returned in the response as the saved watchpoint location.

 <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Write Watchpoints** under the Ground Intelligence category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Request body

- EntityWatchpointsServiceCreateWatchpointRequestBody: Request body for creating a Watchpoint
  - `bearingRange` WatchpointBearingRangeTypeRequestBody: Inclusive clockwise range for the vehicle's direction of travel, measured in degrees from true north. Endpoints must be finite, distinct, and in [0, 360). A start greater than the end wraps through north. When absent, observations are not filtered by direction of travel.
    - `endDegrees` number, required: End bearing in degrees.
    - `startDegrees` number, required: Start bearing in degrees.
  - `customDetections` WatchpointCustomDetectionRequestTypeRequestBody[]: Conditions to detect in new observations. Defaults to none. Requires custom detections to be enabled for your organization. Types must be distinct.
    - `query` string: Additional criteria narrowing the supported detection. Defaults to empty.
    - `type` 'workZone' | 'stoppedVehicle' | 'vehicleCollision' | 'roadObstruction' | 'roadClosure' | 'roadDefect' | 'trafficSignalFault', required: Supported detection type. Required; there is no default. Valid values: `workZone`, `stoppedVehicle`, `vehicleCollision`, `roadObstruction`, `roadClosure`, `roadDefect`, `trafficSignalFault`
  - `location` WatchpointLatLngTypeRequestBody, required: Watchpoint latitude and longitude.
    - `latitude` number, required
    - `longitude` number, required
  - `mode` 'justOnce' | 'daily' | 'weekly' | 'monthly' | 'every15Minutes' | 'hourly', required: Recurrence frequency for observations. Valid values: `justOnce`, `daily`, `weekly`, `monthly`, `every15Minutes`, `hourly`
  - `name` string: Customer-provided name for the watchpoint.
  - `note` string: Customer-provided note about the watchpoint.
  - `observationType` 'roadDefect' | 'utilityCut' | 'guardrail' | 'streetlight' | 'signage' | 'stormDrain' | 'graffiti' | 'vegetation' | 'blight' | 'illegalDumping' | 'littering' | 'highVegetationWeeds' | 'fire' | 'other', required: Type of condition to observe at this watchpoint. Valid values: `roadDefect`, `utilityCut`, `guardrail`, `streetlight`, `signage`, `stormDrain`, `graffiti`, `vegetation`, `blight`, `illegalDumping`, `littering`, `highVegetationWeeds`, `fire`, `other`
  - `sendDashboardNotification` boolean: Sends the authenticated user a dashboard notification for each new observation. Defaults to false. Ignored when the API token is not associated with a user.

## Response `200`

OK response.

- EntityWatchpointsServiceCreateWatchpointResponseBody
  - `data` EntityCreateWatchpointTypeResponseBody, required: Watchpoint object
    - `bearingRange` WatchpointBearingRangeTypeResponseBody: Inclusive clockwise range for the vehicle's direction of travel, measured in degrees from true north. Endpoints must be finite, distinct, and in [0, 360). A start greater than the end wraps through north. When absent, observations are not filtered by direction of travel.
      - `endDegrees` number, required: End bearing in degrees.
      - `startDegrees` number, required: Start bearing in degrees.
    - `createdAtTime` string, required: Time when the watchpoint resource was created.
    - `customDetections` WatchpointCustomDetectionResponseTypeResponseBody[]: Configured detections. Omitted when none are configured.
      - `query` string: Normalized customer criteria. Defaults to empty.
      - `type` 'unknown' | 'workZone' | 'stoppedVehicle' | 'vehicleCollision' | 'roadObstruction' | 'roadClosure' | 'roadDefect' | 'trafficSignalFault', required: Configured detection type. Returns unknown if the stored type is unsupported. Valid values: `unknown`, `workZone`, `stoppedVehicle`, `vehicleCollision`, `roadObstruction`, `roadClosure`, `roadDefect`, `trafficSignalFault`
    - `id` string, required: Unique identifier for the watchpoint.
    - `lastObservationTime` string, nullable, required: Time when the most recent observation was collected, or null when unavailable.
    - `location` WatchpointLatLngTypeResponseBody, required: Watchpoint latitude and longitude.
      - `latitude` number, required
      - `longitude` number, required
    - `mode` 'unknown' | 'justOnce' | 'daily' | 'weekly' | 'monthly' | 'every15Minutes' | 'hourly', required: Recurrence frequency for observations. Valid values: `unknown`, `justOnce`, `daily`, `weekly`, `monthly`, `every15Minutes`, `hourly`
    - `monitoringEndTime` string, required: Server-derived end of the current monitoring window.
    - `monitoringStartTime` string, required: Start of the current monitoring run.
    - `name` string, nullable, required: Customer-provided name for the watchpoint, or null when unavailable.
    - `note` string, nullable, required: Customer-provided note about the watchpoint, or null when unavailable.
    - `observationCount` integer, required: Number of observations collected for the watchpoint.
    - `observationType` 'unknown' | 'roadDefect' | 'utilityCut' | 'guardrail' | 'streetlight' | 'signage' | 'stormDrain' | 'graffiti' | 'vegetation' | 'blight' | 'illegalDumping' | 'littering' | 'highVegetationWeeds' | 'fire' | 'other', required: Type of condition to observe at this watchpoint. Valid values: `unknown`, `roadDefect`, `utilityCut`, `guardrail`, `streetlight`, `signage`, `stormDrain`, `graffiti`, `vegetation`, `blight`, `illegalDumping`, `littering`, `highVegetationWeeds`, `fire`, `other`
    - `samsaraDashboardUrl` string, required: Organization-scoped URL that opens this Watchpoint in the Samsara dashboard.
    - `status` 'unknown' | 'active' | 'completed', required: Current lifecycle status of the watchpoint. Valid values: `unknown`, `active`, `completed`
    - `updatedAtTime` string, required: Time when the public watchpoint projection was most recently updated.

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)