Player API

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

This page is generated from the OpenAPI specification; the same text is inMarkdown for tools and AI assistants.

Read your player brand

GET/v1/player

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

Response 200

The settings and the resolved brand.

Fields

Name	Type	Description
settingsrequired	object	Every field is optional; null or absent is unset (inherits).
settings.display_name	string or null
settings.logo_url	string or null	An https:// image address.
settings.accent_color	string or null
settings.theme	string or null	One of `"dark"`, `"light"`.
settings.giving_url	string or null	Your giving page, https://. Unset: no giving button.
settings.giving_label	string or null
settings.giving_on	boolean or null	false hides the giving button even where a page is set.
settings.show_badge	boolean or null	false removes “Streaming by Cardinal”.
brandrequired	object
brand.namerequired	string
brand.logo_urlrequired	string or null
brand.accent_colorrequired	string
brand.themerequired	string	One of `"dark"`, `"light"`.
brand.show_badgerequired	boolean
brand.givingrequired	object or null
brand.giving.urlrequired	string
brand.giving.labelrequired	string

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

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)

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);

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
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;

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

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))
}

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());
    }
}

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()}");

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

Response 200

The settings and the resolved brand.

Fields

Name	Type	Description
settingsrequired	object	Every field is optional; null or absent is unset (inherits).
settings.display_name	string or null
settings.logo_url	string or null	An https:// image address.
settings.accent_color	string or null
settings.theme	string or null	One of `"dark"`, `"light"`.
settings.giving_url	string or null	Your giving page, https://. Unset: no giving button.
settings.giving_label	string or null
settings.giving_on	boolean or null	false hides the giving button even where a page is set.
settings.show_badge	boolean or null	false removes “Streaming by Cardinal”.
brandrequired	object
brand.namerequired	string
brand.logo_urlrequired	string or null
brand.accent_colorrequired	string
brand.themerequired	string	One of `"dark"`, `"light"`.
brand.show_badgerequired	boolean
brand.givingrequired	object or null
brand.giving.urlrequired	string
brand.giving.labelrequired	string

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.

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

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)

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);

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
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;

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

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))
}

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());
    }
}

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()}");

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	Description
customer_refrequired	string	Your identifier for the customer.

Response 200

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

Fields

Name	Type	Description
settingsrequired	object	Every field is optional; null or absent is unset (inherits).
settings.display_name	string or null
settings.logo_url	string or null	An https:// image address.
settings.accent_color	string or null
settings.theme	string or null	One of `"dark"`, `"light"`.
settings.giving_url	string or null	Your giving page, https://. Unset: no giving button.
settings.giving_label	string or null
settings.giving_on	boolean or null	false hides the giving button even where a page is set.
settings.show_badge	boolean or null	false removes “Streaming by Cardinal”.
brandrequired	object
brand.namerequired	string
brand.logo_urlrequired	string or null
brand.accent_colorrequired	string
brand.themerequired	string	One of `"dark"`, `"light"`.
brand.show_badgerequired	boolean
brand.givingrequired	object or null
brand.giving.urlrequired	string
brand.giving.labelrequired	string

Errors

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

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

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)

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);

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
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;

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

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))
}

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());
    }
}

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()}");

Set one customer's player brand

PUT/v1/customers/{customer_ref}/player

Path parameters

Name	Type	Description
customer_refrequired	string	Your identifier for the customer.

Request body

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

Response 200

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

Fields

Name	Type	Description
settingsrequired	object	Every field is optional; null or absent is unset (inherits).
settings.display_name	string or null
settings.logo_url	string or null	An https:// image address.
settings.accent_color	string or null
settings.theme	string or null	One of `"dark"`, `"light"`.
settings.giving_url	string or null	Your giving page, https://. Unset: no giving button.
settings.giving_label	string or null
settings.giving_on	boolean or null	false hides the giving button even where a page is set.
settings.show_badge	boolean or null	false removes “Streaming by Cardinal”.
brandrequired	object
brand.namerequired	string
brand.logo_urlrequired	string or null
brand.accent_colorrequired	string
brand.themerequired	string	One of `"dark"`, `"light"`.
brand.show_badgerequired	boolean
brand.givingrequired	object or null
brand.giving.urlrequired	string
brand.giving.labelrequired	string

Errors

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

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

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)

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);

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
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;

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

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))
}

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());
    }
}

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()}");