> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbusbci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud API Endpoints

> Reference for Nimbus Cloud API endpoints covering model registry access, inference operations, analytics, and usage workflows.

# 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

<CardGroup cols={3}>
  <Card title="Cloud API Authentication" icon="key" href="/cloud-api/authentication">
    Set up API keys, license checks, and secure access patterns.
  </Card>

  <Card title="Cloud API Reference" icon="book-open" href="/cloud-api/introduction">
    Review API scope, base URL, and service architecture.
  </Card>

  <Card title="Julia SDK Quickstart" icon="code" href="/julia-sdk/quickstart">
    Run authenticated setup and load your first pre-trained model.
  </Card>
</CardGroup>

## 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 (supported for compatibility; prefer the `X-API-Key` header) |
| `paradigm` | string | Filter by BCI paradigm: `motor_imagery`, `p300`, `ssvep` (optional)              |
| `type`     | string | Filter by model type: `NimbusLDA`, `NimbusQDA`, `NimbusProbit` (optional)        |

<Note>
  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.
</Note>

**Request:**

```bash theme={null}
curl https://api.nimbusbci.com/v1/models/list \
  -H "X-API-Key: nbci_live_your_key"
```

**Response:**

```json theme={null}
{
  "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/qda/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:**

```bash theme={null}
# Get only motor imagery models
curl "https://api.nimbusbci.com/v1/models/list?paradigm=motor_imagery" \
  -H "X-API-Key: nbci_live_..."

# Get only NimbusLDA models
curl "https://api.nimbusbci.com/v1/models/list?type=NimbusLDA" \
  -H "X-API-Key: nbci_live_..."
```

### Using in Julia SDK

Use this endpoint through `list_available_models()` to discover model names that your license can access:

```julia theme={null}
using NimbusSDK

# Authenticate
NimbusSDK.install_core("nbci_live_your_key")

# Discover available models
models = list_available_models(model_type="NimbusLDA")

# Load a bundled or local model by name/path
model = load_model(NimbusLDA, "motor_imagery_4class_v1")
```

## Analytics & Logging

### POST /v1/analytics/log

Log inference events and usage metrics (optional, for analytics tracking).

**Authentication**: Required (API key)

**Request:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "logged": true,
  "event_id": "evt_1234567890",
  "quota": {
    "used": 1235,
    "remaining": 48765
  }
}
```

**cURL Example:**

```bash theme={null}
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}
  }'
```

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

## Health Check

### GET /api/health

Check API status and availability.

**Authentication**: Not required

**Request:**

```bash theme={null}
curl https://api.nimbusbci.com/api/health
```

**Response:**

```json theme={null}
{
  "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:**

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

## Error Responses

All endpoints return consistent error responses:

```json theme={null}
{
  "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

```julia theme={null}
using NimbusSDK

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

# 2. Load a bundled or local pre-trained model
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

```bash theme={null}
# Get all models your license allows
curl -X GET https://api.nimbusbci.com/v1/models/list \
  -H "X-API-Key: nbci_live_your_key" \
  | jq '.models[] | {name, type, paradigm}'
```

### Check Model Availability

```bash theme={null}
# Check if specific model is available
curl -X GET https://api.nimbusbci.com/v1/models/list \
  -H "X-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 |

<Note>
  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.
</Note>

## 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 Loading

`load_model()` loads bundled models or local `.jld2` files by name/path:

```julia theme={null}
# Load a bundled model by name
model = load_model(NimbusLDA, "motor_imagery_4class_v1")

# Load a local model file
model = load_model(NimbusLDA, "my_model.jld2")
```

Use `/v1/models/list` or `list_available_models()` to discover the model catalog before loading an available model.

## Endpoints FAQ

<AccordionGroup>
  <Accordion title="Does this API run BCI inference directly?" icon="help-circle">
    No. Inference runs locally in NimbusSDK.jl. The API is used for authentication, model registry access, installation flows, and optional analytics logging.
  </Accordion>

  <Accordion title="Which endpoint is required first?" icon="arrow-right">
    Start with authentication (`/v1/auth/validate` via SDK setup), then use `/v1/models/list` to discover available models for your license tier.
  </Accordion>

  <Accordion title="Why can model loading be fast?" icon="clock">
    `load_model(...)` reads bundled or local `.jld2` model files, so inference setup avoids network latency after SDK installation and authentication.
  </Accordion>
</AccordionGroup>

## Next Read

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/cloud-api/authentication">
    API key setup and management
  </Card>

  <Card title="Julia SDK" icon="code" href="/julia-sdk/api-reference">
    Complete SDK reference
  </Card>

  <Card title="Training Models" icon="graduation-cap" href="/examples/advanced-applications">
    Train custom models
  </Card>

  <Card title="Code Examples" icon="braces" href="/examples/basic-examples">
    Working examples
  </Card>
</CardGroup>

## Support

For API questions or model requests:

* **Email**: [hello@nimbusbci.com](mailto:hello@nimbusbci.com)
* **API Status**: [https://api.nimbusbci.com/api/health](https://api.nimbusbci.com/api/health)
* **Documentation**: [https://docs.nimbusbci.com](https://docs.nimbusbci.com)