Storybeat Completion

Analyze Narrative Progression within Subtxt

The Storybeat Completion endpoint enables writers and developers to verify the completion status of narrative movements (storybeats) within a specific family. By analyzing the input storytelling text against the child storybeats of a parent storybeat, the endpoint determines whether all necessary storybeats are fulfilled and provides detailed feedback when they are not. This helps guide storytelling in alignment with Subtxt's structured framework.

Using the Storybeat Completion Endpoint

To evaluate the completion of storybeats within a family, submit a POST request to the storybeat/completion endpoint. The endpoint verifies the alignment of the storytelling text with child storybeats and determines whether all storybeats are satisfied. If the storytelling is incomplete, the response includes an explanation of the missing or unfulfilled beats.

Note: The supplied storybeat_id must represent a parent storybeat that has already been broken down into its four child storybeats. If the parent storybeat has not been decomposed into the required child beats, the request will fail.

API Endpoint

URL:
https://api.subtxt.app/api/v1/storybeat/completion

Parameters

The storybeat/completion endpoint accepts the following parameters:

If the supplied storybeat_id does not meet the requirement of being broken down into four child storybeats, the API will return an error message indicating this condition.

Request Example

Here’s a sample POST request:

curl -X POST https://api.subtxt.app/api/v1/storybeat/completion \
-H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-d '{
        "structure_id": "struct_e7d1b3d29cfc42d4",
        "storybeat_id": "beat_bdf8b3d46c6d4a2e",
        "storytelling": "The detective uncovers a crucial clue, solidifying the case while addressing personal doubts about the suspect."
    }'

Sample Responses

Example 1: All Child Storybeats Fulfilled

In this case, the narrative satisfies all the child storybeats of the parent.

Request:

{
    "structure_id": "struct_e7d1b3d29cfc42d4",
    "storybeat_id": "beat_bdf8b3d46c6d4a2e",
    "storytelling": "The detective uncovers a crucial clue, solidifying the case while addressing personal doubts about the suspect."
}

Response:

{
    "storybeat_complete": true,
    "explanation": "All child storybeats of the specified storybeat have been fulfilled."
}

Example 2: Incomplete Child Storybeats

Here, the narrative does not satisfy all child storybeats. The explanation field provides detailed feedback on what is missing or incomplete.

Request:

{
    "structure_id": "struct_e7d1b3d29cfc42d4",
    "storybeat_id": "beat_8af33fa2a44d3c20",
    "storytelling": "Ophelia, eager to mend the ongoing familial tensions that her presence exacerbates, decides to bake cookies as a peace offering."
}

Response:

{
    "storybeat_complete": false,
    "explanation": "The submitted storytelling only addresses the initial setup of Child Beat 1, where Ophelia decides to bake cookies as a peace offering to mend familial tensions. However, it does not delve into the aftermath of her mistake, the reactions of other family members, or the deeper tensions that arise as a result. None of the other child beats (2, 3, or 4) are present, as there is no exploration of trust, testing, or arguments over the cause of the trouble. Additionally, the last child beat (Child Beat 4) is entirely absent, meaning the scene does not turn or reach a definitive conclusion. The storytelling is incomplete and fails to fulfill the parent beat's thematic objective of illustrating an abundance of skill (or lack thereof) and its impact on family dynamics."
}

Example 3: Invalid Storybeat ID (Missing Child Beats)

If the supplied storybeat_id has not been broken down into its required four child storybeats, the request will fail with an error message.

Request:

{
    "structure_id": "struct_e7d1b3d29cfc42d4",
    "storybeat_id": "beat_A746djf33kfj97",
    "storytelling": "The detective begins investigating the case but does not reach a resolution."
}

Response:

{
    "error": "The supplied storybeat_id must represent a parent storybeat that has been broken down into four child Storybeats. Please ensure the Storybeat has been fully decomposed before making this request."
}

Summary

The Storybeat Completion endpoint ensures that the supplied storybeat_id corresponds to a fully decomposed parent storybeat and verifies the fulfillment of all child storybeats. It provides clear feedback when storytelling is incomplete or when the required conditions for evaluating the storybeat are not met, guiding writers to align their narratives with Subtxt's structured framework.

Feedback and Support

If you have questions or encounter issues with this API, please contact support for assistance.