Developer Documentation

Everything you need to integrate with the Nexus API Platform. Choose a topic below or browse the knowledge base.

REST API Overview

The Nexus REST API uses standard HTTP methods and returns JSON responses. All endpoints require authentication via Bearer token or API key in the Authorization header.

Base URL: https://api.nexusplatform.io/v2

Authentication

Include your API key in every request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.nexusplatform.io/v2/users

Rate Limits

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Error Handling

All errors return a consistent JSON structure with error.code, error.message, and optional error.details array. HTTP status codes follow REST conventions: 400 for bad requests, 401 for auth failures, 429 for rate limits, 500 for server errors.

Webhook Integration

Webhooks allow you to receive real-time notifications when events occur in your Nexus account. Instead of polling the API, you register an endpoint and we push events to you as they happen.

Setting Up Webhooks

Navigate to Settings → Webhooks in your dashboard, or use the API to create webhook subscriptions programmatically. Each webhook requires a publicly accessible HTTPS URL and a list of event types to subscribe to.

POST /v2/webhooks
{
  "url": "https://yourapp.com/webhooks/nexus",
  "events": ["user.created", "order.completed", "payment.failed"],
  "secret": "whsec_your_signing_secret"
}

Verifying Signatures

Every webhook request includes an X-Nexus-Signature header containing an HMAC-SHA256 signature. Always verify this signature before processing the payload to prevent replay attacks and ensure the request originated from Nexus.

Retry Policy

You can monitor webhook delivery status and manually retry failed deliveries from the dashboard.

Official SDKs

We maintain official client libraries for popular programming languages. Each SDK handles authentication, retries, pagination, and type safety so you can focus on building your integration.

JavaScript / TypeScript

npm install @nexus/sdk
// or
yarn add @nexus/sdk

The JavaScript SDK supports both Node.js (16+) and modern browsers. TypeScript definitions are included out of the box. The SDK uses fetch under the hood and supports custom fetch implementations for testing.

Python

pip install nexus-sdk

The Python SDK supports Python 3.8+ and provides both synchronous and async interfaces. It includes Pydantic models for all API objects, making it easy to work with typed data in your application.

Go

go get github.com/nexusplatform/nexus-go

The Go SDK follows idiomatic Go patterns with context support, structured error types, and automatic pagination via iterators. It has zero external dependencies beyond the standard library.

Community SDKs

Knowledge Base

Getting Started Guide ▼

Welcome to Nexus! This guide will walk you through creating your account, generating API credentials, and making your first API call. The entire process takes about 10 minutes.

Step 1: Create Your Account

Visit dashboard.nexusplatform.io/signup and register with your work email. You will receive a verification email within 60 seconds. After verifying, you will be prompted to create your organization and invite team members.

Step 2: Generate API Keys

Navigate to Settings → API Keys in your dashboard. Click "Create New Key" and choose the appropriate scope. We recommend creating separate keys for development and production environments. Store your secret key securely as it will only be shown once.

Step 3: Make Your First Request

Test your credentials by calling the /v2/me endpoint, which returns your account information. If you receive a 200 response with your organization details, you are all set to start building your integration.

Authentication Best Practices ▼

Proper authentication handling is critical for the security of your integration. Follow these best practices to ensure your API credentials remain secure and your application handles auth failures gracefully.

Key Rotation

Rotate your API keys every 90 days at minimum. Nexus supports having two active keys simultaneously, allowing you to rotate without downtime. Generate a new key, update your application configuration, verify it works, then revoke the old key.

Scoped Permissions

Always use the minimum scope necessary. If your integration only reads user data, create a read-only key rather than a full-access key. Available scopes include: read:users, write:users, read:orders, write:orders, admin:webhooks, and admin:billing.

Environment Isolation

Never use production API keys in development or testing environments. Create separate organizations or use the sandbox mode to ensure test data never leaks into production and development activity does not affect your rate limits.

  • Store keys in environment variables or a secrets manager, never in source code
  • Use different keys for different services within your infrastructure
  • Monitor the API key usage dashboard for unexpected patterns
  • Set up alerts for failed authentication attempts
Pagination & Filtering ▼

All list endpoints in the Nexus API support cursor-based pagination and flexible filtering. Understanding these patterns is essential for efficiently working with large data sets without hitting rate limits or memory constraints.

Cursor Pagination

Rather than traditional offset-based pagination (which becomes slow with large datasets), Nexus uses cursor-based pagination. Each response includes a next_cursor value that you pass as a query parameter to retrieve the next page of results.

Filtering

Most list endpoints support filtering via query parameters. Common filters include created_after, created_before, status, and type. Multiple filters can be combined and are applied with AND logic. For complex queries, use the search endpoint with our query DSL.

Performance Tips

  • Always specify a limit parameter (max 100, default 25)
  • Use fields parameter to request only the data you need
  • Cache cursor positions if you need to resume pagination later
  • For bulk data export, use the Export API instead of paginating through all records
Error Handling & Debugging ▼

Robust error handling ensures your integration remains reliable even when things go wrong. The Nexus API provides detailed error information to help you diagnose and resolve issues quickly.

Error Response Format

Every error response includes a machine-readable error.code (like INVALID_PARAMETER or RATE_LIMIT_EXCEEDED), a human-readable error.message, and an optional error.details array with field-specific validation errors.

Common Error Codes

  • AUTHENTICATION_FAILED - Invalid or expired API key
  • INSUFFICIENT_PERMISSIONS - Key does not have required scope
  • RATE_LIMIT_EXCEEDED - Too many requests, check Retry-After header
  • RESOURCE_NOT_FOUND - The requested entity does not exist
  • VALIDATION_ERROR - Request body failed validation
  • CONFLICT - Resource already exists or state conflict

Debugging Tools

Enable debug mode by adding X-Nexus-Debug: true to your requests. This returns additional timing information, cache status, and the resolved request parameters in the response headers. Never enable debug mode in production as it adds latency.

Migration Guide (v1 to v2) ▼

The v2 API introduces several breaking changes from v1. This guide covers every change and provides a step-by-step migration path. We recommend running both versions in parallel during migration to ensure a smooth transition.

Breaking Changes

  • Authentication header changed from X-API-Key to standard Authorization: Bearer
  • All timestamps now use ISO 8601 format instead of Unix epoch
  • Nested objects use snake_case consistently (previously mixed)
  • Pagination changed from offset-based to cursor-based
  • Error response structure completely redesigned

Migration Steps

First, update your authentication headers. Then update your pagination logic to use cursors. Next, update your data models to match the new field names. Finally, update your error handling to use the new error structure. Run your test suite after each step to catch regressions early.

The v1 API will remain available until December 2026, giving you at least 8 months to complete your migration. We strongly recommend starting the migration now to take advantage of the improved performance and new features in v2.

Submit a Documentation Request ▼

Can't find what you're looking for? Submit a documentation request and our team will create or improve the relevant documentation within 5 business days.