Building Custom Playlist Ordering with the Playlist API

Most playlist APIs store order as a plain integer, item 1, item 2, item 3, and reorder by rewriting that number. AIOZ Stream's Playlist API doesn't work that way. Its reorder endpoint asks for the item's neighbors instead of a position, a real design choice with a real reason behind it, not an arbitrary API quirk.

TL;DR:

• The Playlist API has nine operations: create, list, retrieve, update, add item, reorder item, remove item, delete thumbnail, and delete playlist, each with its own endpoint.
• Reordering uses a dedicated PUT endpoint that takes a required current_id plus next_id and/or previous_id, specifying the item's new neighbors rather than an absolute position number.
• That neighbor-based design avoids a real problem plain integer positions create: moving one item in the middle of a long list otherwise means rewriting every position number after it.
• Moving an item to the very top or bottom still works with just one neighbor reference, set next_id to the current first item to move something to the top, or previous_id to the current last item to move it to the bottom.
• The API returns playlist_url and iframe fields on every playlist object, but AIOZ's documentation doesn't explain what embedding a playlist actually looks like or whether playback auto-advances the way a single video's player does.

The Playlist API surface

Nine endpoints cover the whole lifecycle: POST /playlists/create to create one, POST /playlists to list a user's playlists, GET /playlists/:playlist_id to retrieve one, PATCH /playlists/:playlist_id to update its metadata, POST /playlists/:playlist_id/items to add a video, PUT /playlists/:playlist_id/items to reorder one, DELETE /playlists/:playlist_id/items/:item_id to remove one, plus separate delete endpoints for a playlist's thumbnail and for the playlist itself. A playlist object carries id, user_id, name, thumbnail_url, timestamps, an item_count, the video_items themselves, total duration and size, and the playlist_url/iframe fields covered further down. Adding a video is a single POST with just a video_id in the body, appended to the end by default, nothing more complicated than that. The list endpoint is worth calling out specifically since it's a POST rather than a GET, unusual for a pure read operation, which suggests it accepts filter or pagination parameters in a request body rather than query-string arguments, worth checking directly if a project needs to page through a large number of a user's playlists rather than assuming GET-style query parameters will work.

Reordering: neighbors, not a position number

The reorder endpoint's request body is current_id, next_id, and previous_id, and AIOZ's own documentation is direct about the rule: "the current_id is always required. Use next_id and previous_id to specify the new position." Both neighbor fields are optional individually, meaning a single reference is enough to place an item, you don't need to supply both the thing before it and the thing after it every time. The edge cases are handled the same way rather than needing special-case logic: "to move a video to the top of the playlist, set next_id to the ID of the first video in the playlist. To move a video to the bottom, set previous_id to the ID of the last video in the playlist." There's no null-position or index-zero concept to reason about, moving something to either end is still just a neighbor reference, the current first or last item.

A concrete case: a five-item playlist, A through E in that order, and a request to move item D between A and B. The request body is straightforward once you know which two items D should sit between:

PUT /playlists/:playlist_id/items
{
  "current_id": "D",
  "previous_id": "A",
  "next_id": "B"
}

The result is A, D, B, C, E, one write describing D's new neighbors, nothing else in the list touched or even referenced in the request. Moving D again later, say to the very end, only needs previous_id set to whatever the last item happens to be at that moment, the client doesn't need to track or recompute anything about the rest of the list's internal state to make that call correctly, only the identity of one neighboring item.

Why this avoids a real problem

Plain integer positions have a well-known failure mode in any reorderable list: moving one item in the middle means rewriting the position value of every item after it, one write becomes many. That's a real, documented reason serious drag-and-drop implementations avoid raw integer indices. A tldraw's-creator writeup on the exact problem puts it plainly: "making a change to one item's order might mean making a change to all items in the stack. This strategy could lead to excessive writes to a database, or larger packets being sent to ensure consistency between users in a multiplayer session." The common fix in that space is fractional indexing, assigning a decimal value between two existing positions so only the moved item needs a new value, Figma's own multiplayer editor uses exactly this technique, and Trello uses a related gap-buffering scheme with large position increments to leave room for insertions. AIOZ's neighbor-reference design solves the identical underlying problem through a different mechanism, a linked-list-style "insert relative to this item" operation instead of a numeric value between two others, but the goal is the same: moving one playlist item shouldn't require rewriting the rest of the list. Put a number on what integer positions would actually cost: moving item 3 to the end of a 200-item playlist under a naive position-integer scheme means decrementing the position of every item from 4 through 200, 197 writes, or one very large batch update, for what a viewer experiences as a single drag-and-drop action. AIOZ's neighbor-reference design turns that same move into exactly one write, regardless of how long the playlist is or where in it the move happens, which matters more as playlists get longer and reordering gets more frequent, exactly the conditions where the naive approach's cost scales worst.

What isn't documented: embedding a playlist

Every playlist object returned by the API includes playlist_url and iframe fields, which strongly implies a playlist can be embedded and played the way a single video can, but AIOZ's documentation doesn't actually explain what either field contains or how playback behaves once embedded. Whether a viewer gets an auto-advancing player that moves through the playlist's items in order, whether the embedded player exposes the same theming options covered in the white-label player article, or whether it behaves more like a single-video embed pointed at whatever the current item happens to be, isn't stated either way. That's worth testing directly against a real playlist before building UI around an assumption, the fields exist and are populated, but their actual playback behavior is undocumented. A practical way to de-risk that gap before committing to it in a real integration: create a test playlist with two or three short videos, embed it using the returned iframe value exactly as given, and watch what actually happens at the point where the first item ends, rather than assuming auto-advance, a visible playlist sidebar, or any specific behavior from the field names alone. Field names are a reasonable hint at intent, they're not a specification, and the gap between the two is exactly where an integration built on assumption breaks in production later.

Frequently Asked Questions

How do I move a playlist item to a specific position?
Call the reorder endpoint with the item's current_id plus either next_id, previous_id, or both, specifying what the item's new neighbors should be rather than an absolute position number.

Do I need to supply both next_id and previous_id when reordering?
No. A single neighbor reference is enough; supplying just one still places the item correctly.

How do I move an item to the very top or bottom of a playlist?
Set next_id to the current first item's ID to move something to the top, or previous_id to the current last item's ID to move it to the bottom.

Why doesn't AIOZ use a simple position number for playlist ordering?
A plain integer position requires rewriting every subsequent item's position value on every move. Neighbor-based reordering, like fractional indexing elsewhere in the industry, avoids that cascade by only touching the item that actually moved.

Can I embed a whole playlist the way I'd embed a single video?
The API returns playlist_url and iframe fields suggesting yes, but AIOZ's documentation doesn't describe the actual embedded playback behavior, worth testing directly before assuming auto-advance or theming parity with single-video embeds.

Is there a maximum number of items a playlist can hold?
Not documented. AIOZ's Playlist API reference doesn't state a maximum item count.

Related Reading

• Getting Started with the AIOZ Stream Node.js SDK: the same playlist endpoints called through the Node.js client instead of raw REST
• Getting Started with the AIOZ Stream Go SDK Client: confirms the Go client's reorder request struct matches this exact neighbor-reference design
• How to White-Label the AIOZ Stream Video Player via API: the player theming this article's embedding question builds on
• How to Embed the AIOZ Stream Player on Your Website: the single-video embed pattern a playlist embed is compared against
• AIOZ Stream Developer Guide: the full API surface the Playlist API is part of

References

• AIOZ Stream Playlist API documentation: the endpoints, fields, and reorder mechanics quoted above
• Steve Ruiz: Reordering with Fractional Indices: the integer-position renumbering problem quoted above
• Fractional Indexing: Implementing Drag-and-Drop Ordering: the Figma/Trello real-world examples cited above