Send requests to the Owncast API

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

Event	Endpoint	Scope
System chat message	/api/integrations/chat/system	CAN_SEND_SYSTEM_MESSAGES
Standard chat message	/api/integrations/chat/send	CAN_SEND_MESSAGES
Chat action	/api/integrations/chat/action	CAN_SEND_SYSTEM_MESSAGES
Remove chat message	/api/integrations/chat/messagevisibility	HAS_ADMIN_ACCESS
Get chat history	/api/integrations/chat	HAS_ADMIN_ACCESS
Get connected clients	/api/integrations/clients	HAS_ADMIN_ACCESS
Set stream title	/api/integrations/streamtitle	HAS_ADMIN_ACCESS
system message to client	/api/integrations/chat/system/client/{clientId}	CAN_SEND_SYSTEM_MESSAGES
Get server status	/api/integrations/status	HAS_ADMIN_ACCESS
Get a chat user's details	/api/integrations/moderation/chat/user/{userId}	HAS_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

Send an authenticated POST with your access token in the Authorization header and a JSON body. For example, to send a system chat message:

const res = await fetch("https://your.owncast.server/api/integrations/chat/system", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer " + YOUR_ACCESS_TOKEN,
  },
  body: JSON.stringify({ body: "this is a system chat message" }),
});

const result = await res.json();
// { "success": true, "message": "sent" }

Test sending chat messages

Change the following curl command to point to your server URL and use your auth token with "system message" access. 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!"}' \
  https://your.owncast.server/api/integrations/chat/system

A successful request returns 200 with a JSON body:

{ "success": true, "message": "sent" }

Scopes

Each access token is granted one or more scopes that control what it can do. The endpoints above list the scope each one requires.

Scope	Grants
CAN_SEND_MESSAGES	Send standard chat messages as the token's own user.
CAN_SEND_SYSTEM_MESSAGES	Send chat messages as the system, and send chat actions.
HAS_ADMIN_ACCESS	Administrative actions: read chat history, list connected clients, set the stream title, change message visibility, get the server status, and look up a chat user.

Responses and errors

Status	Meaning
200	The request succeeded. For the mutation (POST) endpoints the JSON body is the success: true envelope with a short message. The GET endpoints return the domain object instead: the server status, an array of chat messages, an array of connected clients, or a user's details.
400	The request body was malformed. The JSON body has success: false and a message.
401	The access token is missing, invalid, or lacks the scope the endpoint requires. The body is plain text.
500	The server hit an error handling the request.

Owncast does not return a separate 403 for an insufficient scope. A token without the required scope is rejected with 401, the same as a missing or invalid token.