# Getting started

## Base URL

All requests go to the versioned gateway under your Norano origin:

```
https://norano.ai/api/v1
```

The `/v1` major never breaks within the major version. Deprecations are announced
with `Deprecation` + `Sunset` headers and a window.

## Get an API key

API keys are decoupled from the browser/Clerk session. A key looks like
`norano_sk_live_…` (live) or `norano_sk_test_…` (test mode). The plaintext is shown
**once** at creation and never retrievable — store it securely. See
/docs/api/authentication for scopes and test vs live.

## Your first call

Send the key as a bearer token:

```http
GET /api/v1/projects
Authorization: Bearer norano_sk_live_…
```

```json
{ "object": "list", "data": [], "has_more": false, "url": "/api/v1/projects" }
```

Single objects are returned bare with an `object` discriminator; lists are wrapped
with cursor pagination (`limit`, `starting_after`/`ending_before`, `has_more`,
`next_cursor`). Every response echoes a `Request-Id` header.

## The machine-discovery surface

An agent with only the base URL can bootstrap from these (all public, no key):

- `GET /api/v1/openapi.json` — the OpenAPI 3.1 document (single source of truth).
  Send `Accept: text/markdown` (or use `/api/v1/openapi.md`) for the Markdown form.
- `GET /llms.txt` — a curated, LLM-oriented map of the API.
- `GET /llms-full.txt` — the whole-corpus blob (curated map + error catalog + enums
  + the full OpenAPI JSON) for a single-shot context load.
- `GET /.well-known/oauth-protected-resource` and the MCP manifest — advertise the
  MCP server URL and the auth scheme.

## Next

- **Authentication**: /docs/api/authentication
- **Async jobs** (most generate calls are async): /docs/api/jobs
- **Example agent flow** (end to end): /docs/api/example