Skip to main content

Resources

The methods on client.geofences, client.workflows, client.webhooks, client.devices, client.account, and client.storage are generated from the SpatialFlow OpenAPI spec. Their names follow the pattern apps<Domain>Api<Operation>, for example appsGeofencesApiListGeofences.

Calling conventions​

  • Path and query parameters are positional, in the order the generated signature lists them. Required parameters come first.
  • A request body is one positional argument holding the request object.
  • The last argument is an optional Axios request config. See Per-request options.
  • Every method returns a promise of an Axios response. The API payload is in response.data.
  • Failed requests reject with a SpatialFlow error.
  • Each endpoint accepts an API key, or only an access token. An API key needs the scope named for the endpoint, and a missing scope gives a PermissionError. The sections below list the credential for each example.

Find a method​

Method names come from the OpenAPI spec the SDK was generated from, so check what your installed version has. Editor autocomplete on client.geofences. lists the methods, and the full signatures are in the package's dist/index.d.ts. The tables below list the operations most integrations use.

Geofences​

MethodArguments
appsGeofencesApiListGeofenceslimit?, offset?, activeOnly?
appsGeofencesApiCreateGeofencecreateGeofenceRequest
appsGeofencesApiGetGeofencegeofenceId
appsGeofencesApiUpdateGeofencegeofenceId, updateGeofenceRequest
appsGeofencesApiDeleteGeofencegeofenceId

An API key needs geofences:read to list and get, geofences:create to create, geofences:write to update, and geofences:delete to delete. Create, update, and delete also need an owner or manager, which for an API key is the role of the user who owns it.

import {SpatialFlow, CreateGeofenceRequest} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});

const list = await client.geofences.appsGeofencesApiListGeofences(50, 0);
for (const geofence of list.data.geofences) {
  console.log(geofence.id, geofence.name);
}
console.log(`${list.data.total_count} geofences in total`);

const polygon = {
  type: 'Polygon',
  coordinates: [
    [
      [-122.4, 37.8],
      [-122.4, 37.7],
      [-122.3, 37.7],
      [-122.3, 37.8],
      [-122.4, 37.8],
    ],
  ],
};

const created = await client.geofences.appsGeofencesApiCreateGeofence({
  name: 'Depot',
  geometry: polygon as unknown as CreateGeofenceRequest['geometry'],
  group_name: 'depots',
});
const geofenceId = created.data.id;

await client.geofences.appsGeofencesApiUpdateGeofence(geofenceId, {name: 'Main depot'});
await client.geofences.appsGeofencesApiDeleteGeofence(geofenceId);

The generated geometry type describes every accepted shape at once, so a plain GeoJSON Polygon needs the cast shown above. The API accepts Polygon, MultiPolygon, and circle geometries.

Workflows​

MethodArguments
appsWorkflowsApiListWorkflowslimit?, offset?, isActive?, status?, category?, search?
appsWorkflowsApiCreateWorkflowworkflowIn
appsWorkflowsApiGetWorkflowworkflowId
appsWorkflowsApiUpdateWorkflowworkflowId, workflowUpdate
appsWorkflowsApiToggleWorkflowworkflowId
appsWorkflowsApiActivateWorkflowworkflowId
appsWorkflowsApiDeleteWorkflowworkflowId

An API key needs workflows:read to list and get, workflows:create to create, workflows:write to update, toggle or activate, and workflows:delete to delete. The key's owner must be an owner or manager.

import {SpatialFlow} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});

const list = await client.workflows.appsWorkflowsApiListWorkflows(20, 0);
console.log(`${list.data.workflows.length} of ${list.data.total} workflows`);

await client.workflows.appsWorkflowsApiToggleWorkflow('3f1b6a52-0000-0000-0000-000000000000');

Build the nodes and edges of a workflow in the dashboard first and inspect an existing workflow with appsWorkflowsApiGetWorkflow to see the shape the API expects.

Webhooks​

MethodArguments
appsWebhooksApiListWebhookslimit?, offset?, isActive?
appsWebhooksApiCreateWebhookcreateWebhookRequest
appsWebhooksApiGetWebhookwebhookId
appsWebhooksApiUpdateWebhookwebhookId, updateWebhookRequest
appsWebhooksApiDeleteWebhookwebhookId
appsWebhooksApiRotateWebhookSecretwebhookId
appsWebhooksApiTestWebhookwebhookId, testWebhookRequest
appsWebhooksApiGetWebhookDeliverieswebhookId, limit?, offset?, status?, eventType?

Webhook endpoints accept only an access token, not an API key, and the user must be an owner or manager.

import {SpatialFlow} from '@spatialflow/sdk';

const client = new SpatialFlow({accessToken: process.env.SPATIALFLOW_ACCESS_TOKEN});

const created = await client.webhooks.appsWebhooksApiCreateWebhook({
  name: 'Dispatch',
  url: 'https://example.com/hooks/spatialflow',
  events: ['enter', 'exit'],
});
console.log(created.data.id);

const list = await client.webhooks.appsWebhooksApiListWebhooks(20, 0);
console.log(list.data.webhooks.length);

To check deliveries on your server, see Webhook verification.

Devices​

MethodArguments
appsDevicesApiListDevicesisActive?, includeGeofences?, group?
appsDevicesApiCreateDevicedeviceIn
appsDevicesApiGetDevicedeviceId
appsDevicesApiUpdateDevicedeviceId, updateDeviceIn
appsDevicesApiDeleteDevicedeviceId
appsDevicesApiGetDeviceEventsdeviceId, limit?, offset?

The deviceId argument of these methods is the device's UUID, which is the id in the create response. The device_id you set when creating a device (here truck-12) is your own identifier, and it is the one location ingest uses.

An API key needs devices:read to list, get and read events, devices:create to create (creating with a device_id that's already registered in the workspace re-registers that device and also needs devices:read and devices:write), both devices:write and devices:read to update, and devices:delete to delete.

import {SpatialFlow} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});

const created = await client.devices.appsDevicesApiCreateDevice({
  device_id: 'truck-12',
  name: 'Truck 12',
});
const deviceUuid = created.data.id;

const active = await client.devices.appsDevicesApiListDevices(true);
console.log(active.data);

const events = await client.devices.appsDevicesApiGetDeviceEvents(deviceUuid, 25, 0);
console.log(events.data);

Account and storage​

client.account covers API keys, the user profile, and notifications. Account calls accept only an access token, not an API key. client.storage covers presigned uploads and file downloads. An API key needs storage:write to create a presigned URL and complete an upload, storage:read to list files and get a download URL, and storage:delete to delete, and listing image files or downloading device files also needs devices:read. Most code does not call client.storage directly, because uploadGeofences wraps it. Deleting an uploaded file doesn't work yet: the delete endpoint can't find files stored by an upload.

Resources without a client property​

The package also exports the other generated API classes, such as TripsApi, PoliciesApi, SignalsApi, and ReportsApi. The client does not create them for you. Build one with a Configuration. The trips, policies, signals, and reports endpoints accept only an access token:

import {Configuration, DEFAULT_BASE_URL, TripsApi} from '@spatialflow/sdk';

const trips = new TripsApi(
  new Configuration({basePath: DEFAULT_BASE_URL, accessToken: process.env.SPATIALFLOW_ACCESS_TOKEN}),
);

These instances use the generated Axios client directly, so they do not apply the SDK's timeout default or convert failures into SpatialFlow errors. Failed calls reject with an AxiosError.