REST API & OpenAPI
The Phase 1 API is served by FastAPI. Interactive docs are available from a running instance; this page summarizes versioned surfaces and how to authenticate.
http://localhost:8080), use interactive
Swagger at GET /docs and fresh JSON at GET /docs/json.
Static site below: bundled snapshot at assets/openapi.json
(run uv run --directory platform/backend python -m nims.tools.export_contracts to refresh).
Full OpenAPI specification
Embedded Swagger UI loads the repo snapshot next to this page. Use Try it out against
your API origin (e.g. add http://localhost:8080 under servers if needed).
Authentication
Browser sessions — after sign-in, the API uses an HTTP-only cookie (nims_session).
Sign-in methods are configured per organization: local email/password (optional) and
at most one of LDAP / Active Directory, Microsoft Entra ID, or
OpenID Connect, via GET/PATCH /v1/admin/identity and AUTH_* environment
variables. The login page calls GET /v1/auth/providers for the effective catalog. See
design-auth-user-management.md.
Automation & scripting use Bearer tokens (seeded or issued API tokens). Send:
Authorization: Bearer <token>Example:
curl -sS -H "Authorization: Bearer $TOKEN" http://localhost:8080/v1/meAPI surfaces
| Surface | Path | Notes |
|---|---|---|
| OpenAPI JSON | GET /docs/json |
Full schema for codegen & contract tests |
| Swagger UI | GET /docs |
Try requests against a live server |
| GraphQL (read) | POST /graphql |
GraphiQL at GET /graphql when enabled |
| REST v1 | /v1/… |
Inventory, bulk, resource views, search |
Deployment & environment
For production Docker / Kubernetes examples, every environment variable (auth, LLM,
connectors, PG* for RDS, etc.), and a deploy checklist, see
Deployment & environment on this site, or
docs/deployment.md
and
docs/environment-variables.md on GitHub.
Endpoints used by the web UI
These are stable touchpoints for the React console (see also Platform & web UI).
| Capability | Method & path |
|---|---|
| Global search | GET /v1/search?q=&limit= |
| Current user / prefs | GET /v1/me, PATCH /v1/me |
| Sign-in provider catalog | GET /v1/auth/providers |
| Identity (admin) | GET /v1/admin/identity, PATCH /v1/admin/identity |
| UI: page registry / slots / nav / federation | GET /v1/ui/page-registry, …/placements, …/navigation, …/federation |
| Plugins, connectors, jobs | GET /v1/plugins, /v1/connectors (admin writes), /v1/jobs, POST /v1/jobs/{key}/run |
| LLM (admin; org default model & endpoint) | GET /v1/admin/llm, PATCH /v1/admin/llm, POST /v1/admin/llm/test, GET /v1/admin/llm/metrics |
| Intent Center copilot | POST /v1/copilot/chat, POST /v1/copilot/chat/stream, POST /v1/copilot/suggest_next_steps, GET/POST /v1/copilot/skills, and related routes under /v1/copilot/… (see GET /docs) |
| MCP (optional; off by default) | /mcp on the same origin when NIMS_MCP_ENABLED=1; Authorization: Bearer <api token> |
| Object view (fields + graph) | GET /v1/resource-view/{resourceType}/{id} |
| Relationship graph JSON | GET /v1/resource-graph/{resourceType}/{id} |
| Bulk export | GET /v1/bulk/{resourceType}/export |
| Bulk import | POST /v1/bulk/{resourceType}/import/csv, …/import/json |
Supported bulk resourceType values include core types such as Location, Rack,
Device, Vrf, plus catalog types registered in the bulk router. Refer to
platform/backend/nims/routers/v1/bulk.py in the repo for the authoritative list.
Errors & versioning
Errors follow HTTP semantics with JSON bodies from FastAPI. API paths are versioned under /v1; bump
major versions when breaking contracts. Use correlationId headers where returned for tracing across
jobs and webhooks.
Future work: auth hardening and GraphQL policy items (public allowlist, 401 parity) are listed on Wishlist & future work.