# Player

Your brand on the hosted watch page and embed at cardinal.stream: name,
logo, color, theme, an optional giving button, and the Cardinal badge.

Base URL: `https://api.cardinalstreaming.com`. Authenticate with `Authorization: Bearer <your API key>`.

## Read your player brand

`GET /v1/player`

Your brand on the hosted player (cardinal.stream), as stored and as viewers see it.

### Examples

cURL:

```bash
curl "https://api.cardinalstreaming.com/v1/player" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"
```

Python:

```python
import os

import requests

response = requests.get(
    "https://api.cardinalstreaming.com/v1/player",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

JavaScript:

```js
const response = await fetch('https://api.cardinalstreaming.com/v1/player', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);
```

TypeScript:

```ts
const response: Response = await fetch('https://api.cardinalstreaming.com/v1/player', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);
```

PHP:

```php
<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.cardinalstreaming.com/v1/player', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;
```

Ruby:

```ruby
require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/player")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body
```

Go:

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.cardinalstreaming.com/v1/player", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(data))
}
```

Java:

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/player"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

C#:

```csharp
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.cardinalstreaming.com/v1/player");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
```

### Response 200

The settings and the resolved brand.

| Name | Type | Required | Description |
|---|---|---|---|
| `settings` | object | yes | Every field is optional; null or absent is unset (inherits). |
| `settings.display_name` | string or null | no |  |
| `settings.logo_url` | string or null | no | An https:// image address. |
| `settings.accent_color` | string or null | no |  |
| `settings.theme` | string or null | no |  One of `"dark"`, `"light"`. |
| `settings.giving_url` | string or null | no | Your giving page, https://. Unset: no giving button. |
| `settings.giving_label` | string or null | no |  |
| `settings.giving_on` | boolean or null | no | false hides the giving button even where a page is set. |
| `settings.show_badge` | boolean or null | no | false removes "Streaming by Cardinal". |
| `brand` | object | yes |  |
| `brand.name` | string | yes |  |
| `brand.logo_url` | string or null | yes |  |
| `brand.accent_color` | string | yes |  |
| `brand.theme` | string | yes |  One of `"dark"`, `"light"`. |
| `brand.show_badge` | boolean | yes |  |
| `brand.giving` | object or null | yes |  |
| `brand.giving.url` | string | yes |  |
| `brand.giving.label` | string | yes |  |

## Set your player brand

`PUT /v1/player`

Replaces your brand on the hosted player. A field left out or null is
unset. In the console only an owner may change it.

### Request body

| Name | Type | Required | Description |
|---|---|---|---|
| `display_name` | string or null | no |  |
| `logo_url` | string or null | no | An https:// image address. |
| `accent_color` | string or null | no |  |
| `theme` | string or null | no |  One of `"dark"`, `"light"`. |
| `giving_url` | string or null | no | Your giving page, https://. Unset: no giving button. |
| `giving_label` | string or null | no |  |
| `giving_on` | boolean or null | no | false hides the giving button even where a page is set. |
| `show_badge` | boolean or null | no | false removes "Streaming by Cardinal". |

### Examples

cURL:

```bash
curl -X PUT "https://api.cardinalstreaming.com/v1/player" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"
```

Python:

```python
import os

import requests

response = requests.put(
    "https://api.cardinalstreaming.com/v1/player",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

JavaScript:

```js
const response = await fetch('https://api.cardinalstreaming.com/v1/player', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);
```

TypeScript:

```ts
const response: Response = await fetch('https://api.cardinalstreaming.com/v1/player', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);
```

PHP:

```php
<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('PUT', 'https://api.cardinalstreaming.com/v1/player', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;
```

Ruby:

```ruby
require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/player")
request = Net::HTTP::Put.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body
```

Go:

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("PUT", "https://api.cardinalstreaming.com/v1/player", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(data))
}
```

Java:

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/player"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("PUT", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

C#:

```csharp
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("PUT"), "https://api.cardinalstreaming.com/v1/player");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
```

### Response 200

The settings and the resolved brand.

| Name | Type | Required | Description |
|---|---|---|---|
| `settings` | object | yes | Every field is optional; null or absent is unset (inherits). |
| `settings.display_name` | string or null | no |  |
| `settings.logo_url` | string or null | no | An https:// image address. |
| `settings.accent_color` | string or null | no |  |
| `settings.theme` | string or null | no |  One of `"dark"`, `"light"`. |
| `settings.giving_url` | string or null | no | Your giving page, https://. Unset: no giving button. |
| `settings.giving_label` | string or null | no |  |
| `settings.giving_on` | boolean or null | no | false hides the giving button even where a page is set. |
| `settings.show_badge` | boolean or null | no | false removes "Streaming by Cardinal". |
| `brand` | object | yes |  |
| `brand.name` | string | yes |  |
| `brand.logo_url` | string or null | yes |  |
| `brand.accent_color` | string | yes |  |
| `brand.theme` | string | yes |  One of `"dark"`, `"light"`. |
| `brand.show_badge` | boolean | yes |  |
| `brand.giving` | object or null | yes |  |
| `brand.giving.url` | string | yes |  |
| `brand.giving.label` | string | yes |  |

### Errors

| Status | Code | Meaning |
|---|---|---|
| 400 | `invalid_settings` | A field is malformed; the detail says which. |
| 403 | `owner_only` | In the console, only an owner may change what viewers see. |

## Read one customer's player brand

`GET /v1/customers/{customer_ref}/player`

A partner's per-customer brand, which overrides the default field by field.

### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `customer_ref` | string | yes | Your identifier for the customer. |

### Examples

cURL:

```bash
curl "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"
```

Python:

```python
import os

import requests

response = requests.get(
    "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

JavaScript:

```js
const response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/player', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);
```

TypeScript:

```ts
const response: Response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/player', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);
```

PHP:

```php
<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.cardinalstreaming.com/v1/customers/grace-chapel/player', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;
```

Ruby:

```ruby
require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/customers/grace-chapel/player")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body
```

Go:

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(data))
}
```

Java:

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/customers/grace-chapel/player"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

C#:

```csharp
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
```

### Response 200

The customer's settings and the brand its viewers see.

| Name | Type | Required | Description |
|---|---|---|---|
| `settings` | object | yes | Every field is optional; null or absent is unset (inherits). |
| `settings.display_name` | string or null | no |  |
| `settings.logo_url` | string or null | no | An https:// image address. |
| `settings.accent_color` | string or null | no |  |
| `settings.theme` | string or null | no |  One of `"dark"`, `"light"`. |
| `settings.giving_url` | string or null | no | Your giving page, https://. Unset: no giving button. |
| `settings.giving_label` | string or null | no |  |
| `settings.giving_on` | boolean or null | no | false hides the giving button even where a page is set. |
| `settings.show_badge` | boolean or null | no | false removes "Streaming by Cardinal". |
| `brand` | object | yes |  |
| `brand.name` | string | yes |  |
| `brand.logo_url` | string or null | yes |  |
| `brand.accent_color` | string | yes |  |
| `brand.theme` | string | yes |  One of `"dark"`, `"light"`. |
| `brand.show_badge` | boolean | yes |  |
| `brand.giving` | object or null | yes |  |
| `brand.giving.url` | string | yes |  |
| `brand.giving.label` | string | yes |  |

### Errors

| Status | Code | Meaning |
|---|---|---|
| 404 | `not_found` | No such customer in your organization. |

## Set one customer's player brand

`PUT /v1/customers/{customer_ref}/player`

### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `customer_ref` | string | yes | Your identifier for the customer. |

### Request body

| Name | Type | Required | Description |
|---|---|---|---|
| `display_name` | string or null | no |  |
| `logo_url` | string or null | no | An https:// image address. |
| `accent_color` | string or null | no |  |
| `theme` | string or null | no |  One of `"dark"`, `"light"`. |
| `giving_url` | string or null | no | Your giving page, https://. Unset: no giving button. |
| `giving_label` | string or null | no |  |
| `giving_on` | boolean or null | no | false hides the giving button even where a page is set. |
| `show_badge` | boolean or null | no | false removes "Streaming by Cardinal". |

### Examples

cURL:

```bash
curl -X PUT "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player" \
  -H "Authorization: Bearer $CARDINAL_API_KEY"
```

Python:

```python
import os

import requests

response = requests.put(
    "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player",
    headers={
        "Authorization": f"Bearer {os.environ['CARDINAL_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

JavaScript:

```js
const response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/player', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data = await response.json();
console.log(response.status, data);
```

TypeScript:

```ts
const response: Response = await fetch('https://api.cardinalstreaming.com/v1/customers/grace-chapel/player', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CARDINAL_API_KEY}`,
  },
});
const data: unknown = await response.json();
console.log(response.status, data);
```

PHP:

```php
<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client();
$response = $client->request('PUT', 'https://api.cardinalstreaming.com/v1/customers/grace-chapel/player', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CARDINAL_API_KEY'),
    ],
    'http_errors' => false,
]);
echo $response->getStatusCode(), ' ', $response->getBody(), PHP_EOL;
```

Ruby:

```ruby
require 'json'
require 'net/http'

uri = URI("https://api.cardinalstreaming.com/v1/customers/grace-chapel/player")
request = Net::HTTP::Put.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('CARDINAL_API_KEY')}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.body
```

Go:

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("PUT", "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CARDINAL_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(data))
}
```

Java:

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cardinalstreaming.com/v1/customers/grace-chapel/player"))
            .header("Authorization", "Bearer " + System.getenv("CARDINAL_API_KEY"))
            .method("PUT", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

C#:

```csharp
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("PUT"), "https://api.cardinalstreaming.com/v1/customers/grace-chapel/player");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("CARDINAL_API_KEY"));

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
```

### Response 200

The customer's settings and the brand its viewers see.

| Name | Type | Required | Description |
|---|---|---|---|
| `settings` | object | yes | Every field is optional; null or absent is unset (inherits). |
| `settings.display_name` | string or null | no |  |
| `settings.logo_url` | string or null | no | An https:// image address. |
| `settings.accent_color` | string or null | no |  |
| `settings.theme` | string or null | no |  One of `"dark"`, `"light"`. |
| `settings.giving_url` | string or null | no | Your giving page, https://. Unset: no giving button. |
| `settings.giving_label` | string or null | no |  |
| `settings.giving_on` | boolean or null | no | false hides the giving button even where a page is set. |
| `settings.show_badge` | boolean or null | no | false removes "Streaming by Cardinal". |
| `brand` | object | yes |  |
| `brand.name` | string | yes |  |
| `brand.logo_url` | string or null | yes |  |
| `brand.accent_color` | string | yes |  |
| `brand.theme` | string | yes |  One of `"dark"`, `"light"`. |
| `brand.show_badge` | boolean | yes |  |
| `brand.giving` | object or null | yes |  |
| `brand.giving.url` | string | yes |  |
| `brand.giving.label` | string | yes |  |

### Errors

| Status | Code | Meaning |
|---|---|---|
| 400 | `invalid_settings` | A field is malformed; the detail says which. |
| 404 | `not_found` | No such customer in your organization. |