Nexus API Documentation

Introduction

The Nexus API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Base URL

All API requests should be made to the following base URL:

https://api.nexus-platform.com/v2

Authentication

The Nexus API uses API keys for authentication. You can manage your API keys from your Nexus Dashboard. Your API keys carry many privileges, so be sure to keep them secure!

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value in the Authorization header.

Example Request

curl -X GET "https://api.nexus-platform.com/v2/fleet/vehicles" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

API Key Types

Nexus offers two types of API keys:

• Live keys - For production environments. These keys affect real data.
• Test keys - For testing and development. Actions performed with test keys won't affect your production data.

OAuth Authentication

For applications that act on behalf of users, we support OAuth 2.0 authentication. This allows your application to request authorization from a user to access specific resources.

To learn more about implementing OAuth authentication, please visit our Authentication Setup Guide.

Error Handling

The Nexus API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Nexus's servers.

HTTP Status Codes

Error Response Format

When an error occurs, the Nexus API will return a JSON response with information about the error.

{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'vehicle_id' is required.",
    "status": 400,
    "details": {
      "param": "vehicle_id"
    },
    "request_id": "req_1234567890"
  }
}

Rate Limits

The Nexus API implements rate limiting to protect our infrastructure and maintain a high quality of service for all users. Rate limits are applied on a per-API key basis.

Default Rate Limits

Rate Limit Headers

All API responses include headers that provide information about your current rate limit status:

• X-RateLimit-Limit: The maximum number of requests allowed in the current period
• X-RateLimit-Remaining: The number of requests remaining in the current period
• X-RateLimit-Reset: The time at which the current rate limit window resets, in UTC epoch seconds

Rate Limit Exceeded

If you exceed the rate limit, you will receive a 429 Too Many Requests response with information about when you can retry. The response will include a Retry-After header indicating how many seconds to wait before retrying.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "status": 429,
    "retry_after": 30,
    "request_id": "req_1234567890"
  }
}

API Versioning

The Nexus API is versioned to ensure backward compatibility as we evolve the platform. The current version is v2, which is reflected in the URL path of all API endpoints.

We recommend explicitly specifying the version in your API requests to ensure compatibility with your implementation.

Version Lifecycle

When we make backwards-incompatible changes to the API, we release a new version. We maintain older versions for a reasonable period to give you time to upgrade.

• Active: The current version of the API (v2).
• Deprecated: A version that will be removed in the future. We provide at least 12 months notice before removing a deprecated version.
• Sunset: A version that is no longer supported and will return an error response.

Version Status

For more information on our versioning policy, please visit our API Versioning Guide.