# Getting started

The base address, how to make a key, and a first call with the Authorization header.

## Base address

Every route is served from one host. Answers are JSON. Send a body as `application/json`.

```
https://api.rivier.ai
```

## Make a key

Sign in to the app, open Developers and make a key for the project. Choose the scopes it holds; the secret is shown once, so store it where your server keeps secrets. A key belongs to one project and cannot read another.

## Make a first call

Send the key in the `Authorization` header as a bearer credential. This call searches the web and needs the scope `search:read`.

Request:

```
curl -sS https://api.rivier.ai/search \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "opening hours of the national library" }'
```

Response:

```
{
  "highlights": [
    {
      "text": "…",
      "score": 0.82,
      "source": { "url": "https://example.org/visit" }
    }
  ]
}
```

A missing or wrong key answers 401. A key without the scope answers 403 and names the scope it needs.

## Pin a version

The API has a dated contract. Send `Rivier-Version` to pin it; every answer names the version it was served under. Within one version only additions happen. A breaking change ships as a new date and the earlier one keeps working for at least twelve months. A version the API does not know answers 400 with the list it supports.

Header:

```
Rivier-Version: 2026-11-01
```

## Try it in a test project

A key is either live or test. A test key works in a test project: calls to outside services are recorded and not made, so nothing leaves the test project. `GET /sandbox` says which kind a key is, `POST /sandbox/seed` fills the test project with sample records and `GET /sandbox/deliveries` lists what would have been sent.

## Where to go next

The full list of operations is the OpenAPI 3.1 document at `https://api.rivier.ai/v1/openapi.json`. It needs no key. The reference pages here are made from the same list.