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

x-api-key

string

required

Your API key for authentication

Request Body

govaction_id

string

required

ID of the proposal to analyze rationales for

vote_type

string

required

Type of vote to analyze: “yes” or “no” - only these values are allowed

for

string

default:"all"

Stakeholder group to focus on: “all”, “drep”, “spo”, or “cc” (Constitutional Committee)

custom_system_prompt

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:

You are an expert analyst tasked with producing a comprehensive, structured, and easy-to-understand analysis of a community vote or live proposal. Your job is to break down vote data clearly and interpret voter rationales with depth and nuance. You must return all data in Markdown format for readability.

Your response must be well-structured using bullet points, numbered lists, and clear headings. Combine structured formatting with insightful analysis while maintaining conversational, accessible language.

Using Custom System Prompts

Replace the default instructions with your own analysis approach:

{
  "govaction_id": "gov_action123...",
  "vote_type": "no", 
  "for": "drep",
  "custom_system_prompt": "You are a political scientist specializing in decentralized governance. Focus on institutional dynamics, power structures, and democratic theory. Analyze voting patterns through the lens of public choice theory and collective action problems. Provide academic-level insights with citations to relevant literature where applicable."
}

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

Political Science Analysis

You are a political scientist specializing in digital democracy and decentralized governance systems. Analyze the voting rationales through the lens of democratic theory, focusing on:

1. Representation quality and delegate responsiveness
2. Information asymmetries and voter competence
3. Coalition formation and factional dynamics
4. Institutional design effects on outcomes

Structure your analysis as an academic paper section with clear theoretical frameworks. Reference relevant concepts from political science literature such as principal-agent theory, median voter theorem, or collective action problems where applicable.

Financial Risk Assessment

You are a blockchain treasury analyst with expertise in decentralized finance and risk management. Evaluate the voting rationales from a financial perspective, focusing on:

1. Fiscal responsibility and sustainability concerns
2. Risk assessment and mitigation strategies
3. Economic incentives and market dynamics
4. Treasury management best practices

Provide quantitative insights where possible and structure your analysis as a risk assessment report with clear recommendations for financial governance.

Legal Compliance Review

You are a legal expert specializing in blockchain governance and constitutional law. Analyze the voting rationales for legal and constitutional compliance issues, focusing on:

1. Constitutional adherence and procedural compliance
2. Legal precedent and governance framework integrity
3. Rights protection and due process concerns
4. Regulatory implications and compliance risks

Structure your analysis as a legal memorandum with clear constitutional interpretation and compliance recommendations.

Technical Implementation Analysis

You are a blockchain developer and systems architect with expertise in governance implementation. Evaluate the voting rationales from a technical feasibility perspective, focusing on:

1. Implementation complexity and technical risks
2. System architecture and scalability concerns
3. Integration challenges and compatibility issues
4. Performance impact and resource requirements

Provide technical depth appropriate for development teams and structure your analysis with clear implementation recommendations.

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.

data

object

Show Properties

analysis

object

AI-generated structured markdown analysis of rationales by requested stakeholder group(s) only

Show Analysis Object

DRep

string

Structured markdown analysis of DRep rationales (only if “drep” requested or “all” with DRep data)

SPO

string

Structured markdown analysis of SPO rationales (only if “spo” requested or “all” with SPO data)

ConstitutionalCommittee

string

Structured markdown analysis of Constitutional Committee rationales (only if “cc” requested or “all” with CC data)

proposal_id

string

ID of the analyzed proposal

proposal_title

string

Title of the analyzed proposal

vote_type

string

Vote type that was analyzed (yes/no)

vote_percentages

object

Complete voting breakdown by stakeholder group (always includes all groups for context)

Show Vote Percentages

DRep

object

DRep voting breakdown including detailed No vote breakdown

Show Properties

majority

string

Majority vote outcome (yes, no, abstain)

percentages

object

Percentage breakdown of votes

Show Percentages

Yes

number

Percentage of “yes” votes

number

Percentage of “no” votes (includes all no categories)

Abstain

number

Percentage of “abstain” votes

counts

object

Count of votes

Show Counts

Yes

number

Number of “yes” votes

number

Number of “no” votes

Abstain

number

Number of “abstain” votes

SPO

object

SPO voting breakdown including detailed No vote breakdown

Show Properties

majority

string

Majority vote outcome (yes, no, abstain)

percentages

object

Percentage breakdown of votes

Show Percentages

Yes

number

Percentage of “yes” votes

number

Percentage of “no” votes (includes all no categories)

Abstain

number

Percentage of “abstain” votes

counts

object

Count of votes

Show Counts

Yes

number

Number of “yes” votes

number

Number of “no” votes

Abstain

number

Number of “abstain” votes

ConstitutionalCommittee

object

Constitutional Committee voting breakdown including detailed No vote breakdown

Show Properties

majority

string

Majority vote outcome (yes, no, abstain)

percentages

object

Percentage breakdown of votes

Show Percentages

Yes

number

Percentage of “yes” votes

number

Percentage of “no” votes (includes all no categories)

Abstain

number

Percentage of “abstain” votes

counts

object

Count of votes

Show Counts

Yes

number

Number of “yes” votes

number

Number of “no” votes

Abstain

number

Number of “abstain” votes

meta

object

Show Properties

group_filter

string

Filter used for stakeholder groups

vote_type

string

Vote type that was analyzed

rationale_counts

object

Count of rationales analyzed by group (only includes requested groups with data)

Show Properties

DRep

number

Number of DRep rationales analyzed (only if requested and available)

SPO

number

Number of SPO rationales analyzed (only if requested and available)

ConstitutionalCommittee

number

Number of CC rationales analyzed (only if requested and available)

total_rationales_processed

number

Total number of rationales processed across requested groups

precise_token_count

number

Exact token count using GPT tokenizer for processed rationales

token_limits

object

Token limits and configuration used

Show Properties

gpt4o_max_context

number

GPT-4o maximum context window (18,000)

safe_input_limit

number

Safe input limit used (7,600 tokens)

output_token_reserve

number

Tokens reserved for response output (5,000)

processing_method

string

Method used: “direct_analysis” or “precise_token_based_summarization”

custom_prompt_used

boolean

Whether a custom system prompt was provided for this analysis

processed_votes_count

number

Total number of votes processed from database for requested groups

timings

object

Performance metrics for the request

Show Properties

fetch_proposal_data

number

Time taken to fetch proposal data (ms)

fetch_votes

number

Time taken to fetch votes (ms)

extract_rationales

number

Time taken to extract rationales (ms)

generate_ai_analysis

number

Time taken for AI analysis (ms)

total

number

Total request processing time (ms)

rationales

object

Raw rationales from voters (only includes requested groups with data)

Show Properties

DRep

array

Array of DRep rationales (only if “drep” requested or “all” with DRep data)

Show Rationale Object

string

Voter ID who provided the rationale

comment

string

The rationale text provided by the voter

SPO

array

Array of SPO rationales (only if “spo” requested or “all” with SPO data)

Show Rationale Object

string

Voter ID who provided the rationale

comment

string

The rationale text provided by the voter

ConstitutionalCommittee

array

Array of CC rationales (only if “cc” requested or “all” with CC data)

Show Rationale Object

string

Voter ID who provided the rationale

comment

string

The rationale text provided by the voter

{
  "data": {
    "analysis": {
      "DRep": "## 📊 What the Numbers Tell Us\n\n- **Explicit No Votes**: 1.62B ADA (active voters who chose \"No\")\n- **Not Voted**: 1.55B ADA (eligible voters who didn't participate)\n...",
      "SPO": "## 📊 What the Numbers Tell Us\n\n- **Explicit No Votes**: 612.37M ADA (active voters who chose \"No\")\n- **Not Voted**: 13.89B ADA (eligible voters who didn't participate)...",
      "ConstitutionalCommittee": "## 📊 What the Numbers Tell Us\n- **Explicit No Votes**: N/A ADA (active voters who chose \"No\")\n- **Not Voted**: N/A ADA (eligible voters who didn't p..."
    },
    "proposal_id": "gov_action10ueqgzwenxr39le68n0se9peu92r7gm2846xwehh3u0ahc0qd0uqqyljxu5",
    "proposal_title": "Set 2025 Net Change Limit of 300M ADA, 2026 Net Change Limit of 250M ADA",
    "vote_type": "no",
    "vote_percentages": {
      "SPO": {
        "counts": { "No": 22, "Yes": 29, "Abstain": 1 },
        "majority": "No",
        "percentages": { "No": 96.44, "Yes": 3.56 }
      },
      "DRep": {
        "counts": { "No": 111, "Yes": 141, "Abstain": 15 },
        "majority": "No",
        "percentages": { "No": 65.25, "Yes": 34.75 }
      },
      "ConstitutionalCommittee": {
        "counts": { "No": 4, "Yes": 1, "Abstain": 1 },
        "majority": "No",
        "percentages": { "No": 83.33, "Yes": 16.67 }
      }
    }
  },
  "meta": {
    "group_filter": "all",
    "vote_type": "no",
    "rationale_counts": {
      "DRep": 26,
      "SPO": 1,
      "ConstitutionalCommittee": 4
    },
    "total_rationales_processed": 31,
    "precise_token_count": 6276,
    "token_limits": {
      "gpt4o_max_context": 18000,
      "safe_input_limit": 7600,
      "output_token_reserve": 5000
    },
    "processed_votes_count": 137,
    "processing_method": "precise_token_based_summarization",
    "custom_prompt_used": false,
    "timings": {
      "fetch_proposal_data": 247,
      "fetch_votes": 132,
      "extract_rationales": 12,
      "generate_ai_analysis": 38004,
      "total": 38396
    }
  },
  "rationales": {
    "DRep": [
      {
        "id": "drep1y23kabcdefg...",
        "comment": "I'm voting \"No\" on t..."
      }
    ],
    "SPO": [
      {
        "id": "pool1vc8jhijklmn...",
        "comment": "Please provide some ..."
      }
    ],
    "ConstitutionalCommittee": [
      {
        "id": "cc_hot1qvr7p6mlmnopqus...",
        "comment": "The published rationale for t..."
      }
    ]
  }
}

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

Status Code	Description
200	Success - Analysis generated successfully
400	Bad Request - Invalid or missing required parameters
401	Unauthorized - Missing or invalid API key
404	Not Found - Proposal not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

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:

Start with default analysis for comprehensive overview
Apply domain-specific prompts for targeted insights
Use legal/compliance perspective for risk assessment
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

Overview

DRep API

Proposal API

Rationale API

Request Headers

Request Body

Custom System Prompts

Default System Prompt

Using Custom System Prompts

Best Practices for Custom Prompts

Define Your Role

Set Analysis Focus

Define Output Style

Specify Depth Level

Custom Prompt Examples

Tips for Better Analysis

Custom Prompt Guidelines

Response Structure

Response Filtering Logic

Analysis Output Format

Processing Methods

Technical Specifications

Status Codes

Notes

Advanced Usage Tips

Multi-Perspective Analysis Strategy

Prompt Optimization Tips

Overview

DRep API

Proposal API

Rationale API

​Request Headers

​Request Body

​Custom System Prompts

​Default System Prompt

​Using Custom System Prompts

​Best Practices for Custom Prompts

Define Your Role

Set Analysis Focus

Define Output Style

Specify Depth Level

​Custom Prompt Examples

​Tips for Better Analysis

​Custom Prompt Guidelines

​Response Structure

​Response Filtering Logic

​Analysis Output Format

​Processing Methods

​Technical Specifications

​Status Codes

​Notes

​Advanced Usage Tips

​Multi-Perspective Analysis Strategy

​Prompt Optimization Tips

Request Headers

Request Body

Custom System Prompts

Default System Prompt

Using Custom System Prompts

Best Practices for Custom Prompts

Custom Prompt Examples

Tips for Better Analysis

Custom Prompt Guidelines

Response Structure

Response Filtering Logic

Analysis Output Format

Processing Methods

Technical Specifications

Status Codes

Notes

Advanced Usage Tips

Multi-Perspective Analysis Strategy

Prompt Optimization Tips