API Reference

Complete reference for the SpatialFlow REST API. All endpoints are documented with request/response schemas and interactive Try It panels.

Base URL

https://api.spatialflow.io/api/v1

Authentication

All API requests require authentication via JWT bearer tokens or API keys.

JWT Token Flow

1. Obtain tokens by calling the login endpoint with your email and password. The response includes an access_token and a refresh_token, alongside token_type, expires_in, and the signed-in user.
2. Attach the access token to every request in the Authorization header:

   curl https://api.spatialflow.io/api/v1/geofences \
     -H "Authorization: Bearer <access_token>"

3. Access tokens expire after 24 hours by default. This is a platform-wide setting SpatialFlow controls, not something a workspace owner or admin can change. When a token expires, call the refresh endpoint with your refresh token to obtain a new access token without re-authenticating.
4. Refresh tokens expire after 7 days. After expiry, the user must log in again.

API Key Authentication

For server-to-server integrations, use an API key in the X-API-KEY header:

curl https://api.spatialflow.io/api/v1/geofences \
  -H "X-API-KEY: sf_..."

Manage API keys from the Account endpoints or the dashboard.

See the Authentication Guide for detailed setup instructions.

API Reference Sections

Browse the full API reference by resource. Each section contains endpoint documentation with request/response schemas and interactive Try It panels.

Resource	Description
Geofences	Create, manage, and query geofences with polygon and circle geometries
Workflows	Build automation workflows triggered by geofence events
Devices	Register devices, track locations, and manage tracking sessions
Webhooks	Configure webhook endpoints for real-time event delivery
Workspaces	Manage workspace settings and team members
Account	API key management, notifications, and account settings
Authentication	Login, logout, token refresh, password reset, and email verification
Subscriptions	Subscription plans, usage metrics, and billing

Use the sidebar to navigate all endpoints organized by resource tag.

Rate Limits

API requests are rate limited by authentication method, and several endpoints have their own stricter limits on top of that. See Rate Limiting for the tiers, the headers returned on a 429, and how event quota throttling differs from request rate limiting.

For plan-based usage limits (events/month, geofences, webhooks), see Plans, billing and usage.

Pagination

List endpoints support offset-based pagination:

curl "https://api.spatialflow.io/api/v1/geofences?offset=0&limit=50"

Error Handling

All errors return consistent JSON responses using Django Ninja's standard format:

{
  "detail": "Invalid geometry format",
  "error_code": "VALIDATION_ERROR"
}

Validation errors return detail as an array:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "geometry"],
      "msg": "Field required"
    }
  ]
}

See Errors for full details.

OpenAPI Specification

The complete OpenAPI 3.1 specification is available for download:

• Download OpenAPI spec

curl https://docs.spatialflow.io/openapi/openapi.json