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.
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 (configurable by workspace admins). 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_live_..."

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 rate limits vary by subscription tier:

Tier	Requests/Hour	Notes
Free	100	Community support
Pro	1,000	Email support
Business	5,000	Priority support
Enterprise	Custom	Dedicated support with SLA

These are the default API key rate limits per subscription tier. Endpoint-specific limits (e.g., login, location ingestion) may also apply. See Rate Limiting for the full picture.

For event-based usage limits (events/month, geofences, webhooks), see Subscriptions and Limits.

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 Error Handling for full details.

OpenAPI Specification

The complete OpenAPI 3.0 specification is available for download:

• Download OpenAPI spec

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