← API overview · Preview
Authentication
Pass your API key as a bearer token. Keys are scoped per workspace and can be rotated at any time without downtime.
curl https://api.geosy.ai/v1/sites \
-H "Authorization: Bearer YOUR_API_KEY"
Errors
| Code | Meaning |
|---|
400 | The request was malformed; the body explains what to fix |
401 | Missing or invalid API key |
403 | Valid key, but no permission for this resource |
404 | The resource does not exist in this workspace |
429 | Rate limit reached; retry after the indicated delay |
500 | Our fault; safe to retry with backoff |
Rate limits
Preview keys carry generous fair use limits, returned in response headers. Tell us your expected volume and we will set limits that fit.
Sites
| Endpoint | What it does |
|---|
GET /v1/sites | List monitored sites |
POST /v1/sites | Create a site from a boundary or coordinates |
GET /v1/sites/:id | Fetch one site with its current state |
DELETE /v1/sites/:id | Stop monitoring a site |
Detections
| Endpoint | What it does |
|---|
GET /v1/detections | Query detections by site, type, confidence and time |
GET /v1/detections/:id | Fetch one detection with its evidence |
POST /v1/detections/:id/feedback | Mark useful or not useful to tune your models |
Assets
| Endpoint | What it does |
|---|
GET /v1/assets/search | Find vessels and aircraft by name or identifier |
POST /v1/assets/:id/follow | Start following an asset |
GET /v1/assets/:id/track | Retrieve movement history for a period |
Alerts
| Endpoint | What it does |
|---|
GET /v1/alerts | List alert rules |
POST /v1/alerts | Create a rule: where, what, confidence, channel |
DELETE /v1/alerts/:id | Remove a rule |
Cases
| Endpoint | What it does |
|---|
GET /v1/cases | List investigation cases |
POST /v1/cases | Open a case |
POST /v1/cases/:id/items | Pin a site, detection, asset or note to a case |
Reports
| Endpoint | What it does |
|---|
POST /v1/reports | Generate a report for a site, asset or case |
GET /v1/reports/:id | Fetch a completed report |
Webhooks
Register endpoints and choose events. Every delivery is signed so you can verify it came from us.
detection.created — a new detection at a monitored sitezone.entered / zone.exited — geofence eventsasset.dark — a followed vessel's signal went quietreport.completed — a generated report is ready
The complete live reference, with schemas and a sandbox, unlocks with your early access workspace. Request access.