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.

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: `RxLDA`, `RxGMM` (optional)

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": "RxLDA",
      "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": "RxGMM",
      "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 (RxLDA or RxGMM)
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 RxLDA models
curl "https://api.nimbusbci.com/v1/models/list?api_key=nbci_live_...&type=RxLDA"

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(RxLDAModel, "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 in the Nimbus dashboard (coming soon).

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(RxLDAModel, "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(RxLDAModel, "motor_imagery_4class_v1")  # ~2-3 seconds

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

Cache location: ~/.nimbus/models/

Next Steps

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

API documentation

Core concepts

Model specification

Inference configuration

BCI Models

Examples & tutorials

Development

API Endpoints

API Endpoints

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

Next Steps

Authentication

Julia SDK

Training Models

Code Examples

Support

Getting started

API documentation

Core concepts

Model specification

Inference configuration

BCI Models

Examples & tutorials

Development

​API Endpoints

​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

​Next Steps

Authentication

Julia SDK

Training Models

Code Examples

​Support

API Endpoints

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

Next Steps

Support