# Norano

> Norano is an agent-first API that turns floor plans into photorealistic
> visualizations and walkable 360° tours. This file is an LLM-oriented index;
> follow the links to load the full machine-readable contract.

## What Norano does (product context)
- Turns uploaded floor plans (DXF/PDF) into photorealistic visualizations and
  walkable 360° tours, each produced by a long-running async `Job`.
- NOTE: this is the product vision, NOT the list of endpoints available today.
  The OpenAPI document below is the authoritative, current API surface.

## What the v1 API exposes today
- Discover the resource vocabulary: `GET /api/v1`.
- Track any long operation through ONE unified async `Job`: `GET /api/v1/jobs`
  (list) and `GET /api/v1/jobs/{id}` (poll → fetch `result.assets[]`).
- Job CREATE endpoints (projects, plans, visualizations, tours, assets) are
  rolling out incrementally — always treat the OpenAPI document as the source
  of truth for which endpoints currently exist.

## Auth
- Bearer API key: `Authorization: Bearer norano_sk_live_…` (or `norano_sk_test_…`).
- Keys are scoped (least privilege); `403 insufficient_scope` if a scope is missing.

## The async Job loop
- Long operations return a `Job`. Poll `GET /api/v1/jobs/{id}` (optionally
  `Prefer: wait=30` to long-poll) until `status` is terminal, then read `result.assets[]`.

## Errors
- Every error is `{ error: { type, code, message, remediation, retryable, docs_url, request_id } }`.
- Branch on `type` + `code` (stable), never on `message`.

## Machine-readable resources
- [OpenAPI 3.1 (JSON)](https://norano.ai/api/v1/openapi.json) — the single source of truth.
- [OpenAPI 3.1 (Markdown)](https://norano.ai/api/v1/openapi.md)
- [llms-full.txt](https://norano.ai/llms-full.txt) — the whole-corpus blob for one-shot loading.
- [Capability manifest](https://norano.ai/.well-known/mcp.json)
- [OAuth protected-resource metadata](https://norano.ai/.well-known/oauth-protected-resource)

## MCP
- MCP server (Streamable HTTP): https://mcp.norano.ai/mcp
- Discover it via the [capability manifest](https://norano.ai/.well-known/mcp.json).