---
title: "Analyze Actions Contract"
method: POST
path: "/analyze-actions-contract"
tags: ["app"]
---

# Analyze Actions Contract

`POST /analyze-actions-contract`

Analyze an unsaved draft through Core's real prompt composer.

## Headers

- `X-API-Key` string, nullable
- `API-AUTH-TOKEN` string, nullable

## Request body

- AnalyzeActionsPromptRequest
  - `character` ActionsPromptCharacterDraft, required — Current editor values; this model never writes character state.
    - `character_id` string, nullable
    - `character_name` string
    - `description` string
    - `speaking_style_description` string
    - `speaking_style_sample_dialogues` string
    - `character_traits` object
    - `personality_enabled` boolean
    - `state_of_mind_enabled` boolean
    - `moderation_enabled` boolean
    - `custom_guardrails_enabled` boolean
    - `guardrails_text` string
    - `model_group_name` string, nullable
    - `temperature` number
    - `language_codes` string[]
    - `actions_enabled` boolean
    - `actions_contract` string
    - `show_full_unfiltered_llm_output` boolean
    - `character_actions` string[]
    - `looks_description` string
    - `clothes_description` string
    - `custom_prompt` string
    - `is_narrative_driven` boolean
  - `action_config` ActionConfig
    - `actions` Action[], nullable
      - `value` string, required
    - `characters` ActionCharacterConfig[], nullable
      - `name` string, required
      - `bio` string, required
    - `objects` ActionObjectConfig[], nullable
      - `name` string, required
      - `description` string, required
    - `current_attention_object` ActionObjectConfig
      - `name` string, required
      - `description` string, required
    - `tools` ClientToolDeclaration[], nullable
      - `name` string, required
      - `description` string, required
      - `inputSchema` object, required
  - `runtime_context` ActionsPromptRuntimeContext — Optional edit-time values for components normally known only at runtime.
    - `dynamic_info` DynamicInfo
      - `text` string
      - `keep_in_context` boolean — Whether to keep this dynamic info static in the context for the session.
    - `scene_description` ActionObjectConfig[], nullable
      - `name` string, required
      - `description` string, required
    - `memory` string, nullable
    - `narrative_prompt` string, nullable
    - `knowledge_base_context` string, nullable
    - `vision_available` boolean, nullable
    - `vision_prompt_mode` 'auto' | 'disabled'
    - `provider_mode` 'discrete' | 'realtime', nullable
  - `capabilities` ActionProtocolCapabilities — Client-requested or server-selected realtime protocol capabilities. ``model_output_version`` remains absent for legacy clients so the serialized response shape is compatible with clients that use strict capability decoders.
    - `action_protocol_version` integer
    - `model_output_version` integer, nullable

## Response `200`

Successful Response

- AnalyzeActionsPromptResponse
  - `analysis_version` 'actions-contract-v0'
  - `effective_prompt` ActionsPromptEffectivePrompt, required
    - `sha256` string, required
    - `character_count` integer, required
    - `render_mode` 'combined_json' | 'realtime_tools' | 'natural_text', required
    - `provider_assumption` 'discrete' | 'realtime', required
    - `resolved_model_group_name` string, required
    - `resolved_provider` string, required
    - `resolved_model` string, required
  - `findings` ActionsPromptFinding[], required
    - `source_section` string, required
    - `field_path` string, required
    - `status` 'present' | 'empty' | 'inactive' | 'runtime_placeholder', required
    - `excerpt` string, required
    - `effect` string, required
    - `precedence` string, required
  - `conflicts` ActionsPromptConflict[], required
    - `code` string, required
    - `severity` 'info' | 'warning' | 'error', required
    - `summary` string, required
    - `source_paths` string[], required
    - `recommendation` string, required
  - `inferred_contract` InferredActionsContract, required
    - `output_mode` 'combined_json' | 'realtime_tools' | 'natural_text', required
    - `action_transport` 'action-response' | 'tool-call' | 'tool-and-action-response' | 'none', required
    - `allowed_actions` string[], required
    - `client_tools` string[]
    - `requires_structured_output` boolean, required
    - `summary` string, required
  - `system_generated_contract` SystemGeneratedActionsPromptSection[], required
    - `field_path` string, required
    - `source_section` string, required
    - `content` string, required
    - `effect` string, required
    - `precedence` string, required
  - `recommendations` string[], required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-04** `f44933ff97dc` — 3 info
  - added the new optional request property `capabilities`
  - added the new optional request property `runtime_context/anyOf[subschema #1: ActionsPromptRuntimeContext]/vision_prompt_mode`
  - added the required property `system_generated_contract` to the response with the `200` status
- **2026-08-31** `6d7137301537` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/convai/apis/fastapi/changes/analyze-actions-contract/post.md)

---

[API](https://skmtc.dev/convai/apis/fastapi.md) · [All operations](https://skmtc.dev/convai/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/convai/fastapi/revisions/f44933ff97dc/schema)