APIs & Access Tokens

We currently support the following actions you can make via requests from your code.

EventEndpointScope
System chat message/api/integrations/chat/systemCAN_SEND_SYSTEM_MESSAGES
User chat message/api/integrations/chat/userCAN_SEND_MESSAGES
Chat action/api/integrations/chat/actionCAN_SEND_SYSTEM_MESSAGES
Remove chat message/api/integrations/chat/messagevisibilityHAS_ADMIN_ACCESS
Get chat history/api/integrations/chatHAS_ADMIN_ACCESS
Get connected clients/api/integrations/clientsHAS_ADMIN_ACCESS
Set stream title/api/integrations/streamtitleHAS_ADMIN_ACCESS

Visit the API documentation for each endpoint to learn more about what values are expected or will be returned.

Your Owncast server will only accept actions from requests with a valid Access Token. Follow the below steps to create an access token.

  1. visit /admin/access-tokens on your owncast server.
  2. Click Create Access Token.
  3. Select the scope of permissions you want to give this token.
  4. Save this access token.

Your code

  1. Create a new request in your code.
  2. This request should send headers with Authorization: Bearer and your access token.

Example request:

{
    headers: {
        Content-Type: "application/json",
        Authorization: "Bearer " + YOUR_ACCESS_TOKEN
    },
    { body: "this is a system chat message" }
}

Test sending chat messages

Change the following curl command to point to your server URL and use your auth token. It will send a system message to your chat.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer YOURAUTHTOKEN" -d '{"body": "I am a system message!"}' http://YOUR.OWNCAST.SERVER/api/integrations/chat/system