# Norano API — overview

Norano turns floor plans into branded plans, photorealistic visualizations, and
3D tours. This API is built for **machines**: an autonomous agent can discover the
product, drive it, and recover from its own errors with no human in the loop.

## Point an agent here

- **OpenAPI 3.1** (the single source of truth): `/api/v1/openapi.json`
- **MCP server** (Streamable HTTP): `https://mcp.norano.ai/mcp`
- **Whole-corpus context blob**: `/llms-full.txt` (and the curated map at `/llms.txt`)
- **Interactive reference**: /docs/api/reference

Every docs page is available as raw Markdown — append `.md` to the URL, or send
`Accept: text/markdown`. Use the "Use with an agent" menu on any page to copy it
or open it in ChatGPT / Claude.

## Design principles

- **Machine-first** — stable codes, enums, and ids are the contract; prose is not.
- **Async-native** — expensive work returns a Job handle immediately; you poll or
  receive a webhook (see /docs/api/jobs).
- **Discoverable** — from only the base URL you can find the schema, the MCP server,
  and the auth scheme.
- **Idempotent** — every unsafe POST takes an `Idempotency-Key`; a retry never
  double-charges.
- **Every error is actionable** — each error carries `code`, `remediation`,
  `retryable`, and `docs_url` (see /docs/api/errors).
- **Safe for autonomous spenders** — cost is knowable before spending (`dry_run`),
  bounded (per-key caps), and rehearsable for free (test-mode keys).

## Start here

1. **Getting started** — base URL, keys, your first call: /docs/api/getting-started
2. **Authentication** — bearer keys, scopes, test vs live: /docs/api/authentication
3. **Async jobs** — the Job object and the agent loop: /docs/api/jobs
4. **Errors** — the actionable error catalog: /docs/api/errors
5. **Webhooks** — signed delivery + verification: /docs/api/webhooks
6. **Example agent flow** — end to end, REST and MCP: /docs/api/example