# API reference

Source: https://docs.native.no/norn/reference

> **Preview.** The Norn API is not live yet. This page describes the planned interface; names and fields can change before access opens.

The base URL, authentication, request format, errors, limits and versions of the Norn API, and every endpoint on one list.

> **Planned values.** The address and the limits on this page are what we plan for the preview. The email that opens your access confirms them.

## Base URL

Base URL:

```text
https://api.native.no/v1
```

Every request goes over HTTPS. Plain HTTP is refused.

## Authentication

Send an access token as a bearer token in the `Authorization` header of every request. You get it with your client ID and secret and the Norn API as the `audience`, as [Authentication](https://docs.native.no/authentication) shows:

HTTP:

```http
POST /v1/ideas HTTP/1.1
Host: api.native.no
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
```

Your credentials belong to your team and reach every brand your team creates, and no others. A token lasts at most an hour: cache it and fetch a new one before it runs out.

## Requests and responses

- Request bodies are JSON, sent with `Content-Type: application/json`. Responses are JSON too.
- Field names are `snake_case`, and times are ISO 8601.
- Ids start with the kind of thing they name: `brand_`, `batch_`, `idea_`, `fb_`.
- Every object has an `object` field that names its kind. Lists come back as an object with `"object": "list"` and the items in `data`.
- New fields can appear at any time. Write code that ignores the ones it does not use.

## Errors

An error comes back with an HTTP status and a body that says what went wrong. When it is about one field, `param` names it:

409 Conflict:

```json
{
  "error": {
    "type": "invalid_request",
    "code": "brand_not_ready",
    "message": "Norn is still reading https://pipedream.example. Ask again when the brand’s status is ready.",
    "param": "brand"
  }
}
```

| Status | `type` | When |
| --- | --- | --- |
| `400` | `invalid_request` | A field is missing, or has the wrong type or value. |
| `401` | `authentication_error` | The access token is missing, expired or not for this API. |
| `403` | `permission_error` | Your credentials cannot reach that brand. |
| `404` | `not_found` | There is no brand, batch or idea with that id. |
| `409` | `invalid_request` | The brand is not ready yet. `code` is `brand_not_ready`. |
| `429` | `rate_limit` | Too many requests. Wait as many seconds as the `Retry-After` header says. |
| `500` | `server_error` | Something broke on our side. Try once more, then tell us. |

## Limits

- Your client ID has a request limit during the preview, agreed with you when access opens. Past it, the API answers `429`.
- Every call answers within seconds. The slow work, reading a website and thinking up ideas, runs in the background: you get a brand or a batch back at once and ask for it again until it is ready. Ask no more often than every 10 seconds.
- Up to 10 ideas per request, and up to 20 drafts per prediction.

## Versions

The version is part of the path: `/v1`. A change that would break your code gets a new version. The `model` field in each response names the model that answered, so you can tell when Norn itself has changed.

## All endpoints

| Endpoint | What it does | Status |
| --- | --- | --- |
| `POST /v1/brands` | [Create a brand](https://docs.native.no/norn/brands#create) | Preview |
| `GET /v1/brands/{brand_id}` | [Get a brand](https://docs.native.no/norn/brands#get) | Preview |
| `PATCH /v1/brands/{brand_id}` | [Update a brand](https://docs.native.no/norn/brands#update) | Preview |
| `POST /v1/ideas` | [Create ideas](https://docs.native.no/norn/ideas#create-ideas) | Preview |
| `GET /v1/ideas/{batch_id}` | [Get a batch](https://docs.native.no/norn/ideas#get-a-batch) | Preview |
| `POST /v1/feedback` | [Send feedback](https://docs.native.no/norn/feedback#send-feedback) | Preview |
| `POST /v1/predictions` | [Create predictions](https://docs.native.no/norn/predictions#create-predictions) | In development |