API Reference

Storyforms

Endpoint: /v1/storyform

This endpoint provides a detailed overview of a specific Storyform, listing the individual IDs of Transits, Perspectives, Progressions, and Events. The response is organized by Throughline, with each Throughline displaying associated Perspectives and Storybeats.

Endpoint

URL: api.subtxt.app/v1/storyform

Method: POST

Request Body

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

{
  "user_id": "required string",
  "structure_id": "required 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").

Response

The response will return a detailed JSON object listing the available transits, perspectives, progressions, and events organized by throughline.

Example Response

{
  "throughlines": {
    "Objective Story": {
      "perspectives": [
        {
          "perspective_id": "perspective_xY5wV4uT3sR2",
          "description": "Visualizing possibilities within the Objective Story context",
          "storybeats": [
            {
              "transit_id": "transit_zB7fiC9vznpGbcVjnxajj3Zc",
              "progressions": [
                {
                  "progression_id": "progression_bF3gH2sP1lK9",
                  "events": [
                    {
                      "event_id": "event_cD3eF4gH5iJ6",
                      "description": "Conflict between the crew members and unexpected obstacles"
                    },
                    {
                      "event_id": "event_dH5iJ6gK7lL8",
                      "description": "The crew uncovers a hidden agenda"
                    }
                  ]
                }
              ]
            },
            {
              "transit_id": "transit_dT4fU5gV6nO8",
              "progressions": [
                {
                  "progression_id": "progression_gL4mN5vB2xK3",
                  "events": [
                    {
                      "event_id": "event_fJ2lM5oN7pP9",
                      "description": "A character's hidden past comes to light"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    "Main Character": {
      "perspectives": [
        {
          "perspective_id": "perspective_wH3uV4rT6sR2",
          "description": "Internal struggles of the Main Character",
          "storybeats": [
            {
              "transit_id": "transit_kN5bM6vW2pX9",
              "progressions": [
                {
                  "progression_id": "progression_mF4yT5oU3sJ8",
                  "events": [
                    {
                      "event_id": "event_jB2dN7vT8gF9",
                      "description": "Main Character contemplates their decision"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Structure

throughlines: Lists each Throughline (e.g., Objective Story, Main Character) within the storyform.
perspectives: For each Throughline, available perspectives are listed by perspective_id (hashed), along with a description explaining the Perspective’s focus.
storybeats: Each Perspective contains Transits, which are further broken down into Progressions and Events:
- transit_id: The hashed ID for each Transit.
- progressions: Each Transit contains one or more Progressions, listed by progression_id (hashed).
- events: Each Progression contains one or more Events, listed by event_id (hashed), along with a brief description.

Notes

IDs Are Hashed: All identifiers are returned as hashed strings for security and privacy purposes.
Hierarchy: The structure is organized from Throughline → Perspectives → Transits → Progressions → Events, allowing users to traverse the entire Storyform.
Transits: Each Transit can have between 1 and 4 entries (min: 1, max: 4), corresponding to major story shifts.

Example Request

{
  "user_id": "user_a1B2c3D4e5F6",
  "structure_id": "structure_g7H8i9J0k1L2"
}

Response Explanation

This request would return all available Transits, Progressions, and Events within the specified Structure, grouped by Throughline and Perspective. Each item is listed with its hashed ID, allowing further requests to focus on specific Transits, Progressions, or Events if needed.