# Predictions

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

> **In development.** Not part of the first preview of the Norn API. This page describes the interface as planned.

In development: send the drafts you already have, and Norn ranks them before they go out, with how likely each is to beat the brand’s usual post.

> **Not in the first preview.** Predictions are still being built. This page shows the interface as we plan it, so you can tell us whether it fits what you are building. Write to [hei@native.no](mailto:hei@native.no).

Ideas answer "what should we post?". Predictions answer the question that comes after: "of the posts we have, which one will land?". Send Norn drafts from your team, your own models or your customers, and it ranks them before anything is published.

## What the numbers mean

`score` is Norn’s estimate of the chance a draft beats the brand’s usual post on engagement, from 0 to 1. A score of 0.74 means Norn expects the draft to do better than the brand’s typical post about three times in four.

`confidence` says how much evidence stands behind the score, from 0 to 1. It starts low for a new brand and rises as outcomes come back through [feedback](https://docs.native.no/norn/feedback). A high score with low confidence is a guess. Treat it like one.

## Acting on a prediction

Both numbers are meant to be used in code. A common pattern: publish on your own when both are high, and ask a person when they are not.

TypeScript:

```ts
const [top] = result.data

if (top.score >= 0.7 && top.confidence >= 0.5) {
  await schedule(top.id)
} else {
  await askForReview(top.id)
}
```

## Create predictions

`POST /v1/predictions` (in development)

Body:

- `brand` (string, required): The id of a brand whose `status` is `ready`.
- `candidates` (object[], required): The drafts to rank, from 2 to 20.
  - `id` (string, required): Your own id for the draft. It comes back with its prediction.
  - `text` (string, required): The draft’s words.
  - `format` (string, optional; one of: `image`, `carousel`, `video`, `text`): The format it will go out in.

cURL:

```bash
curl -X POST https://api.native.no/v1/predictions \
  -H "Authorization: Bearer $NATIVE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "brand": "brand_7Hk2pQ",
  "candidates": [
    {
      "id": "draft-a",
      "text": "Frozen pipes do not care that it is Sunday. We do. Same-day fix, no drama.",
      "format": "video"
    },
    {
      "id": "draft-b",
      "text": "Winter is here. Book your annual plumbing inspection today.",
      "format": "image"
    }
  ]
}'
```

TypeScript:

```ts
const res = await fetch('https://api.native.no/v1/predictions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIVE_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    brand: "brand_7Hk2pQ",
    candidates: [
      {
        id: "draft-a",
        text: "Frozen pipes do not care that it is Sunday. We do. Same-day fix, no drama.",
        format: "video"
      },
      {
        id: "draft-b",
        text: "Winter is here. Book your annual plumbing inspection today.",
        format: "image"
      }
    ]
  }),
})
if (!res.ok) throw new Error(`Norn answered ${res.status}: ${await res.text()}`)
const result = await res.json()
```

Python:

```python
import os

import requests

res = requests.post(
    "https://api.native.no/v1/predictions",
    headers={"Authorization": f"Bearer {os.environ['NATIVE_ACCESS_TOKEN']}"},
    json={
      "brand": "brand_7Hk2pQ",
      "candidates": [
        {
          "id": "draft-a",
          "text": "Frozen pipes do not care that it is Sunday. We do. Same-day fix, no drama.",
          "format": "video"
        },
        {
          "id": "draft-b",
          "text": "Winter is here. Book your annual plumbing inspection today.",
          "format": "image"
        }
      ]
    },
    timeout=30,
)
res.raise_for_status()
result = res.json()
```

Response:

```json
{
  "object": "list",
  "model": "norn-preview",
  "brand": "brand_7Hk2pQ",
  "data": [
    {
      "object": "prediction",
      "id": "draft-a",
      "rank": 1,
      "score": 0.74,
      "confidence": 0.41
    },
    {
      "object": "prediction",
      "id": "draft-b",
      "rank": 2,
      "score": 0.22,
      "confidence": 0.41
    }
  ]
}
```

## What it will not do at first

- It reads words only. To rank a picture or a video, describe it in `text`.
- It ranks drafts within one brand. It does not compare brands with each other.
- A score is for ranking and for thresholds. It is not a forecast of reach, clicks or sales.