Technical reference

API environments

The Navixy IoT Logic API is available on multiple regional platforms to optimize performance and comply with data residency requirements.

Base URLs

Region	Base URL	Data Location
Europe	https://api.eu.navixy.com	European data centers
Americas	https://api.us.navixy.com	US-based data centers

Environment selection

Choose the environment that:

1. Is geographically closest to your operations (to minimize latency)

2. Complies with your data residency requirements

3. Matches your existing Navixy platform subscription

Both environments offer identical API functionality, but may differ in:

• Response times based on your geographic location

• Data storage location (important for compliance with regulations like GDPR)

• Maintenance windows and update schedules

Authentication

Authentication for the Navixy IoT Logic API uses API keys or user session hashes. For detailed information about authentication methods, obtaining API keys, and best practices, please refer to the Authentication documentation.

API rate limiting

To ensure system stability for all customers, the platform limits API requests to 50 requests per second per user and per IP address (for applications serving multiple users). These limits are applied based on user session hash and API keys.

When a rate limit is exceeded, the API returns a 429 Too Many Requests status code with a specific error message

To avoid rate limiting issues:

1. Implement exponential backoff for retries

2. Batch operations where possible

3. Cache frequently accessed data

4. Distribute non-urgent requests over time

Request formats

HTTP methods

Method	Usage	Examples
GET	Retrieving information	Flow listing, flow details
POST	Creating, updating, deleting resources	Creating, updating and deleting flows and nodes

Some read operations use POST requests with a request body instead of GET with query parameters. Always check the endpoint documentation for the correct method.

Content type

All requests and responses use JSON format:

Content-Type: application/json

All request bodies must be valid JSON objects. The API will return a 400 Bad Request response for malformed JSON.

Date and time formats

All timestamps in the API use ISO 8601 format in UTC timezone:

YYYY-MM-DDThh:mm:ssZ

Example: 2025-04-08T14:30:00Z represents April 8, 2025, at 2:30 PM UTC.

Response structure

All API responses follow a consistent JSON format.

Success responses

Success responses always include a success: true field and may include additional data:

{
  "success": true,
  "value": {
    // Requested data or resource
  }
}

For list operations:

{
  "success": true,
  "list": [
    // Array of requested items
  ]
}

Error responses

Error responses include success: false and a status object with details, for example:

{
  "success": false,
  "status": {
    "code": 292,
    "description": "IoT Flow Invalid"
  },
  "errors": [
    {
      "node_ids": [2],
      "message": "Node #2 is missing, but has a link from edge"
    },
    {
      "node_ids": [1],
      "message": "Data source node \"New Data Source\" (#1) must be at the start of flow"
    }
  ]
}

Response Fields:

• success: Always false for error responses

• status.code: Internal error code (see tables below)

• status.description: Human-readable error category

• errors: Array of detailed validation errors (present only for HTTP 400 responses)

  • node_ids: Array of affected node IDs (optional)

  • message: Human-readable error description

Common error codes

HTTP status	Internal code	Description	Context
400	292	IoT Flow Invalid	Flow validation failed
400	293	IoT Endpoint Invalid	Endpoint validation failed
400	294	IoT Node Invalid	Node validation failed
401	14	Invalid session	Authentication required or session expired
403	7	Access denied	Insufficient permissions
404	201	Not found	Requested resource doesn't exist
500	1	Database error	Internal server error

Validation errors (HTTP 400)

All validation errors return HTTP status 400 and include a detailed errors array. The following table lists all possible validation error messages:

Category	Error Message	Description
Flow Structure	Node #${node_id} is missing, but has a link from edge	Referenced node doesn't exist in the flow
	Data source node "${title}" (#${node_id}) must be at the start of flow	Data source node has incoming connections
	Output endpoint node #${node_id} must be at the end of flow	Output endpoint node has outgoing connections
	A flow starting from data source node #${node_id} must have an output endpoint node	Flow path doesn't terminate with an output endpoint
Graph topology	The flow's graph cannot contain cycles	Circular references detected in flow
	The flow's graph can't contain self-loops	Node connects to itself
	Node #${node_id} is involved in the message processing twice	Node is reachable through multiple paths
Connections	Nodes #${node_id1} and #${node_id2} have a duplicate connection	Multiple edges exist between the same nodes
	Logic node #${node_id} does not contain at least one relationship	Logic node has no outgoing connections
	Logic node #${node_id} contains invalid link types, only Then or Else is allowed	Logic node has non-conditional connection types
Node content	Node #${node_id} has incorrect content	Node configuration data is invalid
	Duplicate Switch Output #${output_number} action in Nodes: #${node_id1}, #${node_id2}	Same output number controlled by multiple action nodes
Resource limits	The total number of attributes in a flow must not exceed ${max_amount}	Flow contains too many attributes (limit: 200)
	The node identifier must be unique within the flow: non-unique ID is #${node_id}	Multiple nodes have the same ID
Output nodes	Nodes #${node_id1} and #${node_id2} are duplicated as output nodes	Multiple output endpoints in the same processing subgraph

Variables in error messages (e.g., ${node_id}, ${title}) are replaced with actual values in API responses.

Flow architecture

Flows in Navixy IoT Logic follow a directed graph architecture with specific requirements and constraints.

Basic requirements

Requirement	Description
Input nodes	Every flow must have at least one data source node
Output nodes	Every flow must have at least one output endpoint node
Node IDs	Each node has a unique ID within its flow (not globally unique)
Connections	Edges define directional data flow between nodes
Multiple connections	Nodes can have multiple incoming and outgoing connections
No cycles	Circular references are not supported

Flow validation

When creating or updating flows, the API performs several validation checks:

1. Node IDs must be unique within a flow

2. Each edge must reference valid node IDs

3. The flow must be acyclic (no circular references)

4. All nodes must be reachable from data sources

5. All required fields must be present for each node type

Flow states

State	Description	Effect
enabled: true	Active flow	The flow processes data in real-time
enabled: false	Inactive flow	Data is not processed by this flow

Individual nodes can also be enabled or disabled, allowing for partial flow activation.

Node positioning

The view property in nodes is used for visual representation in UI tools:

"view": {
  "position": {
    "x": 150,
    "y": 50
  }
}

While optional for API functionality, including this data helps maintain visual layout when editing flows later.

Node reference

Nodes are actual building bricks for your IoT Logic data flows. Each node has its destinctive purpose and capabilities. Now the following nodes are available:

• Data Source node - defines where data comes from.

• Initiate Attribute node - allows custom calculations to enrich ar standardize data.

• Logic node - allows validating logical conditins and routing data based on the outcome.

• Action node - enables the automation of sending commands to devices based on the context.

• Output endpoint node - Defines the destination of data running trough the flow.

For detailed Node reference with object schemas and parameters, see Nodes.

API rendpoint reference

See OpenAPI specification in API reference.

Best practices

Practical tips for IoT Logic implementations

Flow design

1. Plan your flow design before implementation

   • Sketch your flow structure including all nodes and connections

   • Identify device sources and required data transformations

   • Determine appropriate output endpoints

2. Create endpoints first before referencing them in flows

   • MQTT endpoints must exist before they can be referenced

   • Test endpoint connectivity independently before adding to flows

3. Use descriptive titles for both flows and nodes

   • Clear naming helps with maintenance and troubleshooting

   • Include purpose or function in the title

4. Test incrementally by adding one component at a time

   • Start with a minimal viable flow and expand

   • Test each node's functionality before adding complexity

5. Monitor data flow after implementation

   • Verify data is flowing as expected

   • Check for proper attribute transformation

Data processing

1. Keep expressions simple where possible

   • Complex expressions are harder to debug and maintain

   • Consider using multiple nodes for complex transformations

2. Use consistent naming conventions for attributes

   • Follow a pattern like category_attribute_unit

   • For example: engine_temperature_celsius

3. Document complex expressions with clear comments

   • Keep documentation for non-obvious calculations

   • Include business logic explanations

4. Consider data volume when creating flows

   • High-frequency data may impact performance

   • Multiple outputs multiply processing requirements

Security

1. Secure your MQTT connections with SSL when possible

   • Enable use_ssl: true for production environments

   • Use secure ports (typically 8883 for MQTT over SSL)

2. Rotate credentials periodically for MQTT endpoints

   • Update credentials every 90 days or after personnel changes

   • Use strong, unique passwords for each endpoint

3. Use unique client IDs for each MQTT endpoint

   • Avoid connection conflicts by using distinctive IDs

   • Consider including account ID and purpose in the client ID

4. Restrict topic access on your MQTT broker

   • Limit permissions to only necessary topics

   • Use topic structures that enable precise access control

Maintenance

1. Back up your flow configurations

   • Store JSON responses from successful flow creation

   • Document flow purposes and interconnections

2. Version your flows with sequential titles

   • Include version numbers in flow titles

   • Maintain a changelog of modifications

3. Regularly review active flows

   • Audit flows to ensure they're still needed

   • Remove or disable unused flows to reduce overhead

4. Keep a library of common patterns

   • Reuse successful flow patterns across applications

   • Standardize approaches to similar problems

Data security considerations

When working with the Navixy IoT Logic API:

1. API Keys: Protect your API keys as they provide full access to your account

2. MQTT Credentials: Use strong passwords for MQTT authentication

3. SSL: Enable SSL (use_ssl: true) for MQTT connections whenever possible

4. Data Privacy: Be mindful of what device data you transmit to external systems

5. Endpoint Security: Regularly audit your endpoints and disable unused ones

Troubleshooting

Issue	Possible Solution
Flow not processing data	Check that both flow and all nodes have enabled: true
MQTT connection failing	Verify credentials, domain, port, and SSL settings
Data transformations not working	Test expressions in isolation to identify issues
Missing data in output	Ensure all required attributes are being processed
API errors	Double-check JSON syntax and required fields
Flow validation errors	Ensure node IDs are unique and edges connect valid nodes
Unexpected data format	Verify the calculation expressions in processing nodes
Missing fields in response	Check if you have all required permissions