REST API guide — TerrAlert

REST API guide — TerrAlertTerrAlert REST API: Developer GuideBase URL: https://terralert.io/api/v1This guide is the public reference for the API. The machine-readable contract is the OpenAPI document at https://terralert.io/api/openapi/v1.json, which lists every /v1 endpoint, field and error code. The interactive OpenAPI pages (/docs, /redoc, /openapi.json) are turned off in production.API access, meaning programmatic use of the API with an API key, is included on the Pro and Enterprise plans. The web app itself uses the same API on every plan.---VersioningEvery documented path starts with /v1, and every /v1 response carries the header API-Version: 1. Inside v1, changes are additive only: new endpoints, new optional parameters, new response fields and new error codes. Write clients that ignore fields they do not know. A breaking change gets /v2, and /v1 keeps working for at least six months after /v2 ships.The same endpoints also answer without the /v1 prefix. Those paths belong to the web app, are not part of the contract, and may change without notice, so integrations should always use /v1.Alert deliveries are at /v1/deliveries (the web app calls them /alerts).---AuthenticationCreate an API key on the API keys page of the web app, then send it in every request:curl https://terralert.io/api/v1/aoi \ -H "Authorization: Bearer ta_live_..."

A key looks like ta_live_Ab3dE6gH_ followed by 43 letters and digits. The first part, up to the second underscore, is the key's prefix: it is not secret, and the key list shows it so you can tell keys apart.

The full key is shown once, when it is created. TerrAlert stores only a SHA-256 hash of it, so a lost key cannot be recovered: revoke it and create another.

Keys belong to the workspace, not to a person. Only the workspace owner or an admin can create or revoke them, and a workspace can hold up to 25 active keys.

A key acts with the role of the person who created it (owner, admin, member or viewer). Webhook endpoints belong to the workspace too: with webhooks:read a key lists them (URLs masked), and with webhooks:write it registers, changes, tests and removes them if its creator is the owner or an admin. If that person leaves the workspace, the key keeps working with a member's rights: it can still list endpoints but no longer change them (403 workspace_role_insufficient). Revoke the keys of anyone who leaves.

A key can be given an expiry (30 days, 90 days or 1 year) or none.

Revocation takes effect on the next request: there is no cache in front of the key check.

Keys work only while the workspace's plan includes API access. If the plan lapses or moves below Pro, every key is refused with 403 api_access_not_in_plan until the plan is restored.

To rotate a key: create the new one, deploy it, then revoke the old one.

ScopesEach key has one or more scopes. A GET needs the :read scope of its resource; POST, PUT and DELETE need :write. A request outside the key's scopes gets 403 scope_missing.

Scope

Allows

aoi:read

List and read areas, their scenes, and scan jobs (GET /v1/aoi..., GET /v1/jobs/{task_id})

aoi:write

Create, change and deactivate areas; start scans (POST /v1/jobs/...)

detections:read

List and read detections, change events (/v1/events), map tiles (/v1/tiles/...) and comparisons (/v1/compare/...)

detections:write

Mark detections reviewed, set verdicts, create and turn off share links, acknowledge, resolve and reopen change events

export:read

GET /v1/detections/export (needs detections:read as well)

alerts:read

List notifications (GET /v1/alerts) and alert deliveries (GET /v1/deliveries)

alerts:write

Mark a notification or a delivery read

webhooks:read

List webhook endpoints

webhooks:write

assets:read

List and read monitored assets, their exposure and activity (GET /v1/assets...)

assets:write

Create, import, change and delete monitored assets

API keys cannot be used for billing, the team, data export and account deletion, support tickets, editing the profile, or managing API keys themselves: those answer 403 session_required. A leaked key therefore cannot create more keys or erase the account. GET /v1/auth/me works with a key.The web app's session tokenThe web app authenticates with the Supabase session of the person signed in, and the API accepts that token on every plan. It expires with the session, so it is not suitable for scripts: use an API key.Managing keysThe API keys page is the way to manage keys. The same operations are in the API, for the web app's session only:

Route

Does

GET /v1/api-keys

The workspace's keys, newest first: id, name, prefix, scopes, status (active, revoked, expired), created_at, created_by_email, expires_at, last_used_at, revoked_at. Never the key.

POST /v1/api-keys

Body {"name", "scopes", "expires_in_days"} (expiry optional, 1 to 730). The response's key field holds the key, this one time.

DELETE /v1/api-keys/{key_id}

Revokes the key. Revoking a revoked key succeeds.

---Rate LimitsEach API key has its own budget of requests a minute:

Plan

Requests a minute, per key

Pro

300

Enterprise

1,200, or as agreed

Every response to a request made with a key carries the budget as it stands after that request:

Header

Meaning

X-RateLimit-Limit

Requests allowed in a minute

X-RateLimit-Remaining

Requests left in the current minute

X-RateLimit-Reset

Seconds until the minute resets

Scene tile images (GET /v1/tiles/scene/{scene_id}/{z}/{x}/{y}.png) do not count against the budget, because a map view fetches hundreds of them. The web app's session is limited to 200 requests a minute per address instead.The actions below also have their own limit, which applies on top. Area creation is counted per workspace. The others are counted per key for a request made with a key, and per address for the web app.

Route group

Endpoint

Limit

Areas

POST /v1/aoi

100 an hour per workspace

Areas

DELETE /v1/aoi/{aoi_id}

30 an hour

Detections

GET /v1/detections/export

10 a minute

Detections

POST /v1/detections/{detection_id}/share

30 an hour

Detections

GET /v1/detections/{detection_id}/chip/{side}.{fmt}

180 a minute

Webhooks

POST /v1/webhooks

10 an hour

Webhooks

PATCH /v1/webhooks/{webhook_id}

60 an hour

Webhooks

DELETE /v1/webhooks/{webhook_id}

20 an hour

API keys

POST /v1/api-keys

20 an hour

API keys

DELETE /v1/api-keys/{key_id}

60 an hour

Account

PUT /auth/me

30 an hour

Team

POST /team/invite, POST /team/accept

20 an hour each

Billing

POST /billing/checkout, POST /billing/portal, POST /billing/cancel

10 an hour each

Enterprise

POST /enterprise/checkout

5 a minute and 20 an hour

Enterprise

POST /enterprise/inquiry

5 an hour

Support

POST /support/tickets

10 an hour

Support

POST /support/tickets/{ticket_id}/messages

30 an hour

Your data

GET /gdpr/export

5 an hour

Public

POST /content/contact

5 an hour

Public

POST /content/events

120 a minute

GET and POST /email/unsubscribe/{token}

30 a minute

Counters are shared by every API server, so the figures are exact rather than per process.When a limit is exceeded the API returns 429 Too Many Requests with the error code rate_limited and a Retry-After header: the number of seconds to wait before trying again. Wait at least that long; retrying sooner is refused again.import time, httpx def get(url, headers): while True: r = httpx.get(url, headers=headers) if r.status_code != 429: return r time.sleep(int(r.headers["Retry-After"]))---ErrorsEvery 4xx and 5xx response has the same body:{ "detail": "Your pro plan allows 20 active AOI(s). Upgrade your plan or deactivate an existing AOI.", "error": { "code": "aoi_quota_exceeded", "message": "Your pro plan allows 20 active AOI(s). Upgrade your plan or deactivate an existing AOI.", "request_id": "6f1c1a52-0a4e-4d8e-9a39-1f0b7c0a0d11" } }Branch on error.code: codes are stable and only ever added. detail and message are for people and may be reworded. For a validation error (422 validation_failed), detail is the list of field errors and message names the first one.

Status

Codes

400

bad_request, webhook_url_unsafe, idempotency_key_invalid

401

not_authenticated (no credentials), invalid_token (unknown key or expired session), api_key_revoked, api_key_expired

403

forbidden, scope_missing, workspace_role_insufficient (a viewer changing anything, or a member managing webhooks or keys), session_required, api_access_not_in_plan, plan_feature_unavailable (for example a webhook on Free), aoi_quota_exceeded, aoi_area_exceeded, scan_frequency_not_in_plan, asset_quota_exceeded

404

not_found: the resource does not exist or belongs to another workspace; the two are indistinguishable on purpose

405

method_not_allowed

409

conflict, event_already_acknowledged, event_already_resolved, event_resolved, event_open, event_merged, webhook_url_exists, api_key_limit_reached, idempotency_in_progress, asset_exists

413

payload_too_large (bodies are limited to 1 MB; an asset import to 8 MB)

415

unsupported_media_type (an asset import that is neither GeoJSON nor CSV)

422

validation_failed, invalid_geometry, invalid_bbox, aoi_area_too_small, idempotency_key_reused, invalid_import, import_too_many_rows

429

rate_limited (see Rate Limits)

451

unavailable_for_legal_reasons

500

internal_error: quote request_id to support

502, 503, 504

upstream_error, service_unavailable, upstream_timeout

The OpenAPI document lists every code with its meaning.Request IDsEvery response carries an X-Request-ID header, and every error body repeats it in error.request_id. Quote it when you contact support and the matching server log can be found at once. To use your own id (from a gateway, or a retry loop), send it as X-Request-ID: 8 to 128 characters from A-Z a-z 0-9 . _ : -. Anything else is replaced with a new id.---Idempotency-KeyA create that times out may or may not have gone through. To retry it safely, send an Idempotency-Key header with a value unique to that create (a UUID is ideal, 1 to 255 printable ASCII characters):curl -X POST https://terralert.io/api/v1/aoi \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Idempotency-Key: 6f1c1a52-0a4e-4d8e-9a39-1f0b7c0a0d11" \ -H "Content-Type: application/json" \ -d @area.json

Accepted by POST /v1/aoi and POST /v1/webhooks.

A repeat with the same key and the same body, within 24 hours, gets the first response again with the header Idempotent-Replayed: true. Nothing is created a second time and no quota is used.

The same key with a different body, or from a different person in the workspace, gets 422 idempotency_key_reused. Use a new key for a new request.

A repeat that arrives while the first is still being processed gets 409 idempotency_in_progress with Retry-After.

A request that fails (any error) stores nothing, so it can be retried with the same key once the problem is fixed.

Keys are remembered per workspace for 24 hours, then forgotten.

A replayed webhook registration does not repeat the signing secret: it has "secret_redacted": true instead, because secrets are never stored for replay.

---PaginationList endpoints take limit and offset, and answer with the APIResponse<T> wrapper:{ "data": [ ... ], "total": 142, "limit": 100, "offset": 0 }There is a next page while offset + limit < total.

Endpoint

Default limit

Maximum

GET /v1/aoi

100

1000

GET /v1/detections

500

GET /v1/deliveries

200

GET /v1/aoi/{aoi_id}/detections, GET /v1/aoi/{aoi_id}/scenes

200

GET /v1/assets, the exposure routes, GET /v1/assets/{asset_id}/events, GET /v1/aoi/activity

100

1000

GET /v1/aoi lists newest first, with the id breaking ties, so pages never overlap or skip an area. GET /v1/detections also returns page, which is offset divided by limit.---Areas of Interest (AOI)List AOIscurl "https://terralert.io/api/v1/aoi?limit=100&offset=0" \ -H "Authorization: Bearer $TERRALERT_API_KEY"active_only (default true) leaves out deactivated areas; send active_only=false to list them too.Create an AOIcurl -X POST https://terralert.io/api/v1/aoi \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "Amazon Basin Watch", "geometry": { "type": "Polygon", "coordinates": [[[-63,-2],[-61,-2],[-61,-4],[-63,-4],[-63,-2]]] }, "scan_frequency": "daily", "detect_types": ["deforestation", "fire"], "min_confidence": 0.80, "alert_channels": ["email", "webhook"], "use_policy_acknowledged": true }'Fields:

Field

Type

Required

Notes

name

string

yes

2 to 120 characters

geometry

GeoJSON

yes

Polygon, EPSG:4326, any size up to the plan's maximum (a shape with no area is refused). An area smaller than 10,000 m² or narrower than 100 m is watched through a box at least 100 m across.

use_policy_acknowledged

boolean

yes

true: you confirm the area is monitored within the acceptable use policy

scan_frequency

string

daily (default) / weekly / monthly / realtime (Pro and Enterprise); limited by plan

detect_types

string[]

deforestation (default) construction flooding fire vegetation_loss urban_expansion

min_confidence

float

0.0 to 1.0, default 0.6

alert_channels

string[]

email (default) webhook; Slack and Teams via a webhook URL

alert_policy

string

confidence (default) or corroborated (alert only once an independent source that can see the change type verifies it; see "Independent verification")

monitoring_mode

string

imagery (default): Sentinel-2 change detection plus the feeds. signals_only: the NASA FIRMS fire, GLAD/RADD forest-loss and flood feeds only, with no imagery, for covering a large asset portfolio cheaply. A signals-only area watches fire, flooding, deforestation and vegetation_loss only

alert_scope

string

all (default): notify on every change. assets_only: notify only when one of your monitored assets lies within alert_scope_radius_m of a change; the others are still recorded and listed in the inbox

alert_scope_radius_m

integer

0 to 50,000 metres, default 1,000

Plan limits: Free=1 AOI, Starter=3, Growth=8, Pro=20, Enterprise=30 or more, as configured at purchase. Signals-only areas have their own allowance and do not count toward these. They are part of Enterprise: 100 areas of up to 150,000 km² each unless the contract sets other limits. Free, Starter, Growth and Pro do not include them yet. A signals-only area answers 403 coverage_area_quota_exceeded when the allowance is used up and 403 coverage_area_not_in_plan on a plan without one. PUT /v1/aoi/{aoi_id} can switch an area's monitoring_mode; it then meets the other mode's allowance and size limit.Area responsesEvery endpoint that returns an area (GET /v1/aoi, GET /v1/aoi/{aoi_id}, POST /v1/aoi, PUT /v1/aoi/{aoi_id}) includes these fields about its imagery:

Field

Type

Meaning

latest_usable_scene_date

date or null

The newest image clear enough to compare: at most 20% cloud, covering at least half of the area. null until there is one. (latest_scene_date is the newest image stored, cloudy or not.)

imagery_status

object or null

Why there is no newer usable image: reason, image_date and percent, below. null while the area is paused or before its first check.

next_pass_estimate

date or null

Estimated date of the next Sentinel-2 pass, from the dates of the area's own images (cloudy ones included) in the last 60 days. null while the area is paused or when it has no image from the last 60 days.

watch_window

GeoJSON Polygon or null

For an area smaller than 10,000 m² or narrower than 100 m, the box watched around it. null for any other area, including a long, thin one whose box would be larger than 1 km², which is analysed as drawn.

watch_window_size_m

[int, int] or null

East-west and north-south size of that box, in metres, each a multiple of 10.

imagery_status.reason is one of:

reason

Meaning

image_date

percent

no_new_pass

No image newer than the newest usable one has arrived yet

Date of the newest usable image, or null when the area has no image yet

null

too_cloudy

The newest image was too cloudy to use

Date of that image

Cloud over the area, rounded up

partly_imaged

The newest image covered less than half of the area

Date of that image

Share of the area covered, rounded down

unreadable

The newest image could not be processed (a fault on TerrAlert's side, not the satellite's)

Date of that image

null

search_failed

The last check could not reach the satellite image catalogue; TerrAlert tries again automatically

null

Cloud and coverage are measured over the area itself, or over its box when it is watched through one.Python exampleimport os import httpx BASE = "https://terralert.io/api/v1" AUTH = {"Authorization": f"Bearer {os.environ['TERRALERT_API_KEY']}"} def list_aois() -> list[dict]: areas, offset = [], 0 while True: r = httpx.get(f"{BASE}/aoi", headers=AUTH, params={"limit": 100, "offset": offset}) r.raise_for_status() page = r.json() areas += page["data"] offset += page["limit"] if offset >= page["total"]: return areas for aoi in list_aois(): print(aoi["name"], aoi["detection_count"])JavaScript exampleconst BASE = 'https://terralert.io/api/v1'; const auth = { Authorization: `Bearer ${process.env.TERRALERT_API_KEY}` }; async function listAois() { const res = await fetch(`${BASE}/aoi?limit=100`, { headers: auth }); if (!res.ok) { const { error } = await res.json(); throw new Error(`${error.code}: ${error.message} (request ${error.request_id})`); } const { data } = await res.json(); return data; }---DetectionsList detectionscurl "https://terralert.io/api/v1/detections?limit=50&min_confidence=0.85&sort=score" \ -H "Authorization: Bearer $TERRALERT_API_KEY"Query parameters:

Parameter

Type

Default

Notes

aoi_id

uuid

none

Filter to a single AOI

change_type

string

none

deforestation construction etc.

min_confidence

float

0.0

Minimum model score, 0 to 1

date_from

date

none

YYYY-MM-DD scene capture date

date_to

date

none

YYYY-MM-DD

min_area_km2

float

none

Filter small detections

reviewed

boolean

none

true / false

bbox

string

none

minLon,minLat,maxLon,maxLat in degrees (EPSG:4326): only detections that intersect the box

sort

string

newest

newest, oldest, area (largest first) or score (highest model score first)

limit

int

Max 500

offset

int

bbox needs west < east within -180 to 180 and south < north within -90 to 90; anything else is 422 invalid_bbox. A box across the antimeridian is two requests. GET /v1/detections/export takes the same filters (including bbox) and format=csv (default) or format=geojson.Detection object{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "aoi_id": "...", "aoi_name": "Amazon Basin Watch", "scene_id": "...", "change_type": "deforestation", "confidence": 0.94, "area_km2": 3.2, "geometry": { "type": "MultiPolygon", "coordinates": [...] }, "capture_date": "2026-06-27", "satellite": "Sentinel-2", "alerted_at": "2026-06-27T14:38:11Z", "reviewed_at": null, "verdict": "real", "verdict_at": "2026-06-27T15:02:40Z", "verdict_with_imagery": true, "created_at": "2026-06-27T14:38:05Z", "centroid_lat": -3.46521, "centroid_lon": -62.21587, "label_source": "watch_list", "before_scene_id": "...", "before_capture_date": "2026-06-20" }centroid_lat and centroid_lon name a point that always lies inside the outline, even for an L-shaped or multi-part one. label_source says where change_type came from: watch_list means it is the category you chose to watch for that area (the model detects that something changed, not what kind of change it is), and signal:<feed>, for example signal:firms, means it is the feed's own label. before_scene_id and before_capture_date name the earlier image the change was found against; they are null for a signal detection, which has no image pair. CSV and GeoJSON exports carry the same facts as lat, lon, label_source and before_capture_date.confidence is the detection's model score: the model's own 0 to 1 score for a Sentinel-2 detection, or TerrAlert's mapping of the feed's confidence class for a NASA FIRMS, GLAD or RADD detection. It is not a calibrated probability, so a score of 0.9 does not mean a 90% chance that the change is real.alerted_at is when the alert was first delivered on any channel; it stays null while an alert is queued or retrying, and for a detection that never alerted. Detections written since October 2026 also carry their provenance: observed_at (the later image's capture date, or the feed event's newest point), model_id and model_version (the model that found it), input_version and policy_version (the version of the alert rules it was written under).Why this alertGET /v1/detections/{detection_id} adds a why object (it is null in lists):"why": { "recorded": true, "gate": "corroborated", "gate_label": "Independent verification", "gate_result": "released", "reason": "independently_verified", "explanation": "Alert released because an independent source that can see this kind of change confirmed it (see Verification).", "policy_version": "2026.10.1", "decided_at": "2026-06-27T14:38:05Z", "alerted_at": "2026-06-27T14:38:11Z", "model": {"model_id": "change-siamese-unet-s2", "model_version": "1.0.0", "checkpoint_sha256": "...", "input_version": "..."}, "before_capture_date": "2026-06-20", "after_capture_date": "2026-06-27", "confirmation": null, "verification": { "state": "verified", "label": "Verified", "summary": "Confirmed by NASA FIRMS fire detection 300 m away, between the two images.", "by_reviewer": false, "evidence": [{"kind": "signal", "source": "firms", "source_label": "NASA FIRMS fire detection", "consistent_with": "fire", "distance_m": 301.2, "observed_at": "2026-06-26T13:00:00Z", "days_after": 0, "quality": "high", "overlaps": true}], "sources": ["firms"], "window_closes_at": "2026-07-01T00:00:00Z", "checked_at": "2026-06-27T14:38:05Z", "policy_version": "2026.10.1" }, "nearby_signals": [{"source": "firms", "count": 3, "nearest_m": 301.2, "latest": "2026-06-26T13:00:00Z", "type_matched": true, "independent": true, "quality": "high", "overlaps": true, "consistent_with": "fire"}], "nearby_signals_note": "Only sources that can see this kind of change count, from another instrument, near the outline and dated around its images.", "caveats": ["The model score is uncalibrated: a score from 0 to 1, not a probability that the change is real."] }gate is the rule that decided: corroborated (an independent source that can see this kind of change verified it), confidence (the change was seen again on a later clear image, compared with an earlier baseline), signal (a NASA FIRMS, GLAD or RADD event) or manual (someone in your workspace marked it real in Triage). gate_result is released or held, and reason is a stable machine code for the sentence in explanation. recorded is false for a detection decided before decision records existed: its reason was not stored and none is invented. model is null for a signal detection, and confirmation is null when the change was never checked again.why.judgment is a trial evidence check of a Sentinel-2 detection (null for a signal detection and for detections written before it existed). mode is always shadow and provisional is true: it is recorded with provisional thresholds and never changes whether the detection alerts. judgment is likely_valid, likely_invalid or uncertain, rule_ids (with reasons, one sentence each) name the rules that produced it, and the evidence is grouped as supporting, contradicting, context and unavailable, each item with its kind (for example polygon_cloud_shadow, water_context, index_change, spatial_persistence), a plain summary and the measured value. The fields may change while it is a trial.Independent verificationEvery detection also carries verification_state and verification_summary (in lists too), and the detail's why.verification adds the evidence behind them. A source counts only when it can see the detection's kind of change, was made by another instrument, lies near the outline and is dated between the earlier image and a few days after the later one (never the time the detection was written):

change type

sources that can verify it

fire

NASA FIRMS active fire

deforestation, vegetation_loss

GLAD and RADD forest-loss alerts

flooding

NASA MODIS/VIIRS flood maps (partial at most)

construction

none at present (a Sentinel-1 radar source exists in the code but is not switched on, so construction is not_verifiable)

urban_expansion

none

A NASA FIRMS, GLAD or RADD detection can also be confirmed by a TerrAlert Sentinel-2 detection over it, and a GLAD detection by RADD (but never a feed by its own points).

verification_state

meaning

verified

an independent, high-quality observation lies on the outline, or someone in your workspace marked it real

partially_verified

an independent observation lies nearby but not on the outline, or is of lower quality

unverified

a source could confirm it and none has yet; why.verification.window_closes_at says until when

not_verifiable

no source covers this kind of change, or the one that does is not switched on for the area

contradicted

someone in your workspace marked it not real

null

not checked yet (detections written before October 2026)

verified and partially_verified release the alert under either alert policy; under corroborated nothing else does, apart from a reviewer marking the detection real. GET /v1/detections/{detection_id}/corroboration returns the same evidence by source (sources, each with type_matched, independent, quality, overlaps and consistent_with), the state and its sentence; radius_m and window_days are now the widest distance and the longest number of days after the later image of the sources that can verify the detection (0 when none can).A NASA FIRMS, GLAD or RADD detection alerts when its newest point is recent and its feed confidence is at least the area's min_confidence; until something independent confirms it, it says "Reported by <feed>, not verified by TerrAlert".VerdictsPUT /v1/detections/{detection_id}/verdict records a person's judgment, real, false or skip, and can be changed later. Send verdict_with_imagery: true only when the person had both evidence images (below) on screen; left out, the verdict is recorded as given without them. The detection object returns it as verdict_with_imagery: true, false, or null for a verdict given before October 2026 or no verdict at all. TerrAlert leaves verdicts given without the images out when it measures the model.curl -X PUT https://terralert.io/api/v1/detections/{detection_id}/verdict -H "Authorization: Bearer $TERRALERT_API_KEY" -H "Content-Type: application/json" -d '{"verdict": "real", "verdict_with_imagery": true}'Evidence images (every plan)Every model detection has two still images, the earlier and the later Sentinel-2 scene of the pair it was found in, cut to the same square around it. They are on every plan; the interactive split view (Before/After Comparison below) is the Pro and Enterprise feature.curl https://terralert.io/api/v1/detections/{detection_id}/chips -H "Authorization: Bearer $TERRALERT_API_KEY"{ "detection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "bbox": [-62.2201, -3.4697, -62.2116, -3.4612], "width": 512, "height": 512, "geometry": { "type": "MultiPolygon", "coordinates": [...] }, "before": { "scene_id": "...", "capture_date": "2026-06-20", "satellite": "Sentinel-2", "url": "/v1/detections/3fa85f64-.../chip/before.webp" }, "after": { "scene_id": "...", "capture_date": "2026-06-27", "satellite": "Sentinel-2", "url": "/v1/detections/3fa85f64-.../chip/after.webp" }, "attribution": "Contains modified Copernicus Sentinel data 2026" }Both images cover bbox (west, south, east, north in degrees) exactly, 512 x 512 px, north up, so you can draw geometry over them from the box alone. The box is the detection's outline made square on the ground and padded on every side by 200 m or half its size, whichever is larger. Fetch an image with the same header; url is relative to https://terralert.io/api and ends in .webp, and .png works too. before is null when no earlier image is recorded. An image answers 204 No Content when the box falls outside the stored scene, and carries an ETag and Cache-Control: private, max-age=86400, so send If-None-Match to get 304 Not Modified for one you already have. A detection raised by a public feed has no image pair: both routes answer 404 with the error code no_optical_pair. Show the attribution line wherever you show the images. Image requests have their own limit of 180 a minute.Dashboard statsReturns aggregate counts for the workspace:curl https://terralert.io/api/v1/detections/meta/stats \ -H "Authorization: Bearer $TERRALERT_API_KEY"{ "total_aois": 3, "active_aois": 3, "total_scenes": 48, "total_detections": 12, "unreviewed": 7, "pending_alerts": 1, "last_scan_at": "2026-06-27T14:38:11Z" }---Change eventsA change event is one physical change, however many times it is observed: a fire FIRMS sees every two hours, or a building site every Sentinel-2 pass outlines again, is one event with several observations (detections). Each detection carries its event_id.curl "https://terralert.io/api/v1/events?status=ongoing" \ -H "Authorization: Bearer $TERRALERT_API_KEY"Query parameters: aoi_id, status, event_type, severity (low, medium, high or critical), sort (recent, the default: newest observation first; severity: critical first, events without a severity yet last), include_merged (default false), limit (max 200), offset.

Status

Meaning

new

The first observation

ongoing

Observed again at about the same size

expanding

An observation more than 20% larger than every earlier one from the same kind of source

shrinking

An observation more than 20% smaller than the previous one from the same kind of source (a burn scar outlined smaller, a flood receding). It does not alert

stale

No further change seen for the type's window (fire 3 days, flooding 7, forest loss 30, construction and other change 90)

resolved

A fire or flood quiet for its window while its feed kept answering, or resolved by a person. Construction and other step changes never resolve on their own.

reactivated

Observed again after it went stale or was resolved, or reopened by a person

rejected

Every observation was marked false by a reviewer. A new observation at the place starts a new event; changing a verdict restores it (ongoing). The history names the reviewer

GET /v1/events/{id} adds the outline, every observation and the full history: each status change, merge and action with its reason, the observation that caused it and the person who acted. When one observation joins two events, they are merged into the older one (merged_into on the other).POST /v1/events/{id}/acknowledge, /resolve and /reopen (a member or above; an API key needs detections:write) take an optional body {"note": "..."}, which is kept in the history. An action the event's state does not allow answers 409 with event_already_acknowledged, event_already_resolved, event_resolved (acknowledge a resolved event), event_open (reopen an open one), event_merged or event_rejected (every observation is marked false: change a verdict instead).SeverityEach event carries severity_level and severity: how much it matters, from measured facts only, with the working shown. It is a ranking aid, never a probability, and no alert is held or routed by it. severity lists every factor with its value and points, the method (the rule table's name and version, terralert-severity-v1), the total points and not_considered (what it deliberately leaves out, such as the model's score).

Factor

Points

Affected area (the event's largest outline)

under 0.01 km²: 0, 0.01 to 0.1: 1, 0.1 to 1: 2, 1 km² or more: 3

Distance to your nearest monitored asset

within 100 m: 2, within 1 km: 1, 1 to 5 km: 0

That asset's criticality (counted within 1 km)

5: 2, 4: 1, otherwise 0

Change type

fire and flooding: 1, otherwise 0

Verification

verified: +1, contradicted: -1, otherwise 0

A total of 0 to 1 is low, 2 to 3 medium, 4 to 5 high and 6 or more critical. critical needs a monitored asset within 1 km, and a rejected event is always low. Of several assets in range, the one scoring the most points is used. The severity is computed when the event changes and again daily, so a new asset counts within a day. It is null until first computed.Only some observations alert: the first one of an event, the one that reactivated it or made it expanding, and the first one independently verified. A repeat observation of an event that already alerted is stored and shown, but not sent again (alert_state: "repeat" on the detection).Notifications (inbox)The changes one pass finds in one area are one notification, sent once to each destination (each person's email, each webhook). If more changes arrive in that area within its cooldown (alert_cooldown_minutes on the area, default 360, 0 to send every pass), they join the notification and are sent as one update when the cooldown ends.curl "https://terralert.io/api/v1/alerts?unread=true" \ -H "Authorization: Bearer $TERRALERT_API_KEY"Each notification lists its area, how many changes and their total area, what released it, its change events, and read_at: read state is per person, so one teammate reading it does not mark it read for the others. GET /v1/alerts/{id} adds every change it announced and every delivery; POST /v1/alerts/{id}/read marks it read for you.Alert deliveriesOne record per notification per destination (email or webhook), with its delivery status:curl "https://terralert.io/api/v1/deliveries?status=failed" \ -H "Authorization: Bearer $TERRALERT_API_KEY"Query parameters: status (pending/retrying/sent/failed), channel (email/webhook), limit (max 200), offset. group_id names the notification, kind is alert, update or outcome (the follow-up that says whether an early alert was confirmed). PUT /v1/deliveries/{id}/read sets read_at and never changes the status: a failed delivery stays failed.---LatencyGET /v1/latency?days=30 reports how long a change takes from the satellite to an alert, over your own areas: the median (p50_s) and 90th percentile (p90_s) in seconds for each stage, from the image being taken, through publication, download and processing, to the change being detected and the first alert delivered, plus feed points from observation to stored. A stage with fewer than 20 samples in the window says insufficient_data and gives no figure. status is ok when the end-to-end stage (alert) has enough samples, partial when only some stages do. The time from a change on the ground to the next clear image of it (2 to 5 days or more) is not included. An API key needs detections:read.Map TilesEvery tile route needs the same Authorization: Bearer header as the rest of the API (an API key needs detections:read).

Route

Returns

GET /v1/tiles/scene/{scene_id}/{z}/{x}/{y}.png

One scene's imagery as a 256 px PNG tile (204 outside the scene)

GET /v1/tiles/scene/{scene_id}/tilejson

TileJSON for that scene

GET /v1/tiles/aoi/{aoi_id}/tilejson

TileJSON for the area's latest processed scene

GET /v1/tiles/detections/{z}/{x}/{y}.mvt

Your detections as Mapbox Vector Tiles, layer detections

GET /v1/tiles/detections/tilejson

TileJSON for the detection layer

To use a scene in MapLibre GL JS, attach the key to tile requests. Do this only in a server-side or internal tool: a key in a public web page can be read by anyone who opens it.const map = new maplibregl.Map({ container: 'map', transformRequest: (url) => url.startsWith('https://terralert.io/api/') ? { url, headers: { Authorization: `Bearer ${API_KEY}` } } : { url }, }); map.addSource('terralert-scene', { type: 'raster', tiles: [`https://terralert.io/api/v1/tiles/scene/${SCENE_ID}/{z}/{x}/{y}.png`], tileSize: 256, }); map.addLayer({ id: 'scene-layer', type: 'raster', source: 'terralert-scene' });---Before/After Comparison# The two most recent processed scenes of an area curl https://terralert.io/api/v1/compare/aoi/{aoi_id}/latest-pair \ -H "Authorization: Bearer $TERRALERT_API_KEY" # Tile URLs and detections for a chosen pair of scenes curl https://terralert.io/api/v1/compare/{before_scene_id}/{after_scene_id} \ -H "Authorization: Bearer $TERRALERT_API_KEY"/v1/compare/{before_scene_id}/{after_scene_id} returns tile URL templates for both scenes, relative to the API base and under /v1, and the detections between them as GeoJSON.---Monitored assetsAn asset is something you own, insure or operate: a property (a Point), a power line (a LineString), a mine boundary (a Polygon), or their Multi forms, in EPSG:4326. Assets are not imaged themselves. TerrAlert matches them by distance against the detections and signals of your watched areas, so only events inside one of your areas can be matched. Assets belong to the workspace: every member sees the same register, and a viewer can read it but not change it.Each asset has your own external_id (a policy number, a pylon id; 1 to 200 characters, unique in the workspace), and optionally a name, up to 20 tags, a criticality from 1 to 5 and properties, your own attributes as a JSON object of at most 4 KB.

Plan

Assets per workspace

Free

Starter

250

Growth

1,000

Pro

10,000

Enterprise

100,000, or as agreed

Over the limit, a create or an import answers 403 asset_quota_exceeded and writes nothing.Create, read, change, delete# Create (Idempotency-Key accepted) curl -X POST https://terralert.io/api/v1/assets \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"external_id": "POL-0042", "name": "Riverside depot", "tags": ["insured"], "criticality": 4, "geometry": {"type": "Point", "coordinates": [-0.1276, 51.5072]}}' # Create or replace by your own id: 201 when created, 200 when replaced curl -X PUT https://terralert.io/api/v1/assets/by-external-id/POL-0042 \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Riverside depot", "geometry": {"type": "Point", "coordinates": [-0.1276, 51.5072]}}'

Route

Does

GET /v1/assets

List, by external_id. Filters: tag, external_id, q (text in the name or id), bbox; include_geometry=false leaves the shapes out. limit up to 1,000

POST /v1/assets

Create one. 409 asset_exists if the external_id is taken

GET and PUT /v1/assets/by-external-id/{external_id}

Read, or create or replace, by your own id. URL-encode it; a / inside it is allowed

GET /v1/assets/{asset_id}

Read

PUT /v1/assets/{asset_id}

Change the fields sent; the others stay as they are

DELETE /v1/assets/{asset_id}

Delete. An area made from it keeps being watched

A polygon whose edges cross, or a line without two distinct positions, is refused with 422 invalid_geometry.Bulk importPOST /v1/assets/import creates or updates up to 5,000 assets in one call, keyed on external_id, and answers once they are written: 10,000 assets are two calls. Send either a GeoJSON FeatureCollection (Content-Type: application/geo+json) with external_id in each feature's properties (or as the feature id), or a CSV file (Content-Type: text/csv) with a header row naming external_id, lat and lon, and optionally name, tags (separated by ;) and criticality. Other properties and columns are kept as the asset's properties. The file may be up to 8 MB.curl -X POST "https://terralert.io/api/v1/assets/import" \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Content-Type: text/csv" \ --data-binary @portfolio.csv{ "total": 5000, "created": 4987, "updated": 10, "rejected": 3, "dry_run": false, "rejects": [ { "row": 214, "external_id": "POL-7731", "reason": "lat and lon are both needed" } ] }A row that cannot be read is rejected with its row number (the CSV line number, or the feature's position in the file) and the rest are written. ?dry_run=true checks the file and counts what would change without writing anything. A file with more than 5,000 rows is refused with 422 import_too_many_rows, and one that cannot be read at all with 422 invalid_import.Exposure: which assets are near which eventsAn event is a detection or a signal (a NASA FIRMS fire hotspot, a GLAD or RADD forest-loss alert, a GIBS flood point) in one of your areas. Distance is the shortest distance on the WGS84 ellipsoid between the asset and the event, in metres, and 0 where they touch.

Route

Answers

GET /v1/assets/exposure/detections/{detection_id}

The assets near one detection, nearest first

GET /v1/assets/exposure/signals/{signal_id}

The assets near one signal

GET /v1/assets/exposure

Every (asset, event) pair in the workspace, nearest first

GET /v1/assets/{asset_id}/events

The events near one asset, nearest first

Parameters: radius_m (default 1,000, at most 50,000), since and until (dates the event was observed, inclusive), kind (all, detection or signal), source (comma-separated, for example firms), change_type and min_score (detections only), include_false (include detections reviewed as false), tag (only assets with this tag), limit (up to 1,000) and offset.curl "https://terralert.io/api/v1/assets/exposure?radius_m=2000&kind=signal&source=firms&since=2026-10-01" \ -H "Authorization: Bearer $TERRALERT_API_KEY"Each item names the asset (asset_id, external_id, asset_name, criticality), the event (kind, event_id, source, change_type, model_score for a detection, signal_confidence for a signal, verdict, observed_on, area_km2, aoi_id, aoi_name, event_lat, event_lon, recorded_at), distance_m, and for a detection detail_path, the API path with its evidence. verification_state (detections only) is the event's verification with a reviewer's verdict applied, and severity is the severity of this event for this asset (see "Severity" under Change events), computed from the pair: the event's area, distance_m, the asset's criticality, the change type and the verification.An area from an assetPOST /v1/aoi/from-asset makes a watched area from an asset plus a buffer, in one call: a mine boundary and the 2 km around it, or a corridor along a line.curl -X POST https://terralert.io/api/v1/aoi/from-asset \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"asset_id": "...", "buffer_m": 2000, "use_policy_acknowledged": true}'buffer_m is 0 to 20,000 (0 keeps a polygon's own boundary). The other fields are those of POST /v1/aoi, and the area is held to the same plan limits and to 5,000 km², the most one satellite tile reliably covers. A buffer that leaves the asset in separate pieces is refused with 422 invalid_geometry: use a larger buffer, or one area per piece. An API key needs aoi:write and assets:read.Coverage areas for a portfolioWatching thousands of properties with imagery is not possible (one Sentinel-2 download per area per pass). POST /v1/assets/coverage-areas instead proposes, or creates, a few large signals-only areas around your assets, watched through the fire, forest-loss and flood feeds, alerting only when an asset is within alert_scope_radius_m of a change.curl -X POST https://terralert.io/api/v1/assets/coverage-areas \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"tag": "wildfire-book", "buffer_m": 5000, "dry_run": true}'The proposal is the convex hull of the assets (all of them, or those with tag) plus buffer_m (100 to 50,000, default 5,000). When that is larger than your plan's signals-only area, the assets are grouped on a grid of 4, 2, 1, 0.5 or 0.25 degrees, the coarsest that fits, one area per cell. The answer lists each area with its asset count, size and outline, your allowance and whether everything fits (fits_plan). dry_run: true (the default) changes nothing; dry_run: false with use_policy_acknowledged: true creates the areas (detect_types default ["fire"], alert_scope default assets_only, alert_scope_radius_m default 1,000), all or none. Creating needs a member role and, for an API key, assets:write and aoi:write.Flood alerts reach assets only once the flood feed writes detections; until then a coverage area reports fire and forest loss.Activity summaries

GET /v1/assets/{asset_id}/activity?since=&until=&radius_m=&min_area_km2= summarises one asset: detections, changed area, review verdicts, signal counts per source, the nearest event and the last change. radius_m=0 counts what touches the asset (inside a mine boundary); a larger radius adds the zone around it.

GET /v1/aoi/activity?since=&until=&min_area_km2= does the same per area, and ranks the areas by meaningful changed area.

A detection counts as meaningful when its changed area is at least min_area_km2 and nobody has reviewed it as false. There is no hidden score. since defaults to 30 days before until, and until to today (UTC).---WebhooksSee the Webhook Integration Guide for payload format, signature verification, and retry policy.Register a webhook:curl -X POST https://terralert.io/api/v1/webhooks \ -H "Authorization: Bearer $TERRALERT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name": "My Server", "url": "https://my-server.com/terralert-hook"}'The response includes a one-time signing_secret. Store it securely: it is not shown again, not even when the same request is replayed with its Idempotency-Key. The URL is stored encrypted and every response shows it masked.Endpoints belong to the workspace: each receives the alerts of all its areas, whoever registered it. Optional filters narrow that down: aoi_ids (areas of the workspace), change_types and min_score (model score, 0 to 1). PATCH /v1/webhooks/{webhook_id} changes the filters, the name, or is_active (pause and resume); a filter sent as null is cleared.Webhooks are not available on the Free plan: POST /v1/webhooks returns 403 for a Free account, and alerts are not delivered to webhooks while an account is on the Free plan. A failed delivery is retried with exponential backoff, up to 5 attempts in total.---Data RetentionDetections and scenes older than your plan's retention window are automatically deleted:

Plan

Retention

Free

30 days

Starter

1 year

Growth

1 year

Pro

3 years

Enterprise

As configured

If a paid subscription ends, the account continues on the Free plan, and its full history is kept for 60 days so you can switch provider or retrieve it with the data export below. After those 60 days the Free plan's 30-day window applies.---Data Export and Account DeletionThese two actions belong to the person signed in, so they take the web app's session and refuse API keys (403 session_required). They are in the Your data section of the Account page.# Export your data: one JSON file (area and detection geometry as GeoJSON inside it) curl https://terralert.io/api/gdpr/export \ -H "Authorization: Bearer $SESSION_TOKEN" # Delete your account. This is immediate and cannot be undone. curl -X POST https://terralert.io/api/gdpr/delete \ -H "Authorization: Bearer $SESSION_TOKEN"The export includes your profile (with your email preferences), areas (with their alert settings: alert_policy, min_confidence, detect_types, scan_frequency), detections (with their geometry), alerts (including alert emails sent to you as a team member), webhooks (your workspace's, with their URLs, and any you registered in another workspace, with the URL masked), API keys (name, prefix, scopes and dates, never the key or its hash), billing fields, support tickets with their messages, team memberships, contact messages, data-rights requests, and the metadata of your sign-in account. It is limited to 5 requests an hour.Deleting the account deletes its workspace's API keys, so they stop working at once.Deletion responds with:

Field

Meaning

erasure_complete

true when every step finished, including at Stripe and Supabase

pending_steps

Steps that did not finish, each with a step name and a plain-language description; TerrAlert completes them by hand

request_id

The id of the data-rights request recorded for this deletion

retained

Plain-language list of what is kept on purpose, and for how long

detail

A summary message for the person who asked

anonymized_at

When the account was anonymised

If the database step fails, the request returns 500 and nothing in TerrAlert's database is changed.All documentation