About scriptbin's APIs and export/download file formats
scriptbin started in response to Pastebin closing down accounts with scripts for being in violation of its Acceptable Use policy. scriptbin was able to offer a simple migration because Pastebin had a way to export all scripts in an account, and there was a matching function to import scripts from Pastebin. Similarly, since very early on there has been a function on scriptbin to export your scripts.
Being able to take all of your scripts and download them as a backup or move everything elsewhere is very important. scriptbin is not a "social media platform" focusing on "engagement" or on making money. If it was, there would be significant reason to want to stop anyone leaving for another place. But scriptbin is primarily a script host (which sometimes also has functions like search) and is always going to provide ways to get back everything you put in.
Right now, scriptbin has these APIs and file formats.
Download/Export file format
When using the 📚 Download all scripts button on your writer's profile, all scripts are zipped up and the zipped file contains these files. This section describes the structure of each file.
A writer should not need to consult this documentation to understand the information contained in this file (but can check on a detail if necessary). This format is optimized to be easy to read and to make sense independent of any tools, not to import. It is nevertheless regular and possible to parse.
Another format, that is optimized for tool use, is also available by using the 🤖 Structured export button instead. This format is described later. This is significantly more convenient to use to import from, but may also not be the version that writers have downloaded. You may wish to implement support for both formats.
Script files (in 📚 Download all scripts)
Each script file is named CLEANEDNAME_numid.txt, where numid is a numerical ID and CLEANEDNAME is a version of the title that has been cleaned of many characters (and possibly also trimmed in length) to be safe for inclusion in a file name.
The script file uses Windows line endings (CRLF/\r\n) and the UTF-8 text encoding.
The script file contains, in order:
The title, including inline tags, on the first line. If an audience tag (performer/listener) is included, it appears first, in the form [audience] , like: [FM4F] Let's make you feel good
A line with #### to separate the title from the start of the metadata, followed by an empty line.
(From this point on, metadata is listed. Metadata may be added over time and may be inserted between two previous pieces of metadata. To future-proof any tool reading this file, until an empty line is encountered, you should skip over any line that does not match any of these and allow for them to appear in arbitrary order.)
A line with Publicly listed or Private. "Private" refers to "not publicly listed".
A line with Format: FORMAT, where FORMAT is Reddit-compatible Markdown if the script has the text mode "Reddit-compatible Markdown", otherwise Plain text.
If the script is password protected: A line with Password protected. The password itself is not included (or even possible to print out).
A line with Created: 2035-01-01 23:59:59 UTC. The timestamp is the point in time when the script was first created/imported in the UTC timezone.
If the script has been updated after this point: A line with Updated: 2035-01-01 23:59:59 UTC. The timestamp is the point in time when the script was most recently updated after creation.
If a script summary has been entered: A line with Summary: SUMMARY where SUMMARY is the summary.
If a script link has been entered: A line with Link: LINK where LINK is the link.
If an audience tag is included: A line with Audience: AUDIENCE; Performer: PF; Listener: LS.
Here, AUDIENCE is the full audience tag, without enclosing brackets, for example FFMMM4M.
PF and LS are both the "tallied" description of the respective performer/listener part. Everything after the first ; is redundant information so the tallied description does not need to be parsed.
The "tallied" description format
The tallied description is:
If it is just one instance of one gender, the name of that gender.
Otherwise, it is the number of instances for each gender, formatted as: COUNT× GENDER and separated with ; . Note that the count is followed by ×, the Unicode U+00D7 multiplication sign character, not the letter X. If multiple genders are involved, the groups are not guaranteed to be listed in any particular order.
For example:
NB4F → Audience: NB4F; Performer: Non binary; Listener: Female
MFAAAAA4A → Audience: MFAAAAA4A; Performer: 1× Male; 1× Female; 5× Any; Listeners: Any
FFF4M → Audience: FFF4M; Performer: 3× Female; Listeners: Male
The gender names used are:
for NB → Non binary
for A → Any
for F → Female
for M → Male
for TF → Trans female
for TM → Trans male
and for anything else, Unspecified
If a script is sorted because scripts have been reordered: A line with Sort order: ORDER where ORDER is an integer. The script that appears at the top of the script list has the lowest number.
If a disclaimer has been entered: A line with Disclaimer: DISCLAIMER where DISCLAIMER is the disclaimer.
If a script has been marked as sensitive or not sensitive (and not "same as per-writer"): A line with Marked as sensitive or Not marked as sensitive.
If a script has been marked as hidden: A line with Hidden: this script was hidden.
If a script has been unpublished by scriptbin: A line with Unpublished: this script was unpublished by scriptbin, followed with a line with Unpublished note: NOTE if a note exists.
An empty line to mark the end of the metadata and the start of the script contents.
If a script has script text entered, the entire script text follows, as entered in the script textbox. (Including the --8<-- divider ending the instructions.)
Script files (in 🤖 Structured export)
Each script file is named CLEANEDNAME_numid.txt, where numid is a numerical ID and CLEANEDNAME is a version of the title that has been cleaned of many characters (and possibly also trimmed in length) to be safe for inclusion in a file name.
The script file uses Windows line endings (CRLF/\r\n) and the UTF-8 text encoding.
The script file contains, in order:
The title, including inline tags, on the first line. If an audience tag (performer/listener) is included, it appears first, in the form [audience] , like: [FM4F] Let's make you feel good
A line with #### to separate the title from the rest of the file, followed by an empty line.
If a script has script text entered, the entire script text follows, as entered in the script textbox. (Including the --8<-- divider ending the instructions.)
Each script file also gets a corresponding metadata sidecar file with a .json file extension instead of .txt.
The metadata file uses the UTF-8 text encoding.
The metadata file contains a JSON object with the following keys and values:
"format" with the value "reddit-markdown" if the script has the text mode "Reddit-compatible Markdown", otherwise "text".
"publicListed" with the value true if the script is publicly listed, otherwise false.
"passwordProtected" with the value true if the script is password protected, otherwise false.
"created" with the point in time when the script was first created/imported as a string value with the format "2035-01-01 23:59:59". The time is given in the UTC timezone.
"updated" with the point in time when the script was most recently updated formatted the same as "created". May be the same value as for "created".
"shortDescription" with the summary as the value, or null if no summary has been entered.
"otherLink" with the script link as the value, or null if no script link has been entered.
"audienceShort" with the audience tag (without enclosing brackets) as the value, or null if no audience tag has been entered.
"sortOrder" with an integer representing the sort order if scripts have been reordered, or null if scripts have not been reordered. The script that appears at the top of the script list has the lowest number.
"disclaimer" with the disclaimer as the value, or null if no disclaimer has been entered.
"markedAsSensitive" with true if the script has been marked as sensitive, false if the script has been marked as not sensitive or null if it has been marked as same as per-writer.
"hidden" with true if the script has been marked as hidden, otherwise false.
"unpublishedCentrally" with true if a script has been unpublished by scriptbin, otherwise false.
"unpublishedCentrallyNote" with the note given describing why a script has been unpublished by scriptbin, if such a note exists, otherwise null.
(The following keys and values are exclusive for the structured export format.)
"textStats" with a JSON object with these keys if a script has text entered (otherwise null or missing entirely):
"wordCount" with the number of words, and
"characterCount" with the number of characters/letters in the script text,
both according to scriptbin's algorithm for counting them.
Script import format
scriptbin has a function to import files from Pastebin's export function. This format fits Pastebin's purpose but is significantly lossy, so encouraging more use of this would be encouraging a worse experience.
If you are interested in defining a format that scriptbin could use to import files from your site, please contact me.
API
An API could come in handy for use cases like:
- Automatically backing up all scripts
- Exporting scripts to another script hosting site
If you are interested in these use cases, or in obtaining the same export as what is produced when using 🤖 Structured export, please contact me.