# API Documentation

The Nx AI Cloud exposes two REST APIs: one for managing AI models and catalogues, and one for managing edge devices and sites. Both are documented via OpenAPI (Swagger UI).

| API             | OpenAPI UI                                                                           | Description                                    |
| --------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------- |
| **Compute API** | [api.sclbl.nxvms.com/cpt/openapi.html](https://api.sclbl.nxvms.com/cpt/openapi.html) | Model upload, conversion, catalogue management |
| **Device API**  | [api.sclbl.nxvms.com/dev/openapi.html](https://api.sclbl.nxvms.com/dev/openapi.html) | Site, server, and edge device management       |

The raw OpenAPI JSON specifications are available at `/cpt/openapi.json` and `/dev/openapi.json` on the same host.

<figure><img src="/files/qyES0GrdFFWEIxj2AHIF" alt="Swagger UI showing the Compute API endpoint list organized by tag"><figcaption><p>The Swagger UI at api.sclbl.nxvms.com/cpt/openapi.html lists all available Compute API endpoints</p></figcaption></figure>

***

## Authentication

All API endpoints require a Bearer token obtained via the Nx OAuth2 flow.

### Getting a token

The token exchange happens automatically when you log in through the Nx AI Cloud admin interface. For programmatic access, follow the OAuth2 authorization code flow against the Nx Cloud identity provider:

```bash
# Exchange an authorization code for tokens
curl -X POST https://cloud.networkoptix.com/cdb/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=<your-code>&redirect_uri=<your-redirect-uri>&client_id=<your-client-id>"
```

The response includes an `access_token` (JWT). Use it as the Bearer token in all subsequent API calls.

> **Note:** The `code` parameter is obtained via the OAuth2 authorization code redirect flow, which requires a browser. For interactive testing, use the Swagger UI linked in the Authentication section above. Headless programmatic authentication is not yet covered here.

### Using the token

Pass the token in the `Authorization` header on every request:

```bash
export TOKEN="eyJ..."

# List all models available to your account
curl https://api.sclbl.nxvms.com/cpt/functions \
  -H "Authorization: Bearer $TOKEN"

# List all sites
curl https://api.sclbl.nxvms.com/dev/systems \
  -H "Authorization: Bearer $TOKEN"
```

***

## Multi-tenant context (acting as an organization)

Users with access to multiple organizations can make API calls on behalf of a specific organization by passing two additional headers:

| Header          | Values                                    | Description               |
| --------------- | ----------------------------------------- | ------------------------- |
| `X-Act-As-Kind` | `user`, `organization`, `channel_partner` | The entity type to act as |
| `X-Act-As-ID`   | UUID of the organization                  | The organization UUID     |

```bash
# List models as a specific organization
curl https://api.sclbl.nxvms.com/cpt/functions \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Act-As-Kind: organization" \
  -H "X-Act-As-ID: <org-uuid>"
```

Omitting these headers causes the API to act as the authenticated user (personal context).

***

## Pagination

List endpoints return paginated results. The total record count is exposed in a response header:

| Header                 | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| `X-Pagination-Records` | Total number of records matching the query (regardless of page size) |

Pagination parameters vary by endpoint; see the OpenAPI spec for `limit` and `offset` query parameters.

```bash
# Fetch the second page of models (20 per page)
curl "https://api.sclbl.nxvms.com/cpt/functions?limit=20&offset=20" \
  -H "Authorization: Bearer $TOKEN" \
  -v 2>&1 | grep "X-Pagination-Records"
```

***

## Common operations

### Upload a model

```bash
curl -X POST https://api.sclbl.nxvms.com/cpt/functions \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@my-model.onnx" \
  -F "name=My Object Detector" \
  -F "documentation=Detects objects in video streams."
```

### Get a specific model

```bash
curl https://api.sclbl.nxvms.com/cpt/function/<model-uuid> \
  -H "Authorization: Bearer $TOKEN"
```

### List devices for a site

```bash
curl https://api.sclbl.nxvms.com/dev/system/<site-nxid>/devices \
  -H "Authorization: Bearer $TOKEN"
```

### Assign a model pipeline to a device

```bash
curl -X POST https://api.sclbl.nxvms.com/dev/system/<site-nxid>/device/<device-nxid>/functions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"FunctionID": "<model-uuid>"}'
```

***

{% hint style="info" %}
For a full list of endpoints, request/response schemas, and query parameters, use the interactive OpenAPI documentation linked at the top of this page.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nx.docs.scailable.net/nx-ai-manager-v6.1.2/miscellaneous/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.