# All providers

`GET /v1/providers` lists every provider that serves models, with where it is based and its
policies.

## Request

Send it with an API key. It takes no field. The [Models](/docs/models) guide says how a model is
named and served.

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/providers"

request = urllib.request.Request(
    ADDRESS,
    headers={"Authorization": "Bearer " + API_KEY},
)
with urllib.request.urlopen(request) as response:
    providers = json.load(response)["data"]

for provider in providers:
    print(provider["slug"], provider["name"], provider["headquarters"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/providers";

const response = await fetch(ADDRESS, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { data } = await response.json();

for (const provider of data) {
  console.log(provider.slug, provider.name, provider.headquarters);
}
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const address = "https://opendunes.com/v1/providers"

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	req, err := http.NewRequest("GET", address, nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var body struct {
		Data []struct {
			Slug         string  `json:"slug"`
			Name         string  `json:"name"`
			Headquarters *string `json:"headquarters"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		panic(err)
	}
	for _, provider := range body.Data {
		hq := ""
		if provider.Headquarters != nil {
			hq = *provider.Headquarters
		}
		fmt.Println(provider.Slug, provider.Name, hq)
	}
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/providers"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY"
```

## Response

`200 OK`.

| Field | Holds |
|---|---|
| `data` | every provider |
| `name` | in each: the provider's name |
| `slug` | in each: its short name, the one `provider.only`, `provider.order` and `provider.ignore` take |
| `privacy_policy_url` | in each: the address of its privacy policy, or `null` |
| `terms_of_service_url` | in each: the address of its terms of service, or `null` |
| `status_page_url` | in each: the address of its status page, or `null` |
| `headquarters` | in each: the country it is based in, as a two-letter code, or `null` |
| `datacenters` | in each: the countries its datacenters are in, as two-letter codes, or `null` |

## What it cost

Free. Reading the catalogue is never charged.

## Errors

`error.code` carries the status, and `error.message` says why.

| Status | When |
|---|---|
| 401 | the key is missing, wrong, disabled or expired |
| 403 | the key answers only from the addresses set on it, and this request came from another |
| 503 | the providers could not be read just now; `Retry-After` says how many seconds to wait |
