Skip to main content

General

Versioning​

To avoid making backwards incompatible changes, the Nomi.ai API uses a versioning system. The current version is v1. You can specify the version in the URL path like so: https://api.nomi.ai/v1/nomis.

Rate Limits​

Use of the Nomi.ai API is subject to rate limits, but they are generous and should not affect normal use. If you hit the rate limit, you will receive a 429 Too Many Requests response, with the following body:

{
  "error": {
    "type": "TooManyRequests"
  }
}

Repeatedly hitting the rate limit may result in API access being revoked for your account. If you need a higher rate limit, please contact us support@nomi.ai.

Response Codes​

If the request is successful, you will receive a 2xx response, such as a 200 OK, 201 Created, or 204 No Content.

If the request is unsuccessful, you will receive a 4xx or 5xx response, such as a 400 Bad Request, 404 Not Found, or 500 Internal Server Error. 4xx errors indicate a problem with the request, such as missing or invalid parameters. 5xx errors indicates a problem with our server.If you repeatedly receive a 5xx error, please contact support at support@nomi.ai.

Request and Response Format​

Nomi.ai API responses are in JSON format.

When requests have a body, they should be in JSON format as well. It is also necessarily to explicitly specify the Content-Type header as application/json when sending a request with a body.

In these documents, we will use TypeScript to describe the expected format of request and response bodies. Even if you are not familiar with TypeScript, these definitions should be easy to understand as the types used (such as string, number, boolean, or array) are common to many programming languages. A series of strings separated by pipes (like "North" | "South" | "East" | "West") indicates that the value must be one of the listed strings.

All dates are represented as strings in ISO 8601 format (ex 2024-09-25T17:28:30.536Z). In the TypeScript definitions, we will use the type ISODateString for these dates.

UUIDs will also be represented as strings in the standard format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. In the TypeScript definitions, we use the type UUID.

Error Response Format​

Error responses will have the following format:

{
  "error": { "type": "SomeErrorNameHere" }
}

Depending on the error in question, there may be additional fields in the error object to provide more context. But all error responses will have the error field with a type field inside it.