Qinertia Cloud API is a professional and highly accurate GNSS/INS post processing solution.

Qinertia is able to post-process RAW GNSS data to deliver centimeter-level positions. Several GNSS post processing modes are available such as single base station, Virtual Base Stations (VBS) and world wide Precise Point Positioning (PPP).

Qinertia is also capable of post processing IMU data to produce highly accurate and reliable position, velocity and attitude data even in harsh GNSS conditions. The solution is able to process SBG Systems INS as well as any GNSS receiver or third party IMU.

Qinertia Cloud API is an ideal solution to create complex but automated post processing workflows such as Lidar point cloud generation, photogrammetry geo-tagging and large survey jobs.

Qinertia Cloud API is accessed using a simple REST API and standard Qinertia CLI JSON processing files.

To use Qinertia Cloud API, you need a MySBG account, be an organization administrator with available processing credits.

The REST API is used to:

• create/view/update/delete containers
• create/upload/update/delete files within a container
• list/start/cancel/monitor processing
• monitor processing progress using webhooks
• list/download generated exports/reports

To ease integration with other services, most endpoints offer an optional metadata dictionary to store user defined data.

The Qinertia Cloud API is structured around three primary components: Containers, Container Files, and Processings. These components define a consistent and automated workflow for managing high-precision GNSS/INS post-processing jobs in the cloud.

Containers are temporary resources used to store, group, and organize the files you want to process via the GNSS/INS cloud service.

Key characteristics:

• Isolated: Independent and scoped to your organization
• Expiration: Automatically deleted 24 hours after creation, along with all its files
• Reusability: Supports uploading new files and launching multiple jobs during its lifetime
• Parallel-friendly: Allows simultaneous processing jobs using different configurations

Once a container is created, you can add, update and delete files within it.

Container files are the user-provided data that will be processed. There are two types of files:

1. input: RAW GNSS observations, INS sbgECom binary logs, IMU data, odometer velocity, etc
2. resources: Export profiles, report templates, geodesy resources, etc

Uploading a file is a two-step process:

1. Register the file on the server to receive upload instructions
2. Upload the file content directly to Amazon S3 using the provided instructions

Once a container is created and the necessary files are uploaded, you can start a processing by submitting a JSON processing settings file.

At any time, you can check the status and progress of a processing and retrieve any errors that may have occurred. Please prefer using webhooks instead of polling processings to monitor progress and status.

After a processing completes successfully, you can request and download the list of generated output files.

1. Create a container
2. Register and upload input/resources files
3. Start the processing job by submitting a JSON processing settings file
4. Monitor job status using webhooks (or via polling during tests)
5. Download results when complete
6. Optionally archive the job (jobs are archived and results are deleted automatically after 30 days)

This API implements standard REST API HTTP methods as detailed below:

• The GET method is used to retrieve a representation of a resource. If successful, GET returns a representation in JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). The GET method never modify any resource or state on the server.
• The POST method is used to create a new resource and/or to execute actions. On successful update or action, a HTTP status code 200 (OK) is returned with a JSON body detailing the operation status. In case of error the corresponding HTTP status code is returned such as 400 (Bad Request).
• The PATCH method is used to update an existing resource. On successful update or action, a HTTP status code 200 (OK) is returned with a JSON body detailing the operation status. In case of error the corresponding HTTP status code is returned such as 400 (Bad Request).
• The DELETE method is used to delete an existing resource.

This API uses standard HTTP status codes to report either a success or a failure. A success is only reported by the status code 200 and the response body always contains the requested resource or the result of an action using JSON.

All other status codes are used to report an error and the response body always contains a JSON detailing the error.

The table below lists all HTTP response status codes used by the API.

It indicates that the REST API successfully carried out whatever action the client requested.

The 200 response includes always a response body. The information returned with the response is dependent on the method used in the request, for example:

• GET an entity corresponding to the requested resource is sent in the response;
• POST/PATCH/DELETE an entity describing or containing the result of the action;

400 is the generic client-side error status, used when no other 4xx error code is appropriate. Errors can be like malformed request syntax, invalid request message format, or deceptive request routing etc.

The client SHOULD NOT repeat the request without modifications.

A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. The Authorization header is missing, doesn't start with "Bearer ", the access token is invalid or expired. More details will be provided to you in the response.

The client MAY repeat the request with a suitable authorization token in the HTTP header.

A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it, i.e., the user does not have the necessary permissions for the resource. A 403 response is not a case of an invalid access token; that would be 401 (“Unauthorized”).

Authentication will not help, and the request SHOULD NOT be repeated. Unlike a 401 Unauthorized response, authenticating will make no difference.

The 404 error status code indicates that the REST API can’t map the client’s URI to a resource but may be available in the future. Subsequent requests by the client are permissible.

No indication is given of whether the condition is temporary or permanent. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

A 409 status code indicates that the request is in conflict with the current state of the target resource. However, the user might be able to resolve the conflict and resubmit the request.

This status code is returned when the requested resource is not in the expected state, or the result of processing the request would create a conflict within the resource.

Example: A user would like to start a processing on an organization that already has an ongoing processing.

The 422 response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. It's probably due to invalid input parameters such as in invalid enum value.

The client SHOULD NOT repeat the request without modifications.

500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.

A 500 error is never the client’s fault, and therefore, it is reasonable for the client to retry the same request that triggered this response and hope to get a different response.

The API response is the generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

This API has been designed to be as easy to use as possible and a dedicated GitHub repository contains code samples.

You should also read the online Qinertia Documentation and other SBG Systems Support Center resources.

Please also visit MySBG to create/manage your account and monitor/buy online prepaid credits.

SBG Systems strives to minimize breaking changes that could disrupt existing integrations. However, as the Qinertia Cloud API evolves with new features and improvements, versioning is essential to ensure a stable and predictable developer experience.

Thanks to its RESTful and JSON-based design, the API is naturally resilient to change. When properly integrated, most changes can be introduced without breaking compatibility.

The Qinertia Cloud API implementation follows SBG Systems' standard Major.Minor.Build-Qualifier versioning scheme:

• Major: Incremented when changes introduce potential breaking modifications or significant new functionality.
• Minor: Incremented for backward-compatible improvements that do not require revalidation or code changes.

Each release updates the version number accordingly and includes a detailed changelog.

In addition to the implementation version, the REST API itself uses endpoint-level versioning via the URL path (e.g., /api/v1/..., /api/v2/...).
This versioning scheme is independent of the Major.Minor.Build version and is used to manage breaking changes to the API's structure or behavior.

Like any RESTful interface, changes fall into two categories:

• Backward-compatible changes: adding a new field to a JSON response or introducing a new endpoint.
• Breaking changes: removing an endpoint or significantly changing its request/response schema.

When a breaking change is introduced, a new version of the endpoint is created (e.g., /api/v2/...), while the previous version remains available to ensure compatibility with existing integrations.

Example: If the schema for /api/v1/info changes significantly, the updated version should be made available at:

/api/v2/info

The original /api/v1/info will continue to return the legacy schema, allowing clients to migrate at their own pace.

Please find below the list of changes for each API release.

New Features

• QCLD-199 - Update Qinertia Engine to latest 4.2 version
• QCLD-172 - Engine: Store in the input.log the list of files with information from the attached container
• QCLD-139 - Rework processing database architecture and endpoint to replace project with a transitive container

Improvements

• QCLD-200 - Improve js code sample error reporting
• QCLD-149 - Updated metadata type from array to a json node
• QCLD-124 - Automatically delete containers and processings results after a certain amount of time

We are releasing version 2 (v2) of the system, which introduces major changes in how input files are handled, how processing jobs are started, and how metadata is managed.

These modifications are part of a broader effort to improve flexibility, performance, and maintainability across the platform.

📂 Input File Handling

• The system for uploading, validating, and accessing input files has been completely reworked.
• File paths, formats, and access methods may differ from those used in v1.

⚙️ Processing Execution

• The logic for starting processing workflows has been redesigned.
• New APIs and triggering mechanisms replace older methods used in v1.

🗂️ Metadata Management

• Metadata is now structured and stored differently.
• You may need to update how metadata is created, retrieved, or passed through your workflow.

Because these changes represent a breaking shift from v1 to v2:

All users must carefully read the updated documentation and adapt their code accordingly.

Using v1 code or logic in v2 without adjustments may result in failures or incorrect behavior.

Container endpoints allow you to create and manage containers.

Containers are temporary resources used to store, group, and organize the files you want to process via the GNSS/INS cloud service.

You can perform the following operations:

• Create a new container
• List existing containers
• Update container metadata
• Delete a container

Container files endpoints allow you to create and manage files within a container.

You can perform the following operations:

• Register new files to the container
• Update file path/type/metadata
• Delete a file

Uploading a file is a two-step process that relies on Amazon S3:

1. Register the file on the server: Add files in container
2. Upload the file content using the information returned by the registration step: Upload file data

These endpoints are used to manage GNSS/INS processing jobs for your organization.

You can perform the following operations:

• Create a new processing job
• Monitor its status and progress
• Retrieve processing results
• Archive completed processings
• List all processings for an organization

Register webhooks to be notified whenever a processing job's status or progress is updated.

The Qinertia Cloud API uses webhooks to notify external services when a processing status changes.
A webhook is simply a URL exposed by your service that is called by SBG Systems’ cloud infrastructure when specific events occur.

For example, you can register a webhook that will trigger a POST request to your service when a processing completes.

Webhooks are managed by a dedicated notification service provided by SBG Systems — not directly by the Qinertia Cloud API.
All webhook-related API requests must be sent to: https://notification-api.sbg-systems.com/api/v2

Webhooks are registered at the organization level. If your organization has multiple ongoing processings, the webhook will be triggered for each status or progress update.

You should check the received payload to identify which processing has issued the event.

Before registering a webhook, you must set up an HTTP endpoint on your service that accepts POST requests.

1. Identify the events you want to monitor.
2. Create a publicly accessible endpoint on your server (must accept POST requests).
3. Ensure the endpoint responds within 5 seconds with a 2XX status code.
4. Register the webhook using the SBG Systems notification service.

Retry policy

If your endpoint is unavailable (due to a timeout, error, or non-2XX status), the webhook will be retried automatically.

Retry logic:

• The notification service retries up to 10 retries, using exponential backoff.
• The 10 retries are spread over approximately 3 days.
• If all attempts fail, the endpoint is considered defective and will be automatically disabled.

You can check missed webhooks events using this endpoint.

You can secure webhook calls and make sure the POST request has been issued by SBG Systems service.

In the webhook's HTTP request you will find 2 headers:

• Sbg-Timestamp: The time the webhook was sent.
• Sbg-Signature: A cryptographic signature using HMAC (Hash-based Message Authentication Code).

To verify the webhook:

1. Make sure the timestamp is not too old and consistent with your server time
2. Recreate the signature on your side using the HMAC secret generated when registering the webhook.
3. Compare it with the Sbg-Signature header.

The HMAC is computed as:

  HMAC(Sbg-Timestamp + "." + rawBody)

Using:

• Algorithm: SHA-256
• Secret: Provided when the webhook was created

Example (Node.js):

  const signature = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody, 'utf8')
    .digest('hex')

Endpoints providing general information such as API version, engine version, and available regions.