The streams.place API

Learn how to use the simple REST endpoints to fetch Drops to display on your own front-end, or post a new Drop from outside of Telegram.

Authentication

The GET endpoint requires no authentication and is available directly at the username/json route. If you have a private Stream, you’ll have to make your request to username/keyphrase/json

For POST requests, your keyphrase is required to be added to the header of your request as an authentication method.

GET route (username/json)

Returns an array of all the user’s public Drops. Each element of the array corresponds to one Drop and has the following properties

Property Contents Example
timestamp UNIX-style timestamp for when the Drop was created 1681908281288
id A unique ID for a Drop 1084819741874431
html HTML representation of the Drop’s contents, as rendered by the bot "<p>If you can see this message, it means that the POST endpoint works…</p>\n"
text The raw text that the bot recieved from Telegram "If you can see this message, it means that the POST endpoint works..."
last_edit UNIX-style timestamp for when the Drop was last edited 1680172933000
media An array of objects representing media associated with a drop [] (empty because no media)

There are three types of media objects that the media array might contain:

I. photo (.jpg, .png, etc)

{
    "type":"photo",
    "file_id":"AgACAgUAAxkBAAIOIWQsxhNo_nDpiRUc5YpOZ6WbvU34AAK9tTEbx3xhVaSsb-2Mkd7zAQADAgADeQADLwQ",
    "urlToFile":"https://fvinkehbbprjnyunhwkc.supabase.co/storage/v1/object/public/stream-images/beta/AgACAgUAAxkBAAIOIWQsxhNo_nDpiRUc5YpOZ6WbvU34AAK9tTEbx3xhVaSsb-2Mkd7zAQADAgADeQADLwQ.jpg"
}

II. animation (.gif)

{
    "type": "animation",
    "file_name": "mygif.gif",
    "file_id": "AgACAgUAAxkIOWHgngQsxhNo_nDpiRUc5Yp109yt284twnkwshVaSsb-2Mkd7sgsrgADeQADLwQ",
    "urlToFile": "https://fvinkehbbprjnyunhwkc.supabase.co/storage/v1/object/public/stream-images/beta/AgACAgUAAxkIOWHgngQsxhNo_nDpiRUc5Yp109yt284twnkwshVaSsb-2Mkd7sgsrgADeQADLwQ.gif"
}

III. audio

{
    "type": "audio",
    "file_name": "mysong.mp3",
    "performer": "Judah",
    "title": "My Song",
    "file_id": "AxkIOWHgngQsxhNo_nDpiRUc5Yp109yt284twnkwshVa-eQADLwsrht23tgs",
    "urlToFile": "https://fvinkehbbprjnyunhwkc.supabase.co/storage/v1/object/public/stream-images/beta/AxkIOWHgngQsxhNo_nDpiRUc5Yp109yt284twnkwshVa-eQADLwsrht23tgs.ogg"
}

Example payload

To bring it all together, here’s an example response from a Stream that contains three Drops, one of which has a photo attached.

[
	{
		 "timestamp": "1681908281288",
		 "id": "12094823072385", 
		 "html": "",
		 "text": "",
		 "last_edit": "",
		 "media": []
	},

	{
		 "timestamp": "1681908220941",
		 "id": "1209481904283", 
		 "html": "",
		 "text": "",
		 "last_edit": "",
		 "media": []
	},

	{
		 "timestamp": "1681901303130",
		 "id": "`10981309423487", 
		 "html": "",
		 "text": "",
		 "last_edit": "",
		 "media": [
			{
			    "type":"photo",
			    "file_id":"AgACAgUAAxkBAAIOIWQsxhNo_nDpiRUc5YpOZ6WbvU34AAK9tTEbx3xhVaSsb-2Mkd7zAQADAgADeQADLwQ",
			    "urlToFile":"https://fvinkehbbprjnyunhwkc.supabase.co/storage/v1/object/public/stream-images/beta/AgACAgUAAxkBAAIOIWQsxhNo_nDpiRUc5YpOZ6WbvU34AAK9tTEbx3xhVaSsb-2Mkd7zAQADAgADeQADLwQ.jpg"
			}
		]
	}
]

You can use the JSON to render your Stream to your own site, or create your own copy of your data.

POST route (username/api/post)

Note: This endpoint has been deprecated as we work on a new identity system for Streams v3.