API Services

Build With Dramatica

API services expose different integration shapes than MCP.

Dramatica MCP is the agent-native integration layer. Use MCP when an assistant, agent runtime, or MCP-capable client needs tools and resources for story development workflows.

API Services are deterministic HTTPS endpoints for structured data export and evaluation workflows. Use them when an application needs a stable JSON response over HTTP rather than an agent-native tool call.

NCP is the portable narrative context exchange format. It can carry Storyform structure, authored prose, Storybeats, Players, and screenplay content across tools. Narrova saves approved work to the selected Storyform. The NCP file carries the saved material when exported.

Access

Public API Services require OAuth bearer authentication, a verified active Dramatica account, an active Pro subscription, and the relevant API scope. The initial rollout limit is 30 requests per minute per authenticated user.

MCP scopes such as mcp:use, mcp:read, and mcp:write do not authorize REST API Services.

API Keys

Pro subscribers create and revoke public API keys from Account > API Keys. Each key is scoped to the authenticated account, has an expiration window, and can include one or both public API scopes.

The plain bearer token is shown once when the key is created. Existing keys can be reviewed by name, scope, status, creation date, and expiration date, then revoked at any time. Revoked and expired keys cannot authenticate API requests.

To create a key:

  1. Open Account > API Keys.
  2. Name the key for the integration that will use it.
  3. Choose an expiration window: 7 days, 30 days, 90 days, or 1 year.
  4. Choose the minimum scopes the integration needs.
  5. Create the key and store the bearer token before leaving the page.

Use the token in the Authorization header:

curl https://platform.dramatica.com/api/v1/storyforms/storyform_... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Revoke keys from Account > API Keys when an integration no longer needs access or a token may have been exposed.

Storyform Export

GET /api/v1/storyforms/{storyform_uuid}

Required scope: api:read

Returns an owned Storyform as a stable public JSON contract with identity, Story metadata, Dynamics, Four Throughlines, Perspectives, Overviews, Storypoints, Storybeats, and Players.

{
  "storyform": {
    "uuid": "storyform_...",
    "title": "Harrow Bay Storyform",
    "story": {
      "uuid": "story_...",
      "title": "The Clock Beneath Harrow Bay"
    },
    "dynamics": {
      "main_character_resolve": "Change",
      "story_driver": "Action",
      "story_outcome": "Success"
    },
    "throughlines": {
      "objective_story": {
        "domain": "Universe",
        "concern": "Progress"
      }
    }
  },
  "ncp": {
    "schema_version": "1.2.0",
    "story": {
      "id": "story_...",
      "title": "The Clock Beneath Harrow Bay",
      "narratives": [
        {
          "id": "narrative_...",
          "title": "Harrow Bay Storyform",
          "subtext": {
            "perspectives": [],
            "players": [],
            "dynamics": [],
            "storypoints": [],
            "storybeats": []
          },
          "storytelling": {
            "overviews": [],
            "moments": []
          }
        }
      ]
    }
  }
}

The response includes canonical NCP so API consumers can receive the portable narrative exchange object directly through the export endpoint. include=ncp is accepted for compatibility, but NCP is included by default.

Storytelling Evaluation

POST /api/v1/evaluations/storytelling

Required scope: api:evaluate

Evaluates supplied Storytelling against a requested Narrative Function, Appreciation, or semantic target.

{
  "target": "Disbelief",
  "storytelling": "Josephine tells Margaret that she is skeptical of anyone she has never met before."
}
{
  "approved": true,
  "evaluation": "Passable",
  "score": 0.85,
  "explanation": "The storytelling expresses Disbelief as a conflict process.",
  "target": {
    "name": "Disbelief",
    "semantic_id": "12345",
    "type": "narrative_function"
  }
}

Example request:

curl https://platform.dramatica.com/api/v1/evaluations/storytelling \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "Disbelief",
    "storytelling": "Josephine tells Margaret that she is skeptical of anyone she has never met before."
  }'

Future Storybeat Completion

Storybeat completion is not publicly available in this rollout. Completion design is tracked separately before any public endpoint is exposed.