Lichess API: Adding Games To Streams

Hey guys! Ever been in a situation where you're trying to use the Lichess API, specifically the 'Add game IDs to stream' endpoint, and it just doesn't work? You're not alone! It seems like a common hiccup for folks trying to programmatically manage their game streams. Let's dive deep into this issue, figure out why it's happening, and get you back on track to seamlessly adding those game IDs. We'll break down the steps, what you might be doing wrong, and what the API *actually* expects. Getting this right means you can build some really cool tools and automations around your Lichess experience, so it's definitely worth understanding. We're going to dissect the problem, look at the expected behavior versus what you're seeing, and offer some solid advice. So grab your favorite beverage, and let's get this sorted!

Understanding the 'Add Game IDs to Stream' API

So, what's the deal with this specific API endpoint, https://lichess.org/api/stream/games/{streamId}/add? Essentially, it's designed to let you dynamically add more games to an existing stream you've created. Think of it like this: you start a broadcast of certain games, and then you decide, 'Hey, I want to add *this* new game to my broadcast too!' This API is your tool to make that happen. The whole idea is to create a live feed of game data that you can then consume, maybe for analysis, for displaying on a website, or for some other custom project. When you use the API, you provide the ID of the stream you want to modify and then, in the request body, you list the IDs of the games you want to add. The API should then acknowledge the addition and, ideally, the updated stream should start including the new games. This is super powerful for real-time monitoring of specific matchups or players. However, as some of you have discovered, it's not always as straightforward as it seems. The error message {"error":"Not found"} is the common roadblock, and it usually points to a misunderstanding of how the stream or the game IDs are being processed by the API. We'll get into the nitty-gritty of why this might be popping up for you.

Decoding the Error: "Not Found"

The dreaded "Not found" error when trying to add a game ID to a stream can be really frustrating, especially when you've followed the documentation to the letter. Let's unpack what this *could* mean in the context of Lichess streams. Often, when an API returns "Not found," it's not necessarily because the *stream* itself doesn't exist, but rather that the *resource* you're trying to add (the game) isn't being recognized in the way the API expects for that specific stream, or the stream ID itself might be subtly incorrect or expired. One common pitfall with Lichess streams is how they are identified and managed. When you first create a stream using an endpoint like /api/stream/games/{streamId}, you're essentially creating a temporary channel. The {streamId} you use here is the identifier for *that specific stream session*. If this stream session has ended, timed out, or was never properly initialized in the first place, trying to add games to it later will result in a "Not found" error because the target stream simply isn't active or doesn't exist anymore from the API's perspective. Another possibility is related to the game IDs themselves. While you might have valid game IDs, perhaps they are in a format the API doesn't expect for this operation, or the games themselves might have already concluded in a way that they can't be 'added' to a live stream anymore. The API might be designed to only accept games that are currently ongoing or haven't started. It's a bit like trying to add a past event to a live news ticker – it might not fit the system's logic. We'll explore some specific scenarios and potential solutions to help you navigate this.

Step-by-Step: Reproducing and Diagnosing the Issue

Let's walk through the exact steps that led to the "Not found" error and see where things might be going wrong. The user provided a clear reproduction case, which is super helpful! First, they create a stream:

curl -N -X POST "https://lichess.org/api/stream/games/testStreamApi" \
  -H "Content-Type: text/plain" \
  -d "6lKDFpQ1"

This part seems to work fine. The API responds with details of the game that was successfully added to this newly created stream, identified as testStreamApi. The output includes game details like "id":"OmjV5yNq", and information about players, variant, and status. This indicates that the stream testStreamApi was successfully created and the initial game was added. Now, the critical part is step two, where the user attempts to add another game:

curl -X POST "https://lichess.org/api/stream/games/testStreamApi/add" \
  -H "Content-Type: text/plain" \
  -d "SmJyJJQl"

This is where the problem occurs, returning {"error":"Not found"}. The expected behavior was that the game with ID SmJyJJQl would be added to the testStreamApi stream. The fact that it fails with "Not found" suggests that either the stream testStreamApi is no longer considered valid by the time the second request is made, or the way the game ID is being sent is problematic for the `/add` endpoint. It's possible that streams created via this initial POST request are ephemeral and have a limited lifespan or might require a specific keep-alive mechanism. If the stream session times out or is closed implicitly after the first game is processed or after a short period of inactivity, subsequent attempts to add to it would fail. Also, let's consider the data format. The documentation for /add implies sending game IDs. Are we sure SmJyJJQl is a valid game ID, and is it being sent correctly as plain text? The first POST request used a game ID (6lKDFpQ1) and it worked. The second attempt uses a different string (SmJyJJQl) as the game ID. If this second string is *not* a valid game ID, that could also lead to an error, though perhaps not always "Not found." However, given the user's description and the error, the most likely culprit is the state of the stream itself.

Potential Causes and Solutions

Let's brainstorm some reasons why the "Not found" error might be popping up and how we can fix it. Based on the reproduction steps, the primary suspect is the lifecycle of the stream itself. Lichess streams, especially those created via the API for specific purposes like this, might be designed to be temporary. After you create a stream and perhaps add an initial game, the stream session might have a limited duration. If you wait too long before attempting to add more games, the stream might have been automatically closed or expired by the server. The API endpoint /api/stream/games/{streamId}/add is meant to append to an *existing, active* stream. If the stream identified by testStreamApi is no longer active when you make the second call, you'll get that "Not found" error.

Solution 1: Keep the Stream Alive

One way to combat this is to ensure the stream remains active. How can you do that? If the API supports it, you might need to periodically send a small, harmless request to the stream or the stream's management endpoint to signal that it's still in use. Alternatively, some streaming APIs require a continuous connection or regular