SpaceBattles APIforums.spacebattles.com ↗
Search and read SpaceBattles fiction stories via API. Access story metadata, chapter content, author profiles, and tag filtering across the Creative Library.
What is the SpaceBattles API?
The SpaceBattles Creative Library API exposes 4 endpoints covering story search, full story metadata, chapter text, and author profiles from forums.spacebattles.com. The search_stories endpoint returns paginated story summaries with structured tags across categories like Setting, Character, Genre, Warning, and Content, plus word counts and engagement stats. Use it to browse or build a corpus of fan fiction and original fiction hosted on one of the largest speculative fiction forum communities.
curl -X GET 'https://api.parse.bot/scraper/ad103a01-c6f4-41c9-a997-214ab3a8190d/search_stories?page=1&tags=worm' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace forums-spacebattles-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: SpaceBattles Fiction SDK — bounded, re-runnable; every call capped."""
from parse_apis.forums_spacebattles_com_api import SpaceBattles, NotFound
client = SpaceBattles()
# Search for stories tagged "worm", capped at 3 results.
for story in client.story_summaries.search(tags="worm", limit=3):
print(story.title, story.author, story.stats.get("words", ""))
# Drill down: get full metadata for the first result.
hit = client.story_summaries.search(tags="worm", limit=1).first()
try:
full = client.stories.get(thread_id=hit.thread_id)
print(full.title, full.author_name, full.stats.status)
for ch in full.chapters[:3]:
print(" ", ch.title, ch.date)
except NotFound as e:
print("story gone:", e)
# Read chapter content for that story.
for chapter in full.content(limit=2):
print(chapter.title, len(chapter.content), "chars")
# Get the author profile via the sub-resource.
author = full.writer.get()
print(author.username, "joined:", author.joined, "messages:", author.stats.get("messages"))
print("exercised: story_summaries.search / stories.get / story.content / story.writer.get")
Browse fiction stories in the SpaceBattles Creative Library with optional tag-based filtering. Results are ordered by most recent activity. Each story summary includes title, author, tags with categories (Setting, Character, Genre, Warning, Content), word count, and engagement stats.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| tags | string | Tag name to filter stories by (e.g. 'worm', 'original', 'rwby'). Matches the site's tag vocabulary. Omitting returns all stories. |
{
"type": "object",
"fields": {
"page": "current page number",
"stories": "array of story summary objects with thread_id, title, author, tags, stats",
"total_pages": "total number of pages available for the current filter"
},
"sample": {
"data": {
"page": 1,
"stories": [
{
"url": "https://forums.spacebattles.com/threads/hedging-bets-worm-cradle.1269248/",
"tags": [
{
"name": "cradle",
"category": "Setting"
},
{
"name": "worm",
"category": "Setting"
}
],
"stats": {
"likes": "214",
"views": "13K",
"words": "1.6k",
"replies": "95",
"watchers": "105",
"threadmarks": "10"
},
"title": "Hedging Bets - Worm/Cradle",
"author": "HyperspaceTrancer",
"snippet": "",
"thread_id": "1269248",
"created_at": "2025-11-12T09:33:40-0500"
}
],
"total_pages": 307
},
"status": "success"
}
}About the SpaceBattles API
Story Search and Metadata
The search_stories endpoint returns paginated lists of stories from the SpaceBattles Creative Library, ordered by most recent activity. Each result includes a thread_id, title, author, a tags array with category labels (Setting, Character, Genre, Warning, Content), and a stats object. You can filter by tag using the tags parameter — values like worm, original, or rwby match the site's tag vocabulary. The total_pages field tells you how many pages exist for your current filter.
The get_story endpoint takes a thread_id and returns the full metadata record for a single story: title, author username, author_id, author_url, categorized tags, a stats block with created date, status, watcher count, and threadmarks count, and an ordered chapters array where each item has a title, URL, and date.
Chapter Content and Author Profiles
To retrieve actual prose, use get_story_content with a thread_id. It returns a chapters array where each object includes post_id, title, author, date, and the full text of the chapter. Stories with many chapters paginate across multiple pages; the total_pages field tells you the extent. The optional page parameter lets you walk through them sequentially.
The get_author endpoint accepts a member_id (available from get_story's author_id field) and returns the author's username, joined datetime, a stats block with message count, likes count, and awards count, and a blurb field that carries the member's tagline or pronouns if set.
The SpaceBattles API is a managed, monitored endpoint for forums.spacebattles.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when forums.spacebattles.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official forums.spacebattles.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a tag-filtered index of SpaceBattles fiction by genre, fandom, or content warning using
search_stories. - Track story activity and watcher growth over time by polling
get_storystats for a set of thread IDs. - Download full chapter text via
get_story_contentto train or evaluate a text model on fan fiction. - Map author output by joining
get_storyauthor_id withget_authormessage and likes counts. - Aggregate word count and threadmarks data across a fandom tag to identify the most substantial stories in a category.
- Surface recently active stories in a specific setting tag (e.g. 'worm', 'rwby') for a recommendation feed.
- Archive a complete story with ordered chapters and metadata by combining
get_storyandget_story_contentcalls.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does SpaceBattles have an official developer API?+
What does the `tags` parameter in `search_stories` accept?+
Does `get_story_content` return every chapter in one response?+
total_pages field and an optional page parameter so you can retrieve subsequent pages. Each page returns a chapters array with post_id, title, author, date, and full prose text.Are forum posts outside the Creative Library — like roleplay threads or debate threads — accessible through this API?+
Is there a way to filter stories by multiple tags at once?+
search_stories endpoint accepts a single tags value per request. Multi-tag filtering is not currently supported. You can fork this API on Parse and revise the search endpoint to add support for multiple tag parameters.