Introduction to Ninox API

updated 10 days ago

Understand Ninox API and set up your environment

Ninox moved from ninoxdb.de to ninox.com. The current interface is api.ninox.com/v1. We recommend building new integrations on top of the new interface.

The old interface api.ninoxdb.de/v1 continues to work, so you don't need to migrate old integrations built with Zapier, Make, or other custom solutions.

Requirements for using the Ninox API

To use the Ninox API, you need the following:

Ninox license
Ninox Personal Access Token
Ninox REST API
Depending on the details of your server environment:
- Public Cloud, Private Cloud, or Private Cloud On-Premises
- Zapier, Make, or a similar solution

Use Postman to send API requests. Alternatively, call endpoints in your shell/terminal using the cURL command. A third option is the http function in the Ninox formula editor.

API reference

The Ninox API is an organized RESTful API. It consists of predictable URLs, form-encoded requests, JSON-encoded responses, and common HTTP response codes. The API also uses standard authentication and verbs.

Authentication

The Ninox API uses Bearer Tokens to authenticate requests. View and manage your Personal Access Tokens in your admin settings in the Ninox web app.

To authenticate your API requests, include the accessToken in the HTTP Authorization header. Content in curly brackets { } signifies a placeholder. Both the curly brackets and the content within must be replaced for the authentication to work.

-H "Authorization": "Bearer {accessToken}"

Ninox recommends that API requests be made over HTTPS. In the Public and Private Cloud, HTTP requests are redirected to HTTPS. If you try to make API requests over plain HTTP and don't follow the redirect, they will fail. Even if you have a username and password, API requests without authentication will also fail.

Content type

Ninox expects services to provide their responses in JSON. To provide a response as a valid JSON object, the services need to provide application/json in the HTTP Content-Type representation header.

-H "Content-Type": "application/json"

Obtaining a Personal Access Token

The Personal Access Token, or API key, is included with every HTTP request made to the Ninox API.

If you are the owner of a workspace, follow the steps below to obtain the API key:

Visit ninox.com.
Click the Start Ninox button to open the web app.
- If you don't see the Start Ninox button, log in with your Ninox credentials first.
In the top-right corner, click the Actions gear icon.
In the drop-down menu, select Integrations.
In the pop-up window, click the Generate button.
Copy the API key to your clipboard.

To delete or revoke a Personal Access Token, click the Delete Token cross mark icon that appears to the right of the generated API key.

Your Ninox API keys grant read and write access to all of your databases, so keep your tokens secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Errors

Ninox uses conventional HTTP response codes to indicate whether an API request was successful or unsuccessful. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx indicate a server error.

HTTP response status codes

Successful responses

Status Code	Definition
200 OK	The request has succeeded. The meaning of the success depends on the HTTP method: GET: The resource has been fetched and is transmitted in the message body. HEAD: The representation headers are included in the response without any message body. PUT or POST: The resource describing the result of the action is transmitted in the message body. TRACE: The message body contains the request message as received by the server.
201 Created	The request has succeeded and a new resource has been created as a result. This is typically the response sent after POST requests, or some PUT requests.
202 Accepted	The request has been received but not yet acted upon. It is noncommittal, since there is no way in HTTP to later send an asynchronous response indicating the outcome of the request. It is intended for cases where another process or server handles the request, or for batch processing.
204 No Content	There is no content to send for this request, but the headers may be useful. The user-agent may update its cached headers for this resource with the new ones.

Client error responses

Status Code	Definition
400 Bad Request	The server could not understand the request due to invalid syntax.
401 Unauthorized	Although the HTTP standard specifies "unauthorized," semantically this response means "unauthenticated." That is, the client must authenticate itself to get the requested response.
403 Forbidden	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server.
404 Not Found	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client. This response code is probably the most famous one due to its frequent occurrence on the web.
422 Unprocessable Entity (WebDAV)	The request was well-formed but was unable to be followed due to semantic errors.

Server error responses

Status Code	Definition
500 Internal Server Error	The server has encountered a situation it doesn't know how to handle.
501 Not Implemented	The request method is not supported by the server and cannot be handled. The only methods that servers are required to support (and therefore that must not return this code) are GET and HEAD.
502 Bad Gateway	This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response.