Overview

Navixy GraphQL API is the programming interface of several Navixy products and of the platform services that run your account, through one endpoint.

Navixy GraphQL API is separate from the RESTful Navixy API. The two APIs have different endpoints, authentication, and data models. Use the REST documentation for the Platform API and the Admin Panel API, and this space for the GraphQL API.

Navixy GraphQL API is the programming interface of several Navixy products and of the platform services that run your account. Not every Navixy product is described here: some products have no API, and some have an API of their own. Each product based on this API has a separate section: you can read about your workspace's products and ignore the rest. All products share one endpoint, one access token, and one way of sending requests.

The API is based on GraphQL. Every request is an HTTP POST to one endpoint, authenticated with an OpenID Connect access token. The endpoint is https://api.eu.navixy.com/v4/graphql. To send your first request, see Getting started. For the token, see Authentication. If you're new to GraphQL, start with GraphQL basics.

Key concepts

These terms apply to every part of the API. Each product and platform service defines its own terms on its overview page.

Term	Definition
Organization	A company's account in Navixy Console, with its own workspaces, members, and roles. One person can belong to several organizations, including child organizations that a channel partner created for its customers.
Workspace	The space that holds the data of one customer and has its own set of products. Your access token names the workspace, so most operations take no workspace ID. Navixy Console creates workspaces.
Product	A part of Navixy that a workspace has or doesn't have, such as Business Data Repository or Tracking. The plan of the workspace decides which products it can have, and each product is billed separately. Each product that this API serves has its own field in the schema.
Platform service	A part of the API that works for every workspace, whatever its plan: Console, IAM, and Billing. The platform services manage your account: its organizations and workspaces, its roles, and its plans.
Access token	A signed JSON Web Token from the Navixy identity service. It names your organization and your workspace and lists the products of your workspace. Every request sends it in the Authorization header.

Products

A product works only in a workspace that has access to it. Your access token lists your workspace's products, and the API rejects operations with a product not on the list. See What your roles and products allow.

Products are billed separately, but they can use each other's records. Tracking and IoT Logic work with the records stored by Business Data Repository, Tracking can use its assets and devices, and IoT Logic can use its devices.

Business Data Repository

Business Data Repository manages your workspace's business data: the assets you track, their types and groups, GPS devices and inventories, geo objects, and schedules. You can add your own custom fields and lists and see who changed a record in the audit log.

Tracking

Tracking answers where your assets are and what their devices report. It returns the live state of assets and devices, follows that state as it changes, and calculates trips and stops from device messages.

IoT Logic

IoT Logic holds your workspace's flows. A flow processes your devices' messages as they arrive, for example, to calculate a value that a device doesn't send. You can list, create, change, and delete flows and choose the devices whose messages enter each flow.

Platform services

The platform services work in every workspace, regardless of which products it has.

Console

Console shows the organizations you belong to, the workspaces you can reach, and the workspace's products. You can enable or disable a product covered by the workspace's plan.

IAM (identity and access management) stores your organization's roles: what access each role gives and who holds it. You can create and change roles and assign them to members or revoke them.

Billing

Billing keeps what your workspace pays for: the plans it can subscribe to, subscriptions, prepaid balance with the statement, and the usage that products reported for it.

How requests work

Every operation is nested under the field of its product or platform service, and the response has the same shape. The following query reads the title of your workspace through the Business Data Repository product:

query {
  bdr {
    workspace {
      title
    }
  }
}

{
  "data": {
    "bdr": {
      "workspace": {
        "title": "Northwind Logistics"
      }
    }
  }
}

Send the query in the query field of a JSON body, with any variables in the variables field. Getting started shows the full HTTP request.

Shared API resources

The pages at the top of this space apply to every product and platform service. They state the rules that every product follows, so the product pages don't repeat them:

• GraphQL basics: GraphQL for developers who know REST, record IDs and the node query, and how subscriptions connect. See also tips and patterns.

• Getting started: Your first authenticated requests.

• Authentication: How to obtain and send an access token, and what your roles and products allow.

• Pagination and Filtering and sorting: How to page through list results and narrow them down.

• Error handling: Error structure, every error code, and how one request can partly fail.

• Optimistic locking: How the API prevents concurrent updates from overwriting each other.

• Deleting records: What a delete does, which references block it, and what you can't get back.

• Limits: Request rate, subscription, pagination, and input size limits.

Developer resources

• Public GraphQL schema: The full type system, one file for the shared types and one per product.

• Introspection: Explore the schema from your own GraphQL client.

Explore the API

Business Data Repository

Store and change assets, devices, geo objects, schedules, and your own fields and lists.

Tracking

Read where your assets are, follow their state as it changes, and get their trips and stops.

IoT Logic

Create the flows that process your devices' messages, and choose which devices enter each flow.

Console

See your organizations and workspaces, and enable or disable the products of a workspace.

IAM

Create roles, decide what each one gives access to, and assign them to members.

Billing

Choose a plan, subscribe your workspace, and read its balance and reported usage.