API Endpoints

The Nimbus API provides backend services for model management and analytics. Note: Inference is performed locally by NimbusSDK.jl, not via API calls.

Start Here

Cloud API Authentication

Set up API keys, license checks, and secure access patterns.

Cloud API Reference

Review API scope, base URL, and service architecture.

Julia SDK Quickstart

Run authenticated setup and load your first pre-trained model.

Base URL

https://api.nimbusbci.com

Model Registry

GET /v1/models/list

List available pre-trained models based on your license tier. Authentication: Required (API key) Query Parameters:

Parameter	Type	Description
`api_key`	string	Your Nimbus API key (required)
`paradigm`	string	Filter by BCI paradigm: `motor_imagery`, `p300`, `ssvep` (optional)
`type`	string	Filter by model type: `NimbusLDA`, `NimbusQDA`, `NimbusProbit` (optional)

The model registry is used by the Julia SDK and currently includes NimbusLDA, NimbusQDA, and NimbusProbit.
NimbusSTS / Bayesian STS is Python SDK only and does not appear in the model registry.

Request:

curl "https://api.nimbusbci.com/v1/models/list?api_key=nbci_live_your_key"

Response:

{
  "models": [
    {
      "name": "motor_imagery_4class_v1",
      "version": "1.0.0",
      "type": "NimbusLDA",
      "paradigm": "motor_imagery",
      "n_features": 16,
      "n_classes": 4,
      "size_mb": 2.3,
      "download_url": "https://models.nimbusbci.com/rxlda/motor_imagery_4class_v1.jld2",
      "checksum": "sha256:abc123...",
      "requires_license": "free",
      "metadata": {
        "description": "4-class motor imagery classifier (left/right/feet/tongue)",
        "training_subjects": 50,
        "accuracy": "72-88%",
        "feature_type": "csp",
        "recommended_use": "Motor imagery BCI applications"
      }
    },
    {
      "name": "p300_binary_v1",
      "version": "1.0.0",
      "type": "NimbusQDA",
      "paradigm": "p300",
      "n_features": 8,
      "n_classes": 2,
      "size_mb": 1.8,
      "download_url": "https://models.nimbusbci.com/rxgmm/p300_binary_v1.jld2",
      "checksum": "sha256:def456...",
      "requires_license": "research",
      "metadata": {
        "description": "P300 target/non-target classifier",
        "training_subjects": 30,
        "accuracy": "85-92%",
        "feature_type": "erp",
        "recommended_use": "P300 speller applications"
      }
    }
  ],
  "total": 2
}

Response Fields:

name (string): Unique model identifier
version (string): Model version
type (string): Model type (NimbusLDA, NimbusQDA, or NimbusProbit)
paradigm (string): BCI paradigm (motor_imagery, p300, ssvep, etc.)
n_features (number): Expected number of input features
n_classes (number): Number of output classes
size_mb (number): Model file size in megabytes
download_url (string): Direct download URL for model file
checksum (string): SHA-256 checksum for verification
requires_license (string): Minimum license tier required
metadata (object): Additional model information

Filtering Examples:

# Get only motor imagery models
curl "https://api.nimbusbci.com/v1/models/list?api_key=nbci_live_...&paradigm=motor_imagery"

# Get only NimbusLDA models
curl "https://api.nimbusbci.com/v1/models/list?api_key=nbci_live_...&type=NimbusLDA"

Using in Julia SDK

The SDK automatically uses this endpoint when loading pre-trained models:

using NimbusSDK

# Authenticate
NimbusSDK.install_core("nbci_live_your_key")

# Load pre-trained model (SDK calls /v1/models/list internally)
model = load_model(NimbusLDA, "motor_imagery_4class_v1")

# SDK downloads, verifies checksum, and caches the model locally

Analytics & Logging

POST /v1/analytics/log

Log inference events and usage metrics (optional, for analytics tracking). Authentication: Required (API key) Request:

{
  "api_key": "nbci_live_...",
  "event_type": "inference",
  "model_name": "motor_imagery_4class_v1",
  "inference_type": "batch",
  "duration_ms": 245,
  "success": true,
  "metadata": {
    "n_trials": 20,
    "accuracy": 0.85,
    "mean_confidence": 0.78
  }
}

Request Fields:

Field	Type	Required	Description
`api_key`	string	Yes	Your API key
`event_type`	string	Yes	Event type: `inference`, `model_load`, `error`
`model_name`	string	No	Model identifier
`inference_type`	string	No	`batch` or `streaming`
`duration_ms`	number	No	Duration in milliseconds
`success`	boolean	No	Whether operation succeeded
`error_message`	string	No	Error description if failed
`metadata`	object	No	Additional event data

Response:

{
  "logged": true,
  "event_id": "evt_1234567890",
  "quota": {
    "used": 1235,
    "remaining": 48765
  }
}

cURL Example:

curl -X POST https://api.nimbusbci.com/v1/analytics/log \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "nbci_live_...",
    "event_type": "inference",
    "model_name": "motor_imagery_4class_v1",
    "inference_type": "batch",
    "duration_ms": 245,
    "metadata": {"n_trials": 20}
  }'

Analytics logging is optional. The SDK works without sending analytics data. Use this endpoint if you want to track usage patterns and performance metrics.

Health Check

GET /api/health

Check API status and availability. Authentication: Not required Request:

curl https://api.nimbusbci.com/api/health

Response:

{
  "status": "healthy",
  "timestamp": "2025-10-27T14:30:00Z",
  "version": "v1",
  "database": "connected"
}

Response Fields:

status (string): API status - "healthy" or "unhealthy"
timestamp (string): Current server timestamp (ISO 8601)
version (string): API version
database (string): Database connection status - "connected" or "disconnected"

Unhealthy Response:

{
  "status": "unhealthy",
  "timestamp": "2025-10-27T14:30:00Z",
  "error": "Health check failed"
}

Error Responses

All endpoints return consistent error responses:

{
  "error": "Error description",
  "code": "ERROR_CODE"
}

Common Error Codes:

Code	HTTP Status	Description
`MISSING_KEY`	400	API key not provided
`INVALID_FORMAT`	400	API key format invalid
`MISSING_EVENT_TYPE`	400	Event type not provided (analytics endpoint)
`INVALID_KEY`	401	API key is invalid or inactive
`KEY_EXPIRED`	401	API key has expired
`KEY_NOT_FOUND`	404	API key not found (revoke endpoint)
`METHOD_NOT_ALLOWED`	405	HTTP method not allowed
`QUOTA_EXCEEDED`	429	Monthly quota limit reached
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`SERVER_ERROR`	500	Internal server error
`NOT_CONFIGURED`	503	Server configuration issue

Rate Limits

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

Endpoint	Requests per Minute
`/v1/auth/validate`	100
`/v1/auth/refresh`	10
`/v1/auth/revoke`	10
`/v1/installer/github-token`	20
`/v1/models/list`	60
`/v1/analytics/log`	1000
`/api/health`	Unlimited

Rate Limit Headers: When you make an API request, the response includes rate limit information in the headers:

X-RateLimit-Limit: Maximum requests allowed per minute
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when the limit resets

Exceeding Limits: If you exceed the rate limit, you’ll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Usage Examples

Complete Workflow in Julia

using NimbusSDK

# 1. Authenticate
NimbusSDK.install_core("nbci_live_your_key")

# 2. Load pre-trained model (calls /v1/models/list)
model = load_model(NimbusLDA, "motor_imagery_4class_v1")

# 3. Run inference (local, no API call)
data = BCIData(features, metadata, labels)
results = predict_batch(model, data)

# 4. Optional: Log analytics
# (SDK can automatically log if configured)
println("Accuracy: $(sum(results.predictions .== labels) / length(labels))")

List All Available Models

# Get all models your license allows
curl -X GET "https://api.nimbusbci.com/v1/models/list?api_key=nbci_live_your_key" | jq '.models[] | {name, type, paradigm}'

Check Model Availability

# Check if specific model is available
curl -X GET "https://api.nimbusbci.com/v1/models/list?api_key=nbci_live_your_key" \
  | jq '.models[] | select(.name=="motor_imagery_4class_v1")'

License Requirements

Different models require different license tiers:

Model	License Required	Description
`motor_imagery_4class_v1`	Free	Basic 4-class motor imagery
`motor_imagery_2class_v1`	Free	Binary motor imagery
`p300_binary_v1`	Research	P300 target detection
`ssvep_multiclass_v1`	Research	SSVEP multi-frequency
Custom models	Commercial+	Customer-specific trained models

Your API key’s license tier determines which models you can access. Attempting to load a model above your tier will return a 403 Forbidden error.

Important Notes

Inference is Local

The Nimbus API does NOT perform inference. Inference happens locally via NimbusSDK.jl using RxInfer.jl. This approach provides: ✅ Privacy: Your EEG data never leaves your machine
✅ Speed: No network latency
✅ Reliability: Works offline after initial setup
✅ Scalability: No API server bottlenecks The API only provides:

Authentication and licensing
Pre-trained model distribution
Optional analytics collection

Model Caching

Models are downloaded once and cached locally:

# First call: downloads from API
model = load_model(NimbusLDA, "motor_imagery_4class_v1")  # ~2-3 seconds

# Subsequent calls: loads from cache
model = load_model(NimbusLDA, "motor_imagery_4class_v1")  # &lt;100ms

Cache location: ~/.nimbus/models/

Endpoints FAQ

Does this API run BCI inference directly?

No. Inference runs locally in NimbusSDK.jl. The API is used for authentication, model registry access, installation flows, and optional analytics logging.

Which endpoint is required first?

Start with authentication (/v1/auth/validate via SDK setup), then use /v1/models/list to discover available models for your license tier.

Why can model loading be fast after first use?

Models are cached locally after the first download, so subsequent load_model(...) calls typically avoid network fetches and complete much faster.

Next Read

Authentication

API key setup and management

Julia SDK

Complete SDK reference

Training Models

Train custom models

Code Examples

Working examples

Support

For API questions or model requests:

Email: hello@nimbusbci.com
API Status: https://api.nimbusbci.com/api/health
Documentation: https://docs.nimbusbci.com

Getting Started

Core Concepts

Models & Algorithms

Configuration & Setup

Examples

Development

Python SDK

Julia SDK

Cloud API Endpoints

API Endpoints

Start Here

Cloud API Authentication

Cloud API Reference

Julia SDK Quickstart

Base URL

Model Registry

GET /v1/models/list

Using in Julia SDK

Analytics & Logging

POST /v1/analytics/log

Health Check

GET /api/health

Error Responses

Rate Limits

Usage Examples

Complete Workflow in Julia

List All Available Models

Check Model Availability

License Requirements

Important Notes

Inference is Local

Model Caching

Endpoints FAQ

Next Read

Authentication

Julia SDK

Training Models

Code Examples

Support

Getting Started

Core Concepts

Models & Algorithms

Configuration & Setup

Examples

Development

Python SDK

Julia SDK

​API Endpoints

​Start Here

Cloud API Authentication

Cloud API Reference

Julia SDK Quickstart

​Base URL

​Model Registry

​GET /v1/models/list

​Using in Julia SDK

​Analytics & Logging

​POST /v1/analytics/log

​Health Check

​GET /api/health

​Error Responses

​Rate Limits

​Usage Examples

​Complete Workflow in Julia

​List All Available Models

​Check Model Availability

​License Requirements

​Important Notes

​Inference is Local

​Model Caching

​Endpoints FAQ

​Next Read

Authentication

Julia SDK

Training Models

Code Examples

​Support

API Endpoints

Start Here

Base URL

Model Registry

GET /v1/models/list

Using in Julia SDK

Analytics & Logging

POST /v1/analytics/log

Health Check

GET /api/health

Error Responses

Rate Limits

Usage Examples

Complete Workflow in Julia

List All Available Models

Check Model Availability

License Requirements

Important Notes

Inference is Local

Model Caching

Endpoints FAQ

Next Read

Support