> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syncgovhub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rationale AI

> Get AI analysis of voting rationales for a specific proposal and vote type

<Note>
  **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.
</Note>

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

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Request Body

<ParamField body="govaction_id" type="string" required>
  ID of the proposal to analyze rationales for
</ParamField>

<ParamField body="vote_type" type="string" required>
  Type of vote to analyze: "yes" or "no" - only these values are allowed
</ParamField>

<ParamField body="for" type="string" default="all">
  Stakeholder group to focus on: "all", "drep", "spo", or "cc" (Constitutional Committee)
</ParamField>

<ParamField body="custom_system_prompt" type="string" optional>
  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.
</ParamField>

## Custom System Prompts

<Info>
  **Flexible Analysis**: Customize the AI analysis style while preserving essential governance context and vote breakdown data.
</Info>

### 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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Define Your Role" icon="user-tie" color="#2091ff">
    **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
  </Card>

  <Card title="Set Analysis Focus" icon="bullseye" color="#2091ff">
    **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
  </Card>

  <Card title="Define Output Style" icon="text-slash" color="#2091ff">
    **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
  </Card>

  <Card title="Specify Depth Level" icon="layer-group" color="#2091ff">
    **Detail Level**: How comprehensive should the analysis be?

    **Examples:**

    * High-level strategic overview
    * Detailed technical assessment
    * Nuanced social dynamics analysis
    * Quantitative pattern recognition
  </Card>
</CardGroup>

### Custom Prompt Examples

<Accordion title="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.
  ```
</Accordion>

<Accordion title="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.
  ```
</Accordion>

<Accordion title="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.
  ```
</Accordion>

<Accordion title="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.
  ```
</Accordion>

### Tips for Better Analysis

<Warning>
  **Context Preservation**: Essential governance data (vote breakdowns, proposal details, rationale lists) are automatically included regardless of your custom prompt.
</Warning>

<Check>
  **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
</Check>

### 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

<Info>
  **Filtered Response**: The API returns only analysis and rationales for requested stakeholder groups. Empty groups are omitted entirely for cleaner responses.
</Info>

<ResponseField name="data" type="object">
  <Expandable title="Properties">
    <ResponseField name="analysis" type="object">
      AI-generated structured markdown analysis of rationales by requested stakeholder group(s) only

      <Expandable title="Analysis Object">
        <ResponseField name="DRep" type="string">
          Structured markdown analysis of DRep rationales (only if "drep" requested or "all" with DRep data)
        </ResponseField>

        <ResponseField name="SPO" type="string">
          Structured markdown analysis of SPO rationales (only if "spo" requested or "all" with SPO data)
        </ResponseField>

        <ResponseField name="ConstitutionalCommittee" type="string">
          Structured markdown analysis of Constitutional Committee rationales (only if "cc" requested or "all" with CC data)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="proposal_id" type="string">
      ID of the analyzed proposal
    </ResponseField>

    <ResponseField name="proposal_title" type="string">
      Title of the analyzed proposal
    </ResponseField>

    <ResponseField name="vote_type" type="string">
      Vote type that was analyzed (yes/no)
    </ResponseField>

    <ResponseField name="vote_percentages" type="object">
      Complete voting breakdown by stakeholder group (always includes all groups for context)

      <Expandable title="Vote Percentages">
        <ResponseField name="DRep" type="object">
          DRep voting breakdown including detailed No vote breakdown

          <Expandable title="Properties">
            <ResponseField name="majority" type="string">
              Majority vote outcome (yes, no, abstain)
            </ResponseField>

            <ResponseField name="percentages" type="object">
              Percentage breakdown of votes

              <Expandable title="Percentages">
                <ResponseField name="Yes" type="number">
                  Percentage of "yes" votes
                </ResponseField>

                <ResponseField name="No" type="number">
                  Percentage of "no" votes (includes all no categories)
                </ResponseField>

                <ResponseField name="Abstain" type="number">
                  Percentage of "abstain" votes
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="counts" type="object">
              Count of votes

              <Expandable title="Counts">
                <ResponseField name="Yes" type="number">
                  Number of "yes" votes
                </ResponseField>

                <ResponseField name="No" type="number">
                  Number of "no" votes
                </ResponseField>

                <ResponseField name="Abstain" type="number">
                  Number of "abstain" votes
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="SPO" type="object">
          SPO voting breakdown including detailed No vote breakdown

          <Expandable title="Properties">
            <ResponseField name="majority" type="string">
              Majority vote outcome (yes, no, abstain)
            </ResponseField>

            <ResponseField name="percentages" type="object">
              Percentage breakdown of votes

              <Expandable title="Percentages">
                <ResponseField name="Yes" type="number">
                  Percentage of "yes" votes
                </ResponseField>

                <ResponseField name="No" type="number">
                  Percentage of "no" votes (includes all no categories)
                </ResponseField>

                <ResponseField name="Abstain" type="number">
                  Percentage of "abstain" votes
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="counts" type="object">
              Count of votes

              <Expandable title="Counts">
                <ResponseField name="Yes" type="number">
                  Number of "yes" votes
                </ResponseField>

                <ResponseField name="No" type="number">
                  Number of "no" votes
                </ResponseField>

                <ResponseField name="Abstain" type="number">
                  Number of "abstain" votes
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="ConstitutionalCommittee" type="object">
          Constitutional Committee voting breakdown including detailed No vote breakdown

          <Expandable title="Properties">
            <ResponseField name="majority" type="string">
              Majority vote outcome (yes, no, abstain)
            </ResponseField>

            <ResponseField name="percentages" type="object">
              Percentage breakdown of votes

              <Expandable title="Percentages">
                <ResponseField name="Yes" type="number">
                  Percentage of "yes" votes
                </ResponseField>

                <ResponseField name="No" type="number">
                  Percentage of "no" votes (includes all no categories)
                </ResponseField>

                <ResponseField name="Abstain" type="number">
                  Percentage of "abstain" votes
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="counts" type="object">
              Count of votes

              <Expandable title="Counts">
                <ResponseField name="Yes" type="number">
                  Number of "yes" votes
                </ResponseField>

                <ResponseField name="No" type="number">
                  Number of "no" votes
                </ResponseField>

                <ResponseField name="Abstain" type="number">
                  Number of "abstain" votes
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Properties">
    <ResponseField name="group_filter" type="string">
      Filter used for stakeholder groups
    </ResponseField>

    <ResponseField name="vote_type" type="string">
      Vote type that was analyzed
    </ResponseField>

    <ResponseField name="rationale_counts" type="object">
      Count of rationales analyzed by group (only includes requested groups with data)

      <Expandable title="Properties">
        <ResponseField name="DRep" type="number">
          Number of DRep rationales analyzed (only if requested and available)
        </ResponseField>

        <ResponseField name="SPO" type="number">
          Number of SPO rationales analyzed (only if requested and available)
        </ResponseField>

        <ResponseField name="ConstitutionalCommittee" type="number">
          Number of CC rationales analyzed (only if requested and available)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_rationales_processed" type="number">
      Total number of rationales processed across requested groups
    </ResponseField>

    <ResponseField name="precise_token_count" type="number">
      Exact token count using GPT tokenizer for processed rationales
    </ResponseField>

    <ResponseField name="token_limits" type="object">
      Token limits and configuration used

      <Expandable title="Properties">
        <ResponseField name="gpt4o_max_context" type="number">
          GPT-4o maximum context window (18,000)
        </ResponseField>

        <ResponseField name="safe_input_limit" type="number">
          Safe input limit used (7,600 tokens)
        </ResponseField>

        <ResponseField name="output_token_reserve" type="number">
          Tokens reserved for response output (5,000)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="processing_method" type="string">
      Method used: "direct\_analysis" or "precise\_token\_based\_summarization"
    </ResponseField>

    <ResponseField name="custom_prompt_used" type="boolean">
      Whether a custom system prompt was provided for this analysis
    </ResponseField>

    <ResponseField name="processed_votes_count" type="number">
      Total number of votes processed from database for requested groups
    </ResponseField>

    <ResponseField name="timings" type="object">
      Performance metrics for the request

      <Expandable title="Properties">
        <ResponseField name="fetch_proposal_data" type="number">
          Time taken to fetch proposal data (ms)
        </ResponseField>

        <ResponseField name="fetch_votes" type="number">
          Time taken to fetch votes (ms)
        </ResponseField>

        <ResponseField name="extract_rationales" type="number">
          Time taken to extract rationales (ms)
        </ResponseField>

        <ResponseField name="generate_ai_analysis" type="number">
          Time taken for AI analysis (ms)
        </ResponseField>

        <ResponseField name="total" type="number">
          Total request processing time (ms)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rationales" type="object">
  Raw rationales from voters (only includes requested groups with data)

  <Expandable title="Properties">
    <ResponseField name="DRep" type="array">
      Array of DRep rationales (only if "drep" requested or "all" with DRep data)

      <Expandable title="Rationale Object">
        <ResponseField name="id" type="string">
          Voter ID who provided the rationale
        </ResponseField>

        <ResponseField name="comment" type="string">
          The rationale text provided by the voter
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="SPO" type="array">
      Array of SPO rationales (only if "spo" requested or "all" with SPO data)

      <Expandable title="Rationale Object">
        <ResponseField name="id" type="string">
          Voter ID who provided the rationale
        </ResponseField>

        <ResponseField name="comment" type="string">
          The rationale text provided by the voter
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ConstitutionalCommittee" type="array">
      Array of CC rationales (only if "cc" requested or "all" with CC data)

      <Expandable title="Rationale Object">
        <ResponseField name="id" type="string">
          Voter ID who provided the rationale
        </ResponseField>

        <ResponseField name="comment" type="string">
          The rationale text provided by the voter
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 (All Stakeholder Groups - "for": "all") theme={null}
  {
    "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..."
        }
      ]
    }
  }
  ```

  ```json 200 (DRep Only - "for": "drep") theme={null}
  {
    "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..."
      },
      "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": "drep",
      "vote_type": "no",
      "rationale_counts": {
        "DRep": 26
      },
      "total_rationales_processed": 26,
      "precise_token_count": 5188,
      "token_limits": {
        "gpt4o_max_context": 18000,
        "safe_input_limit": 7600,
        "output_token_reserve": 5000
      },
      "processed_votes_count": 111,
      "processing_method": "precise_token_based_summarization",
      "timings": {
        "fetch_proposal_data": 221,
        "fetch_votes": 134,
        "extract_rationales": 7,
        "generate_ai_analysis": 12674,
        "total": 13037
      }
    },
    "rationales": {
      "DRep": [
        {
          "id": "drep1y23kumvpqgal3t6v4tamwrprjya453p3djam0eqg63usm9su77hjl",
          "comment": "I'm voting \"No\" on this governance action since there is a newer similar GA (\"2025 Net Change Limit\") which does a better job of explaining what it's meant to achieve, why it's needed, and how the authors arrived at the proposed spending cap."
        },
        {
          "id": "drep1y2rvnp40ea4zsl4hqm0ev4qju205jx7mz57u2vwjzzrf50c24jca9",
          "comment": "Not a fan of giant bulk withdrawals from treasury, prefer larger number of smaller withdrawals that would get approved based on their merit by the community governance..."
        }
      ]
    }
  }
  ```

  ```json 200 (SPO Only - "for": "spo") theme={null}
  {
    "data": {
      "analysis": {
        "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)\n- **Auto No Confide..."
      },
      "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": "spo",
      "vote_type": "no",
      "rationale_counts": {
        "SPO": 1
      },
      "total_rationales_processed": 1,
      "precise_token_count": 22,
      "token_limits": {
        "gpt4o_max_context": 18000,
        "safe_input_limit": 7600,
        "output_token_reserve": 5000
      },
      "processed_votes_count": 22,
      "processing_method": "direct_analysis",
      "timings": {
        "fetch_proposal_data": 265,
        "fetch_votes": 74,
        "extract_rationales": 1,
        "generate_ai_analysis": 10104,
        "total": 10444
      }
    },
    "rationales": {
      "SPO": [
        {
          "id": "pool1vc8jhqtwjrjwsfk6a0enx47hd2ufg98c34ta6lvl0zv0uhpech9",
          "comment": "Please provide some research and math proving that it is necessary, effective, and healthy for the network and users."
        }
      ]
    }
  }
  ```

  ```json 200 (Custom System Prompt Example) theme={null}
  {
    "data": {
      "analysis": {
        "DRep": "## Constitutional Compliance Assessment\n\n**Primary Legal Concerns Identified:**\n\n**Procedural Violations:** Multiple rationales cite concerns about constitutional ..."
      },
      "proposal_id": "gov_actionabcdefgh...",
      "proposal_title": "Set 2025 Net Chan...",
      "vote_type": "no",
      "vote_percentages": {
        "DRep": {
          "counts": { "No": 111, "Yes": 141, "Abstain": 15 },
          "majority": "No",
          "percentages": { "No": 65.25, "Yes": 34.75 }
        }
      }
    },
    "meta": {
      "group_filter": "drep",
      "vote_type": "no",
      "rationale_counts": { "DRep": 26 },
      "total_rationales_processed": 26,
      "processing_method": "direct_analysis",
      "custom_prompt_used": true,
      "timings": {
        "generate_ai_analysis": 14521,
        "total": 15892
      }
    },
    "rationales": {
      "DRep": [
        {
          "id": "drep1y23kumabcdeff....",
          "comment": "I'm voting \"No\" on this governance act..."
        }
      ]
    }
  }
  ```

  ```json 200 (No Rationales Available - Empty Response) theme={null}
  {
    "data": {
      "analysis": {},
      "proposal_id": "gov_action10ueqgzwenxr39le68n0se9peu92r7gm2846xwehh3u0ahc0qd0uqqyljxu5",
      "proposal_title": "Set 2025 Net Change Limit of 300M ADA, 2026 Net Change Limit of 250M ADA",
      "vote_type": "yes",
      "vote_percentages": {
        "SPO": {
          "counts": { "No": 22, "Yes": 29, "Abstain": 1 },
          "majority": "No",
          "percentages": { "No": 96.44, "Yes": 3.56 }
        }
      }
    },
    "meta": {
      "group_filter": "spo",
      "vote_type": "yes",
      "rationale_counts": {},
      "total_rationales_processed": 0,
      "precise_token_count": 0,
      "processed_votes_count": 29,
      "processing_method": "direct_analysis"
    },
    "rationales": {}
  }
  ```

  ```json 400 (Missing Vote Type) theme={null}
  {
    "error": "Invalid or missing 'vote_type' parameter",
    "details": "Only 'yes' or 'no' allowed"
  }
  ```

  ```json 400 (Invalid Parameters) theme={null}
  {
    "error": "Invalid 'for' parameter",
    "details": "Must be one of: 'all', 'drep', 'spo', 'cc'"
  }
  ```

  ```json 404 (Not Found) theme={null}
  {
    "error": "Proposal not found",
    "details": "No proposal found with ID: gov_action1example123456789"
  }
  ```
</ResponseExample>

## Response Filtering Logic

<Info>
  **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
</Info>

## 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

<Info>
  **Automatic Optimization**: The API automatically selects the optimal processing method based on rationale volume.
</Info>

* **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

<Warning>
  **Required Parameter**: The `vote_type` parameter is mandatory. The API analyzes rationales from voters who chose the specified vote type only.
</Warning>

<Info>
  **Complete Coverage**: The API processes ALL available rationales for the specified parameters, not samples, ensuring comprehensive analysis regardless of dataset size.
</Info>

<Check>
  **Optimized Responses**: Empty groups are automatically filtered out to provide clean, focused responses without unnecessary empty data structures.
</Check>

## Advanced Usage Tips

<Info>
  **Maximize Analysis Value**: Combine different analysis approaches and stakeholder perspectives for comprehensive governance insights.
</Info>

### 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