# Server API quickstart

> From a server key to your first page of locations and your first geofence event, with curl. Mint a token, read GET /v1/locations, create a geofence and a webhook, and watch the event arrive.

Source: https://docs.getbeekon.com/api/quickstart/

This page takes you from a server key to a page of locations, then to a geofence event on your webhook, with `curl` and `jq`. You need a **server key** (`bkserv_…`) for your project with these [scopes](https://docs.getbeekon.com/api/scopes/):

* `project:read` and `locations:read` for the first part;
* `geofences:write`, `webhooks:write`, `locations:write` and `events:read` for the second.

## Read your locations

1. **Set your key and region host.**

   Issue a server key on the console’s [API keys](https://docs.getbeekon.com/cloud/console/developers/#api-keys) page (owners and admins), choosing its scopes.

   The region is the second segment of your key: `bkserv_in1_…` lives on `api.in1.getbeekon.com`.

   ```sh
   export BEEKON_SERVER_KEY='bkserv_in1_REPLACE_WITH_YOUR_SECRET'
   export BEEKON_API="https://api.$(echo "$BEEKON_SERVER_KEY" \
     | cut -d_ -f2).getbeekon.com"
   ```

2. **Exchange the key for a session token.**

   ```sh
   export BEEKON_TOKEN=$(curl -sf -X POST "$BEEKON_API/v1/token" \
     -H "Authorization: Bearer $BEEKON_SERVER_KEY" | jq -r .access_token)
   ```

   The response is `{"access_token":"…","expires_in":3600}`. The token lasts `expires_in` seconds; mint a new one when it expires or when a call returns `401`. See [Authentication](https://docs.getbeekon.com/api/authentication/).

3. **Check which project the key belongs to.**

   ```sh
   curl -s "$BEEKON_API/v1/project" -H "Authorization: Bearer $BEEKON_TOKEN"
   ```

   ```json
   {
     "id": "0199b2c4-1f3a-7c11-9d2e-5a6b7c8d9e0f",
     "cell": "in1",
     "created_at": "2026-10-07T06:30:00.000Z",
     "name": "Fleet tracking",
     "status": "active"
   }
   ```

   A `403 {"error":"insufficient scope"}` here means the key lacks `project:read`. Issue a new key with the scopes you need.

4. **Read a day of locations, one page at a time.**

   ```sh
   curl -s -G "$BEEKON_API/v1/locations" \
     -H "Authorization: Bearer $BEEKON_TOKEN" \
     --data-urlencode "from=2026-10-06T00:00:00Z" \
     --data-urlencode "to=2026-10-07T00:00:00Z" \
     --data-urlencode "limit=500"
   ```

   ```jsonc
   {
     "locations": [
       {
         "id": "0190…",
         "device": {"install_id": "2bed7f6c-…"},
         "is_mock": false,
         "latitude": 12.9716,
         "longitude": 77.5946,
         …
       }
     ],
     "next_cursor": "lc1_…",
     "retention_floor": null,
     "schema_version": 1
   }
   ```

   While `next_cursor` is a string, there is more. Repeat the **same** request with `--data-urlencode "cursor=<next_cursor>"` added, until `next_cursor` is `null`:

   ```sh
   cursor=""
   while :; do
     page=$(curl -sf -G "$BEEKON_API/v1/locations" \
       -H "Authorization: Bearer $BEEKON_TOKEN" \
       --data-urlencode "from=2026-10-06T00:00:00Z" \
       --data-urlencode "to=2026-10-07T00:00:00Z" \
       --data-urlencode "limit=500" \
       --data-urlencode "cursor=$cursor") || break
     echo "$page" | jq -c '.locations[]
       | {install_id: .device.install_id, recorded_at, latitude, longitude}'
     cursor=$(echo "$page" | jq -r '.next_cursor // empty')
     [ -z "$cursor" ] && break
   done
   ```

One device, or the gated locations

Add `install_id=<id>` to read one device (the window must then be 24 hours or less), or `include_gated=true` to see the locations the server gated, each with a `gate.reason`. All parameters are on the [Locations](https://docs.getbeekon.com/api/locations/) page.

## Your first geofence event

Create a geofence and a webhook, upload two locations inside the fence from your server, and read the `geofence.enter` the server records. No app is needed: locations you send to [`POST /v1/ingest`](https://docs.getbeekon.com/api/ingest/) are checked against your geofences like the SDK’s.

1. **Create a geofence**: a 200 m circle.

   ```sh
   FENCE_ID=$(curl -sf -X POST "$BEEKON_API/v1/geofences" \
     -H "Authorization: Bearer $BEEKON_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Quickstart",
       "geometry": {
         "type": "circle",
         "center": {"latitude": 12.9716, "longitude": 77.5946},
         "radius_meters": 200
       },
       "notify_on_entry": true,
       "notify_on_exit": true
     }' | jq -r .geofence.id)
   echo "$FENCE_ID"
   ```

2. **Add a webhook** for geofence events. `endpoint_url` must be a public HTTPS URL you control; for a first test, a request-inspection service works. The receiver code is on [Webhooks](https://docs.getbeekon.com/api/webhooks/#a-complete-receiver).

   ```sh
   curl -sf -X POST "$BEEKON_API/v1/webhooks" \
     -H "Authorization: Bearer $BEEKON_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "endpoint_url": "https://hooks.example.com/beekon",
       "event_types": ["geofence.enter", "geofence.exit"]
     }' | tee webhook.json
   ```

   The response’s `secret` (`whsec_…`) signs every delivery. It is shown only once, so keep `webhook.json` until you have stored it.

3. **Upload two locations inside the fence**, 30 seconds apart. The second one confirms the enter ([what produces a geofence event](https://docs.getbeekon.com/api/geofences/#what-produces-a-geofence-event)).

   ```sh
   jq -n --arg a "$(uuidgen | tr A-Z a-z)" --arg b "$(uuidgen | tr A-Z a-z)" '{
     schema_version: 1,
     device: {install_id: "quickstart-device"},
     session_id: "quickstart",
     segments: [{locations: [
       {id: $a, timestamp: (now - 60 | todate), latitude: 12.9716, longitude: 77.5946,
        accuracy: 5, trigger: "interval", motion: "stationary", is_mock: false},
       {id: $b, timestamp: (now - 30 | todate), latitude: 12.9716, longitude: 77.5946,
        accuracy: 5, trigger: "interval", motion: "stationary", is_mock: false}
     ]}]
   }' > batch.json


   curl -s -o /dev/null -w '%{http_code}\n' -X POST "$BEEKON_API/v1/ingest" \
     -H "Authorization: Bearer $BEEKON_TOKEN" \
     -H "Content-Type: application/json" \
     --data-binary @batch.json
   ```

   `200` means the locations are stored. `quickstart-device` now appears in [Devices](https://docs.getbeekon.com/api/devices/) and counts towards this month’s monthly active users like any device.

4. **Read the event.**

   ```sh
   curl -s -G "$BEEKON_API/v1/events" -H "Authorization: Bearer $BEEKON_TOKEN" \
     --data-urlencode "limit=500" \
     | jq '.events[] | select(.type == "geofence.enter")'
   ```

   ```json
   {
     "id": "019e9f61-1400-7000-8000-0000000000e1",
     "type": "geofence.enter",
     "detected_at": "2026-11-01T06:40:12.000Z",
     "device": {"install_id": "quickstart-device", "session_id": "quickstart"},
     "evidence": "track",
     "geofence": {"id": "0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d"},
     "location": {
       "accuracy_m": 5,
       "latitude": 12.9716,
       "longitude": 77.5946,
       "recorded_at": "2026-11-01T06:40:10.000Z"
     },
     "occurred_at": "2026-11-01T06:40:10.000Z",
     "project_id": "019000b0-0000-7000-8000-0000000000b1"
   }
   ```

   The same event arrives at your webhook as a signed `POST`. In the `in1` region it follows the upload within seconds; [elsewhere it can take longer](https://docs.getbeekon.com/api/geofences/#what-produces-a-geofence-event).

To clean up, delete the fence and the webhook:

```sh
curl -s -X DELETE "$BEEKON_API/v1/geofences/$FENCE_ID" \
  -H "Authorization: Bearer $BEEKON_TOKEN"
curl -s -X DELETE "$BEEKON_API/v1/webhooks/$(jq -r .webhook.id webhook.json)" \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

## Next

* [Devices](https://docs.getbeekon.com/api/devices/) and [Trips](https://docs.getbeekon.com/api/trips/): the rest of the read surface.
* [Webhooks](https://docs.getbeekon.com/api/webhooks/): verify signatures, retries, and the delivery format.
* [Events](https://docs.getbeekon.com/api/events/): every event type, and the feed for catching up.
* [Errors](https://docs.getbeekon.com/api/errors/) and [Rate limits](https://docs.getbeekon.com/api/rate-limits/): what to retry, and how.
* [`openapi.yaml`](https://docs.getbeekon.com/openapi.yaml): generate a client.
