Skip to content

APIs Overview

Comprehensive API documentation for integrating with Nova Suite services.

Introduction

Nova Suite provides a rich set of APIs that enable developers to integrate our privacy-focused productivity tools into their applications. All APIs are built on modern REST principles with JSON responses, comprehensive error handling, and extensive documentation.

Available APIs

Nova AI API

Our flagship AI platform, providing access to ModelA 9-Series language models.

Base URL: https://aiservices.novasuite.one/api/v1/

Key Features: - Chat completions with streaming support - Text embeddings for semantic search - Function calling for tool integration - Content moderation and safety

View Nova AI API docs →

Nova ID API

Authentication and identity management for Nova Suite accounts.

Base URL: https://id.novasuite.one/v1

Key Features: - OAuth 2.0 and OpenID Connect support - Multi-factor authentication (MFA) - NUVE (Nova Unified Verification Engine) integration - Session management

View Nova ID docs →

Getting Started

1. Create an Account

Sign up for a Nova Suite developer account:

curl -X POST https://api.novasuite.one/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "SecureP@ssw0rd",
    "plan": "developer"
  }'

2. Generate API Keys

Access your dashboard to create API keys:

  1. Visit dashboard.novasuite.one
  2. Navigate to API Keys section
  3. Click Generate New Key
  4. Select appropriate scopes and permissions
  5. Save your key securely (it will only be shown once)

3. Make Your First Request

import requests

response = requests.get(
    "https://api.novasuite.one/v1/user/profile",
    headers={
        "Authorization": "Bearer nvai_sk_YOUR_API_KEY",
        "Content-Type": "application/json"
    }
)

print(response.json())

Authentication

All API requests require authentication using API keys passed in the Authorization header:

Authorization: Bearer nvai_sk_YOUR_API_KEY

API Key Formats

Service Prefix Example
Nova AI nvai_sk_ nvai_sk_1a2b3c4d5e6f...
Nova ID nvid_sk_ nvid_sk_7g8h9i0j1k2l...
Search nvsr_sk_ nvsr_sk_3m4n5o6p7q8r...

Security Best Practices

  • Never commit API keys to version control
  • Rotate keys regularly (every 90 days minimum)
  • Use environment variables to store keys
  • Implement proper key management in production

Rate Limiting

All APIs implement rate limiting to ensure fair usage and system stability.

Default Limits

Tier Requests/minute Requests/hour Requests/day
Free 60 1,000 10,000
Pro 600 10,000 100,000
Enterprise Custom Custom Custom

Rate Limit Headers

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 573
X-RateLimit-Reset: 1734567890

Handling Rate Limits

When you exceed rate limits, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "retry_after": 42
  }
}

Recommended retry logic:

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

Response Format

All APIs follow a consistent response format:

Success Response

{
  "data": {
    "id": "usr_abc123",
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-11-18T12:00:00Z"
  }
}

Error Response

{
  "error": {
    "message": "Resource not found",
    "type": "not_found_error",
    "code": "resource_not_found",
    "param": "user_id",
    "request_id": "req_xyz789"
  }
}

Common HTTP Status Codes

Code Meaning Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side error
503 Service Unavailable Temporary service outage

Pagination

List endpoints support pagination using cursor-based navigation:

Request Parameters

GET /v1/users?limit=100&after=usr_abc123
Parameter Type Description
limit integer Number of results (1-100, default: 20)
after string Cursor for next page
before string Cursor for previous page

Response Format

{
  "data": [
    {"id": "usr_001", "name": "Alice"},
    {"id": "usr_002", "name": "Bob"}
  ],
  "has_more": true,
  "next_cursor": "usr_002"
}

Example: Fetching All Pages

def fetch_all_users(api_key):
    users = []
    cursor = None

    while True:
        url = f"https://api.novasuite.one/v1/users?limit=100"
        if cursor:
            url += f"&after={cursor}"

        response = requests.get(url, headers={
            "Authorization": f"Bearer {api_key}"
        })

        data = response.json()
        users.extend(data['data'])

        if not data.get('has_more'):
            break

        cursor = data['next_cursor']

    return users

Webhooks

Subscribe to real-time events using webhooks:

Available Events

  • user.created - New user registered
  • ai.completion.completed - AI task finished
  • search.query.executed - Search performed
  • auth.login.succeeded - User logged in
  • auth.login.failed - Failed login attempt

Setting Up Webhooks

curl -X POST https://api.novasuite.one/v1/webhooks \
  -H "Authorization: Bearer nvai_sk_YOUR_KEY" \
  -d '{
    "url": "https://your-app.com/webhooks/nova",
    "events": ["ai.completion.completed"],
    "secret": "whsec_your_webhook_secret"
  }'

Verifying Webhook Signatures

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

SDKs & Client Libraries

Official SDKs for popular languages:

JavaScript/TypeScript

npm install @novasuite/sdk

import { NovaClient } from '@novasuite/sdk';

const client = new NovaClient({
  apiKey: process.env.NOVA_API_KEY
});

const user = await client.users.get('usr_123');

Python

pip install novasuite

from novasuite import NovaClient

client = NovaClient(api_key=os.getenv('NOVA_API_KEY'))
user = client.users.get('usr_123')

Go

go get github.com/novasuite/novasuite-go

import "github.com/novasuite/novasuite-go"

client := novasuite.NewClient(os.Getenv("NOVA_API_KEY"))
user, err := client.Users.Get("usr_123")

Ruby

gem install novasuite

require 'novasuite'

client = NovaSuite::Client.new(api_key: ENV['NOVA_API_KEY'])
user = client.users.get('usr_123')

API Versioning

Nova Suite APIs use URL-based versioning:

https://api.novasuite.one/v1/...
https://api.novasuite.one/v2/...  (coming soon)

Version Support Policy

  • Each API version is supported for minimum 18 months after release
  • Deprecation notices are sent 12 months before version retirement
  • Security updates are backported to all supported versions

Current Versions

API Current Version Status Support Until
Nova AI v1 Stable Ongoing
Nova ID v1 Stable Ongoing
Search v1 Stable Ongoing

OpenAPI Specification

Download OpenAPI (Swagger) specifications for all APIs:

Use with tools like Postman, Insomnia, or code generators.

Testing & Development

Sandbox Environment

Use our sandbox environment for development and testing:

https://api-sandbox.novasuite.one/v1

Sandbox features: - Isolated from production data - No rate limits - Test API keys with test_ prefix - Simulated responses for testing edge cases

Example Test API Key

export NOVA_API_KEY="test_nvai_sk_1234567890abcdef"

API Status & Support

Next Steps

Build amazing things with Nova Suite APIs.