Colota
GitHub

Several backends

Forwarder Reference

Endpoints, target types and settings of colota-forwarder

Every setting goes into the forwarder's .env. Forwarder covers the setup.

Endpoints

MethodPathAuthAccepts
POST/locationsyesColota's field-mapped payload, forwarded to all matching targets with geofence events
POST/owntracksyesThe OwnTracks app's HTTP payload. Only _type: "location" is forwarded
POST/overlandyesColota's Overland batch, sent whole to overland targets and split into single points for the rest
GET/healthno{ status, uptime, targets }, plus per-target delivery counts when the API key is sent

The API key is accepted as an Authorization: Bearer header, an x-api-key header or an ?api_key= query parameter. /health reads it from a header only.

Target Types

TypeUse forWhat the target gets
owntracksHome Assistant's OwnTracks integration, Dawarich, Reitti, OwnTracks RecorderOwnTracks format with X-Limit-U and X-Limit-D headers
traccarTraccarOsmAnd over GET by default. TARGET_n_METHOD=POST sends Traccar JSON
overlandDawarich's batch endpoint, any Overland serverThe whole Overland batch, unchanged. Point the URL at the batch endpoint
geopulse / colota / rawGeoPulse, the Colota integration for Home Assistant, custom serversThe Colota payload, unchanged

Environment Variables

VariableDefaultDescription
PORT3000Port to listen on
API_KEY-Required on every POST when set
FORWARD_TIMEOUT_MS30000Per-target HTTP timeout in milliseconds
MAX_BATCH_POINTS10000Largest /overland batch. Larger ones get 413
MAX_QUEUED_POINTS50000Points still being forwarded before /overland answers 503 with Retry-After
SPLIT_CONCURRENCY1Requests in flight per target while splitting a batch
SPLIT_DELAY_MS0Delay between requests per target while splitting a batch
TARGET_n_URL-Destination. n runs from 1 to 20 without gaps
TARGET_n_TYPErawowntracks, geopulse, traccar, colota, overland or raw
TARGET_n_METHODper typeGET or POST
TARGET_n_AUTH-Full Authorization header value, such as Bearer your-token or Basic <base64>. A target that reads ?api_key= takes it in the URL instead
TARGET_n_TIDCL (owntracks), colota (traccar)Tracker ID for owntracks targets, device ID for traccar targets
TARGET_n_USERcolotaX-Limit-U header for owntracks targets
TARGET_n_DEVICEphoneX-Limit-D header for owntracks targets. A tid in the payload replaces it
TARGET_n_FILTER_TID-Forward only points whose tid matches
TARGET_n_BATCH_MODEsplitsplit sends one request per point, latest only the newest point
TARGET_n_SPLIT_CONCURRENCYglobalPer-target SPLIT_CONCURRENCY
TARGET_n_SPLIT_DELAY_MSglobalPer-target SPLIT_DELAY_MS

Delivery Status

A 200 from the forwarder means it accepted the point, not that a target stored it. Send the API key to /health to see how each target is doing:

curl -H "x-api-key: $API_KEY" http://localhost:3000/health
{
  "status": "ok",
  "uptime": 1832.4,
  "targets": 2,
  "delivery": [
    { "target": 1, "host": "dawarich:3000", "ok": 412, "failed": 0, "lastOkAt": "2026-08-12T09:41:02.881Z" },
    {
      "target": 2,
      "host": "geopulse.example.com",
      "ok": 0,
      "failed": 412,
      "lastFailAt": "2026-08-12T09:41:02.883Z",
      "lastError": "HTTP 401"
    }
  ]
}

target is the n in TARGET_n, so it matches your .env even when two targets share a host. A rising failed count means the target rejects your points, and lastError says why. Counts start at the last restart.

Batch Handling

With the Overland template, or Dawarich with the Batch chip, Colota uploads several points in one request to /overland. Each target handles the batch by its type and TARGET_n_BATCH_MODE:

  • overland targets - Get the whole batch in one request. Use this whenever the backend reads Overland batches, as Dawarich does
  • latest - Gets only the newest point. Use it for Home Assistant, which tracks the current position, so a backlog does not replay through zone automations
  • split - The default. One request per point, one at a time and oldest first. SPLIT_CONCURRENCY and SPLIT_DELAY_MS set the pace

This setup sends Dawarich the full batch, Home Assistant the newest point and a self-hosted Traccar at most two requests at a time, 200 ms apart:

TARGET_1_URL=https://dawarich.example.com/api/v1/overland/batches?api_key=your-key
TARGET_1_TYPE=overland

TARGET_2_URL=http://homeassistant:8123/api/webhook/your-webhook-id
TARGET_2_TYPE=colota
TARGET_2_BATCH_MODE=latest

TARGET_3_URL=https://traccar.example.com:5055
TARGET_3_TYPE=traccar
TARGET_3_SPLIT_CONCURRENCY=2
TARGET_3_SPLIT_DELAY_MS=200

A phone that was offline uploads its whole backlog at once, and a split target turns that into one request per point. MAX_BATCH_POINTS and MAX_QUEUED_POINTS cap it. No points are lost: Colota keeps what it could not send and retries later.

Geofence Events

With Send enter and leave events, Colota also sends an event each time the phone enters or leaves a geofence. With Send current geofences, every point carries the geofences it is in as inregions. The forwarder sends each event where Colota would if it posted to that backend directly:

Target typeEvent from /locationsEvents from /overland
owntracksOwnTracks transition (_type: "transition" with event, desc, t, wtst)Not sent
traccarNot sentNot sent
geopulse / colota / rawPassed through unchangedNot sent
overlandPassed through unchanged, like a pointIn the batch's transitions array

An Overland event carries no wtst, which OwnTracks requires, so owntracks targets get events only from /locations. inregions reaches every type except traccar. See Request format for both settings.

Several Phones

TARGET_n_FILTER_TID sends each phone's points to its own targets:

  1. Give each phone a tid custom field in Settings → Connection → Request format → Custom fields, such as phone1
  2. Set TARGET_n_FILTER_TID to the same value on the targets for that phone
TARGET_1_URL=https://dawarich.example.com/api/v1/owntracks/points?api_key=user1-key
TARGET_1_TYPE=owntracks
TARGET_1_FILTER_TID=phone1

TARGET_2_URL=https://dawarich.example.com/api/v1/owntracks/points?api_key=user2-key
TARGET_2_TYPE=owntracks
TARGET_2_FILTER_TID=phone2

TARGET_3_URL=http://homeassistant:8123/api/webhook/your-webhook-id
TARGET_3_TYPE=owntracks

A target without TARGET_n_FILTER_TID gets every phone. The tid is free text, so phone1 or alice both work. The OwnTracks app limits its Tracker ID to two characters, so use a short code such as p1 there.

Certificates

A target with a certificate from your own CA, or a self-signed one, fails with a certificate error in lastError, such as UNABLE_TO_GET_ISSUER_CERT_LOCALLY or DEPTH_ZERO_SELF_SIGNED_CERT. The forwarder is the TLS client here, so the forwarder has to trust the CA. Mount the CA certificate, or the whole chain as one PEM file, and point Node at it:

environment:
  NODE_EXTRA_CA_CERTS: /certs/my-ca.pem
volumes:
  - ./my-ca.pem:/certs/my-ca.pem:ro

The file must be readable by the container's non-root user. Targets on the same Docker network can use plain http:// and need no certificate.