Skip to main content
POST
Rationale AI
Collective Intelligence: This endpoint analyzes voting rationales to extract patterns, common themes, and underlying values that influenced governance decisions across different stakeholder groups for specific vote choices.
The Rationale API provides AI-powered analysis of voting rationales across different stakeholder groups in Cardano’s governance system, filtered by vote type (Yes/No votes).

Request Headers

string
required
Your API key for authentication

Request Body

string
required
ID of the proposal to analyze rationales for
string
required
Type of vote to analyze: β€œyes” or β€œno” - only these values are allowed
string
default:"all"
Stakeholder group to focus on: β€œall”, β€œdrep”, β€œspo”, or β€œcc” (Constitutional Committee)
string
Custom system prompt to override the default analysis instructions. Use this to customize the analysis style, focus areas, or output format while preserving essential governance context.

Custom System Prompts

Flexible Analysis: Customize the AI analysis style while preserving essential governance context and vote breakdown data.

Default System Prompt

The API uses this default system prompt when no custom prompt is provided:

Using Custom System Prompts

Replace the default instructions with your own analysis approach:

Best Practices for Custom Prompts

Define Your Role

Specify Expertise: β€œYou are a [role] specializing in [area]”Examples:
  • Political scientist studying blockchain governance
  • Financial analyst focusing on treasury management
  • Sociologist examining community dynamics
  • Legal expert in constitutional compliance

Set Analysis Focus

Specify Perspective: What lens should the analysis use?Examples:
  • Economic impact and financial sustainability
  • Technical feasibility and implementation
  • Legal compliance and constitutional issues
  • Community sentiment and social dynamics

Define Output Style

Format Requirements: How should results be presented?Examples:
  • Academic paper format with citations
  • Executive summary for decision makers
  • Technical report with recommendations
  • Comparative analysis with scoring

Specify Depth Level

Detail Level: How comprehensive should the analysis be?Examples:
  • High-level strategic overview
  • Detailed technical assessment
  • Nuanced social dynamics analysis
  • Quantitative pattern recognition

Custom Prompt Examples

Tips for Better Analysis

Context Preservation: Essential governance data (vote breakdowns, proposal details, rationale lists) are automatically included regardless of your custom prompt.
Effective Prompting: Use specific, actionable instructions for better results:
  • Be Specific: β€œFocus on economic implications” vs β€œanalyze from financial perspective with emphasis on treasury sustainability, risk management, and long-term fiscal health”
  • Define Structure: Specify how you want results organized (bullet points, numbered sections, tables, etc.)
  • Set Expectations: Clarify the depth and style of analysis needed
  • Include Context: Mention any specific frameworks, theories, or methodologies to apply

Custom Prompt Guidelines

Do:
  • Specify your expertise area and perspective
  • Define the analysis framework or methodology
  • Set clear expectations for output format
  • Include specific focus areas or evaluation criteria
  • Use domain-specific terminology appropriately
Don’t:
  • Override essential vote data (automatically preserved)
  • Request formats incompatible with the governance context
  • Use prompts that ignore the provided rationales
  • Create prompts that don’t match your stakeholder group filter
  • Make the prompt overly complex or contradictory

Response Structure

Filtered Response: The API returns only analysis and rationales for requested stakeholder groups. Empty groups are omitted entirely for cleaner responses.
object
object
object
Raw rationales from voters (only includes requested groups with data)

Response Filtering Logic

Clean Responses: The API implements intelligent filtering to return only relevant data:
  • Specific Group Requests ("drep", "spo", "cc"): Returns only that group’s analysis and rationales
  • All Groups Request ("all"): Returns all groups that have rationales (skips empty groups)
  • Empty Groups: Omitted entirely from response (no empty arrays or empty analysis)
  • Context Data: vote_percentages always included for full proposal context

Analysis Output Format

The API returns structured markdown analysis with consistent sections:
  • πŸ“Š What the Numbers Tell Us: Vote breakdown and community sentiment
  • 🎯 Main Concerns and Themes: Top 3-4 identified themes with explanations
  • πŸ’‘ What Matters Most to These Voters: Core values and principles
  • πŸ€” Mixed Feelings or Conditions: Conditional statements and uncertainties
  • πŸ‘₯ How Their Role Influenced Their Thinking: Role-specific perspectives
  • 🎯 Bottom Line: Summary of main reasoning

Processing Methods

Automatic Optimization: The API automatically selects the optimal processing method based on rationale volume.
  • Direct Analysis (≀7,600 tokens): Single comprehensive analysis
  • Token-Based Summarization (>7,600 tokens): Intelligent chunking with summary synthesis

Technical Specifications

  • Context Window: GPT-4o 18,000 tokens
  • Safe Input Limit: 7,600 tokens (70% of capacity)
  • Token Measurement: Precise GPT tokenizer counting
  • Processing: ALL available rationales (complete coverage)

Status Codes

Notes

Required Parameter: The vote_type parameter is mandatory. The API analyzes rationales from voters who chose the specified vote type only.
Complete Coverage: The API processes ALL available rationales for the specified parameters, not samples, ensuring comprehensive analysis regardless of dataset size.
Optimized Responses: Empty groups are automatically filtered out to provide clean, focused responses without unnecessary empty data structures.

Advanced Usage Tips

Maximize Analysis Value: Combine different analysis approaches and stakeholder perspectives for comprehensive governance insights.

Multi-Perspective Analysis Strategy

Comparative Analysis:
  • Run the same query with different custom prompts
  • Compare results across stakeholder groups
  • Analyze both Yes and No votes for complete picture
  • Use different analytical frameworks for deeper insights
Sequential Analysis:
  1. Start with default analysis for comprehensive overview
  2. Apply domain-specific prompts for targeted insights
  3. Use legal/compliance perspective for risk assessment
  4. Apply technical lens for implementation considerations

Prompt Optimization Tips

Iterative Refinement:
  • Start with broad expertise-based prompts
  • Refine based on initial results
  • Add specific focus areas as needed
  • Test different analytical frameworks
Context Integration:
  • Reference your organizational context
  • Include relevant regulatory requirements
  • Consider stakeholder communication needs
  • Align with existing analytical processes
Quality Assurance:
  • Compare custom prompt results with default analysis
  • Validate insights against known stakeholder positions
  • Cross-reference with other governance data sources
  • Consider multiple analytical perspectives for important decisions