Fimfiction Developers

Stories

Stories are the bread and butter of Fimfiction. Interacting with them gives you the power to play with the most fundamental resource. A user's public stories are always available through the API, but accessing their unsubmitted stories requires read_stories permission. Modifying, creating and deleting stories requires write_stories permission

Relevant Scopes

  • read_stories
  • write_stories

Table of Contents

GET /stories

Browse all stories on the site. Note that this endpoint runs on the same search backend as the story browse page on the site, meaning it will not show unpublished stories. If you wish to read a user's unpublished stories use the /users/:id/stories endpoint.

Returns

[ story ]

Parameters

query Perform a search across stories. Use -relevance to sort results by how well they match.

Filters

ids
id,id,id...
 Filter out stories with ids not in the comma delimited array.
author
id
 Filter to show only stories from a certain author id.
num_words
minimum,maximum
 Filter out stories with less than minimum words and more than maximum
status
complete|incomplete|on-hiatus|cancelled
 Filter out stories where the status is not equal to status.
date_published
minimum,maximum
 Filter out stories published before minimum and after maximum. Dates should be ISO 8601.
tags
tag,tag,tag...
 Only show stories matching the tags provided. Tags should be in the format of c:id for characters and g:id for genres.
bookshelf
id
 Show stories from a specific bookshelf
unread
bool
 Filter out stories that are read. Only available in conjunction with a filter[bookshelf] that the authenticated user owns

Sort

Max sort fields: 1

date_published
 Date the story was published
hotness
 Current heat values for the story
date_modified
 Date the story was last updated
rating
 Rating of the story
num_words
 Number of words in the story
num_views
 Number of story views
num_comments
 Number of comments on the story
relevance
 When performing a search query this will order by the relevance of the results
num_likes
 Number of likes on the story
num_dislikes
 Number of dislikes on the story
date_added
 The date the story was added. Only available in conjunction with filter[bookshelf]

Pagination

  • Default Size: 20
  • Maximum Size: 100
  • Type: cursor
GET /stories/:id

Retrieves a story by :id. Unsubmitted stories will not be accessible without the user permitting read story access for your application.

Scopes

Parameters

:id required The numeric story id for the story to retrieve data of.
PATCH /stories/:id

Modifies the story with the :id provided.

Scopes

POST /stories

Creates a new story.

Scopes

DELETE /stories/:id

Deletes a story.

Scopes

GET /stories/:id/chapters

Gets a list of chapters in the story.

POST /stories/:id/chapters

Creates a new chapter.

Scopes