API Reference

Storybeats

Endpoint: /v1/storybeats

This endpoint provides access to the Storybeats of a particular Storyform. The Storybeats are structured based on the selected Throughline, Scope (Transits, Progressions, Events), and Perspective.

Endpoint

URL: api.subtxt.app/v1/storybeats

Method: POST

Request Body

The request should include a JSON object with the following parameters:

{
  "user_id": "required string",
  "structure_id": "required string",
  "perspective_id": "required string",
  "throughline": "required string",
  "scope": "required integer",
  "transit_id": "optional string",
  "progression_id": "optional string",
  "event_id": "optional string"
}

Parameters

user_id (required, string): The hashed unique identifier for the user making the request (e.g., "user_a1B2c3D4e5F6").
structure_id (required, string): The hashed unique identifier of the Storyform structure (e.g., "structure_g7H8i9J0k1L2").
throughline (required, string): Indicates which context the Storybeats should apply to. Valid values:
- "Objective Story"
- "Main Character"
- "Obstacle Character"
- "Relationship Story"
perspective_id (required, string): The hashed unique identifier of the Perspective being used (e.g., "perspective_m3N4o5P6q7R8").
scope (required, integer): Specifies the level of detail for the Storybeats. Valid values:
- 1 for Transits
- 2 for Progressions
- 3 for Events
transit_id (optional, string): Specifies a particular Transit to retrieve. This is a hashed ID (e.g., "transit_zB7fiC9vznpGbcVjnxajj3Zc").
progression_id (optional, string): Specifies a particular Progression within a Transit (e.g., "progression_xY5wV4uT3sR2").
event_id (optional, string): Specifies a particular event within a Progression (e.g., "event_cD3eF4gH5iJ6").

Response

The API will return a structured JSON object based on the parameters provided, detailing the requested Storybeats.

Example Request

Fetch events for the second progression within the first transit for the Obstacle Character, using a specific perspective

{
  "user_id": "user_a1B2c3D4e5F6",
  "structure_id": "structure_g7H8i9J0k1L2",
  "throughline": "Obstacle Character",
  "perspective_id": "perspective_m3N4o5P6q7R8",
  "scope": 3,
  "transit_id": "transit_zB7fiC9vznpGbcVjnxajj3Zc",
  "progression_id": "progression_xY5wV4uT3sR2"
}

Sample Response

{
  "storybeats": [
    {
      "appreciation": "Obstacle Character Event 1",
      "method": "Understanding",
      "illustration": "The mentor reveals crucial information",
      "summary": "The Obstacle Character imparts wisdom that challenges the Main Character's beliefs.",
      "storytelling": "In this event, the mentor shares a pivotal story from their past, causing the Main Character to question their own path.",
      "context": "Obstacle Character"
    }
  ]
}

Explanation

IDs Are Hashed: All identifiers (user_id, structure_id, perspective_id, transit_id, progression_id, event_id) are hashed strings for security purposes.
Nested Data Handling: If you provide specific transit_id, progression_id, or event_id, the API will return data scoped to those IDs. If omitted, it will return all relevant data based on the scope parameter.
Perspective Integration: Including the perspective_id allows the API to tailor the Storybeats according to a specific narrative viewpoint or analysis framework.

Notes

Throughline Values: Ensure that the throughline parameter matches one of the valid string options exactly.
Scope Levels:
- 1 (Transits): Returns high-level story movements.
- 2 (Progressions): Returns detailed sequences within Transits.
- 3 (Events): Returns specific occurrences within Progressions.
Security: Since IDs are hashed, they should be treated as opaque identifiers without any assumption about their internal structure.

Additional Examples

Fetch all transits for the Objective Story with a specific perspective

{
  "user_id": "user_a1B2c3D4e5F6",
  "structure_id": "structure_g7H8i9J0k1L2",
  "perspective_id": "perspective_m3N4o5P6q7R8",
  "throughline": "Objective Story",
  "scope": 1
}

Fetch progressions for the Main Character within a specific transit

{
  "user_id": "user_a1B2c3D4e5F6",
  "structure_id": "structure_g7H8i9J0k1L2",
  "perspective_id": "perspective_m3N4o5P6q7R8",
  "throughline": "Main Character",
  "scope": 2,
  "transit_id": "transit_zB7fiC9vznpGbcVjnxajj3Zc"
}