Overview & Authentication

Biosyn provides a multi-tenant REST API for location management, device orchestration, user sync, transaction monitoring, and command queuing.

Endpoints Overview

Category	Method	Endpoint	Description
Location	GET	/api/me	Retrieve profile and stats for authenticated location
Devices	GET	/api/devices	Retrieve a paginated list of devices
	POST	/api/devices	Assign a device to location
	GET	/api/devices/{device_serial}	Retrieve detailed information for a device
	GET	/api/devices/{device_serial}/status	Get real-time connection status
	POST	/api/devices/{device_serial}/command	Enqueue a preset command for execution
	DELETE	/api/devices/{device_serial}	Unassign a device from location
Users	GET	/api/users	Retrieve a paginated list of user records
	POST	/api/users	Create a new user or update an existing user
	GET	/api/users/{pin}	Retrieve a single user profile by PIN
	DELETE	/api/users/{pin}	Delete a user by PIN and sync with devices
	POST	/api/users/import	Bulk import or update multiple users
	DELETE	/api/users/clear	Delete specific or all users from location
Commands	POST	/api/commands	Queue a preset command for execution
	GET	/api/commands/{command_id}	Retrieve status and execution details for a command

---

Base URL & Transport

Because Biosyn operates a multi-server architecture, each organization/location is assigned to a specific server with its own API endpoint. All API endpoints are served under /api over HTTPS.

https://<YOUR_SERVER_URL>/api

---

How to Find Your API URL & Access Token

To find the specific Server URL and access token for your location:

1. Navigate to your organization in Biosyn: Organizations
2. Select your location (e.g. Foo Location).
3. Open the API Access Tokens section.
4. Copy your location's Server URL (e.g. https://server1.biosyn.dev/api) and generate / copy your API Token.

---

Authentication & Headers

Tenant API requests require HTTP Bearer Token authentication in the Authorization header using your location's API Token (LocationApiKey).

Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json

---

HTTP Status Codes

The API uses standard HTTP response status codes:

Code	Status	Description
200	OK	Request succeeded. Response body contains requested data or operation result.
201	Created	Resource successfully created.
204	No Content	Operation succeeded with no returned body (e.g. deletion).
400	Bad Request	Request body or parameters are malformed or invalid.
401	Unauthorized	Missing, invalid, or expired Location API key / Bearer token.
403	Forbidden	Authenticated location is not authorized to access the requested resource.
404	Not Found	Target resource does not exist for this location.
422	Unprocessable Entity	Payload validation failed (e.g., missing required schema fields or type mismatch).

---

Location Information

GET /api/me

Retrieve real-time summary statistics and profile information for the authenticated location.

Response Attributes

Attribute	Type	Description
id	Integer	Unique internal location identifier.
name	String	Name of the location.
is_active	Boolean	Location active status flag.
users_count	Integer	Total number of users in this location.
devices_count	Integer	Total number of devices assigned to this location.
created_at	String (ISO 8601)	Timestamp when location was created.
updated_at	String (ISO 8601) | Null	Timestamp when location was last updated.

---

Response Example

200 OK

{
  "id": 1,
  "name": "Headquarters Office",
  "is_active": true,
  "users_count": 142,
  "devices_count": 6,
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-08-26T12:00:00Z"
}