API version 2

Why a version 2

In version 1, lists come back under different names (data, titles, chapters, penNames, series and others), and a single record is sometimes wrapped and sometimes not. A script has to know each one. Version 1 also ignores a setting it does not recognize: a list asked for with a misspelled filter, such as book= instead of book_id=, quietly returns every item in the account instead of one book's.

What version 2 does

• Every list answers { data: [...], pagination: {...} } and every single record answers { data: {...} }. Anything else the answer used to include sits under meta, unchanged.
• pagination has limit, offset, hasMore, returned and nextCursor. For the few lists that are read in one go (pen names, series, characters, source files), hasMore is false when the list is complete, and null if it reached 1,000 items and there may be more.
• A list refuses settings it does not read, and says which ones it does read, instead of ignoring them.
• With the tools, an argument a tool does not have is refused instead of dropped. Tools for records not yet in version 2 return their usual answer whole under data.
• Error answers keep the shape they already have: { error: { code, message, details } }.

How to turn it on

Direct API calls

Use /api/v2/ in place of /api/v1/, with the same API key, for example GET https://storytelleros.com/api/v2/chapters?book_id=.... Endpoints that are not in version 2 yet answer NOT_IN_V2; keep using /api/v1/ for those. Version 2 starts with titles, chapters, scenes, series, pen names, characters, formats and their files, uploads, and the other main writing, email and catalog lists.

Claude and other assistants

Add ?api_version=2 to the connector address (https://storytelleros.com/api/mcp?api_version=2), or send the header STOS-API-Version: 2 if your setup lets you add headers. If your assistant signs in to StorytellerOS rather than using an API key and does not accept the changed address, use the header or an API key instead.

The plan from here

• Version 1 stays as it is. Your existing scripts and saved assistant setups keep working.
• More endpoints join version 2 over time. Anything not there yet keeps working on version 1.
• We will not make version 2 the default without announcing it at least 60 days ahead, here and by email, with the date.