NeuronSW REST API
NeuronSW (NSW) API (Application Programming Interface) powers our customer portal and offers individual access to data for our clients who want to connect data into their internal systems. It supports OpenAPI standard for describing modern REST API. Behind this API is a software layer processing and analyzing audio data from machines around the world. Primarily, NSW provides REST API for developers to interact with in order to upload audio with labels, return results or events for selected assets.
What The Heck is a REST API?
An API is an application programming interface – in short, it’s a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format.
REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term ‘REST API,’ they are generally referring to an API accessed via HTTP protocol at a predefined set of URLs.
These URLs represent various resources – any information or content, which can be returned as JSON, HTML, audio files, or images. Often, resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT, PATCH and DELETE.
Using NeuronSW API
You can use the NSW Sandbox API environment for testing, which does not affect your production data. The URL you use to authenticate the request determines whether the request goes to production or sandbox environment.
PRODUCTION: new-api.neuronsw.com/v1/xxx ||| SANDBOX: sandbox-api.neuronsw.com/v1/xxx
Authentification with token
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
NSW supports HTTP authentication with the token. In order to authenticate with HTTP, you need to provide a username and password to receive an authentification token. You must send this token in the header when making requests to protected resources. The token will expire after 15 days from the first use.
To obtain token you need to call POST method to https://new-api.neuronsw.com/v1/api-token-auth/
NSW uses conventional HTTP response codes to indicate the success or failure of an API request. In general, there are three status code ranges you can expect:
2xxsuccess status codes confirm that your request worked as expected
4xxerror status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
5xxerror status codes are rare and indicate an error with NSW servers
4xx errors that could be handled programmatically (e.g., an upload is declined) include an error code that briefly explains the error reported.
List of important REST Endpoints
1) Audio upload & view – upload or return a list of recording for given components on the machine
(query parameters are described https://new-api.neuronsw.com/v1/docs/#audio_chunks-list)
(query parameters are described https://new-api.neuronsw.com/v1/docs/#audio_chunks-upload)
2) Audio download – returns audio in .FLAC format for given parameters
(query parameters are described https://new-api.neuronsw.com/v1/docs/#get_audio-list)
3) Labels – insert or retrieve labels for audio for selected time
(query parameters are described https://new-api.neuronsw.com/v1/docs/#label_subcategories-list)
(query parameters are described https://new-api.neuronsw.com/v1/docs/#label_subcategories-create)
4) Machine Results – returns computed predictions/anomaly score for given machine
(query parameters are described https://new-api.neuronsw.com/v1/docs/#model_results_machines-list)
4) Machine Components Results – returns computed predictions/anomaly score for given component on the machine
(query parameters are described https://new-api.neuronsw.com/v1/docs/#model_results_placements-list/)