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

# DRep AI

> Search and filter Delegated Representatives (DReps) using natural language queries with AI-powered analytics

<Note>
  **Enhanced AI-Powered Search**: The DRep AI API uses advanced natural language processing to understand complex queries about Cardano's Delegated Representatives, including their voting patterns, attributes, and governance participation.
</Note>

The DRep AI API enables you to find DReps based on comprehensive criteria, including their attributes (voting power, delegators, participation rate, alignment scores) and their detailed voting behavior on specific proposals using natural language queries.

## Request Headers

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

## Request Body

<ParamField body="query" type="string" required>
  Natural language query describing the DReps you want to find. Supports complex queries with AND/OR logic, proposal-specific searches, and attribute-based filtering.

  **Example queries:**

  * `"Find DReps with more than 100M ADA voting power"`
  * `"Show active DReps who voted yes on the Cardano NCL proposal"`
  * `"Find DReps who voted yes on treasury proposals and no on parameter changes"`
  * `"Show DReps registered in 2024 with high participation rates"`
</ParamField>

<ParamField body="page" type="number" default="1">
  Page number for pagination (minimum: 1)
</ParamField>

<ParamField body="limit" type="number" default="10">
  Number of results per page (minimum: 1, maximum: 100)
</ParamField>

<ParamField body="sort" type="string" default="default">
  Sort field for ordering results. Available options:

  * `"default"` - Default sorting (by voting power)
  * `"name"` - Sort by DRep name (alphabetical)
  * `"participation"` - Sort by participation rate
  * `"votingPower"` - Sort by voting power (ADA delegated)
  * `"delegators"` - Sort by number of delegators
  * `"alignment"` - Sort by alignment score
</ParamField>

<ParamField body="sortDirection" type="string" default="desc">
  Sort direction for ordering results:

  * `"desc"` - Descending order (highest to lowest)
  * `"asc"` - Ascending order (lowest to highest)

  **Note:** For name sorting, `"asc"` = A-Z, `"desc"` = Z-A
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of DReps matching the query

  <Expandable title="DRep Object">
    <ResponseField name="drepId" type="string">
      Unique Bech32 identifier for the DRep (starts with "drep1")
    </ResponseField>

    <ResponseField name="id" type="string">
      Internal database UUID
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the DRep (falls back to drepId if no name set)
    </ResponseField>

    <ResponseField name="status" type="string">
      Current DRep status. Possible values:

      * `"active"` - Currently participating in governance
      * `"inactive"` - Not currently participating
      * `"retired"` - No longer participating
      * `"registered"` - Registered but not yet active
    </ResponseField>

    <ResponseField name="metrics" type="object">
      <Expandable title="Performance Metrics">
        <ResponseField name="votingPower" type="number">
          Total amount of ADA delegated to this DRep (in ADA)
        </ResponseField>

        <ResponseField name="totalDelegators" type="number">
          Number of wallets delegating to this DRep
        </ResponseField>

        <ResponseField name="participationRate" type="number">
          Percentage of allowed proposals this DRep has voted on (0-100)
        </ResponseField>

        <ResponseField name="globalAlignment" type="number">
          Average alignment percentage with community consensus across all votes (0-100)
        </ResponseField>

        <ResponseField name="communityAlignment" type="number">
          Alignment with community-specific voting patterns (currently always 0)
        </ResponseField>

        <ResponseField name="proposalsVoted" type="number">
          Total number of proposals this DRep has voted on
        </ResponseField>

        <ResponseField name="totalAllowedProposals" type="number">
          Number of proposals this DRep was eligible to vote on
        </ResponseField>

        <ResponseField name="totalProposals" type="number">
          Total number of proposals in the governance system
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="links" type="array">
      Array of URLs and social media links associated with the DRep
    </ResponseField>

    <ResponseField name="motivations" type="string">
      DRep's stated motivations for participation
    </ResponseField>

    <ResponseField name="objectives" type="string">
      DRep's stated objectives
    </ResponseField>

    <ResponseField name="qualifications" type="string">
      DRep's qualifications
    </ResponseField>

    <ResponseField name="profilePic" type="string">
      URL to profile picture (if available)
    </ResponseField>

    <ResponseField name="registration_date" type="string">
      ISO timestamp of registration
    </ResponseField>

    <ResponseField name="username" type="string">
      Username (usually same as drepId)
    </ResponseField>

    <ResponseField name="voting_history" type="array">
      <Expandable title="Properties">
        <ResponseField name="alignmentStatus" type="string">
          Whether the vote aligned with majority ("aligned", "opposed", "not\_voted")
        </ResponseField>

        <ResponseField name="date" type="string">
          Date of the vote (YYYY-MM-DD)
        </ResponseField>

        <ResponseField name="globalAlignment" type="number">
          Global alignment percentage for this vote
        </ResponseField>

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

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

        <ResponseField name="majorityVote" type="string">
          The majority vote on this proposal
        </ResponseField>

        <ResponseField name="proposalUrl" type="string">
          URL to the proposal details
        </ResponseField>

        <ResponseField name="rationale" type="string">
          Proposal rationale
        </ResponseField>

        <ResponseField name="type" type="string">
          Type of proposal (InfoAction, ParameterChange, etc.)
        </ResponseField>

        <ResponseField name="subtype" type="string">
          Subtype of proposal (if applicable)
        </ResponseField>

        <ResponseField name="vote" type="string">
          DRep's vote (Yes, No, Abstain)
        </ResponseField>

        <ResponseField name="drepVotingAllowed" type="boolean">
          Whether DRep voting was allowed on this proposal
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="active_since" type="string">
      Date when the DRep became active
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Detailed metadata about the DRep
    </ResponseField>

    <ResponseField name="location" type="string">
      Geographic location (if provided)
    </ResponseField>

    <ResponseField name="url" type="string">
      Primary URL associated with the DRep
    </ResponseField>

    <ResponseField name="other_links" type="array">
      Additional links associated with the DRep
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp when the record was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp when the record was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Query Analysis and Results">
    <ResponseField name="explanation" type="string">
      AI-generated explanation of the search results, including key insights and patterns
    </ResponseField>

    <ResponseField name="query" type="string">
      Original query string as submitted
    </ResponseField>

    <ResponseField name="parsedQuery" type="object">
      Detailed breakdown of how the AI interpreted your query

      <Expandable title="Query Interpretation">
        <ResponseField name="queryType" type="string">
          Type of query detected. Possible values:

          * `"proposal_first"` - Query focused on proposal voting behavior
          * `"drep_first"` - Query focused on DRep attributes
          * `"balanced"` - Query combining both proposal and DRep criteria
          * `"voting_history"` - Query requesting specific DRep's voting history
        </ResponseField>

        <ResponseField name="proposalFilters" type="object">
          Filters applied to proposals, including title searches and proposal types
        </ResponseField>

        <ResponseField name="voteFilters" type="object">
          Filters applied to voting behavior (yes/no/abstain patterns)
        </ResponseField>

        <ResponseField name="drepFilters" type="object">
          Filters applied to DRep attributes (voting power, delegators, etc.)
        </ResponseField>

        <ResponseField name="orderBy" type="array">
          Applied sorting configuration with tie-breaking rules
        </ResponseField>

        <ResponseField name="explanation" type="string">
          Detailed explanation of how the query was interpreted
        </ResponseField>

        <ResponseField name="pagination" type="object">
          Applied pagination settings
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="queryIntent" type="string">
      High-level intent classification of the query
    </ResponseField>

    <ResponseField name="matchedProposals" type="array">
      Proposals that were identified and matched in your query

      <Expandable title="Proposal Match">
        <ResponseField name="id" type="string">
          Unique proposal identifier (gov\_action format)
        </ResponseField>

        <ResponseField name="title" type="string">
          Human-readable proposal title
        </ResponseField>

        <ResponseField name="type" type="string">
          Proposal type. Possible values:

          * `"InfoAction"` - Informational governance action
          * `"ParameterChange"` - Protocol parameter modification
          * `"TreasuryWithdrawal"` - Treasury fund withdrawal
          * `"NewConstitution"` - Constitution or guardrails update
          * `"HardForkInitiation"` - Hard fork proposal
          * `"NoConfidence"` - Motion of no confidence
          * `"UpdateCommittee"` - Constitutional committee update
        </ResponseField>

        <ResponseField name="subtype" type="string">
          Proposal subtype (for ParameterChange proposals). Possible values:

          * `"Network"` - Network-related parameters
          * `"Economic"` - Economic parameters
          * `"Technical"` - Technical parameters
          * `"Governance"` - Governance parameters
          * `null` - No subtype (for non-ParameterChange proposals)
        </ResponseField>

        <ResponseField name="drepVotingAllowed" type="boolean">
          Whether DReps are permitted to vote on this proposal
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="resultCount" type="number">
      Number of DReps returned in this page of results
    </ResponseField>

    <ResponseField name="invalid_titles" type="array">
      Proposal titles mentioned in query that could not be found (if any)
    </ResponseField>

    <ResponseField name="suggested_proposals" type="array">
      Alternative proposal suggestions when exact matches aren't found
    </ResponseField>

    <ResponseField name="usedCache" type="boolean">
      Whether cached results were used to speed up the response
    </ResponseField>

    <ResponseField name="redisAvailable" type="boolean">
      Whether caching system is available
    </ResponseField>

    <ResponseField name="sortInfo" type="object">
      Information about applied sorting

      <Expandable title="Sort Information">
        <ResponseField name="field" type="string">
          The primary sort field used
        </ResponseField>

        <ResponseField name="direction" type="string">
          The sort direction applied ("asc" or "desc")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="optimized" type="boolean">
      Flag indicating this uses the optimized query engine (always true)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination Information">
    <ResponseField name="page" type="number">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of results per page
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of DReps matching the query across all pages
    </ResponseField>

    <ResponseField name="pages" type="number">
      Total number of pages available
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timings" type="object">
  Detailed performance metrics for the request (in milliseconds)

  <Expandable title="Performance Breakdown">
    <ResponseField name="intent_determination" type="number">
      Time to analyze and determine query intent
    </ResponseField>

    <ResponseField name="query_parsing" type="number">
      Time to parse natural language into database filters
    </ResponseField>

    <ResponseField name="database_queries" type="number">
      Time to execute database queries
    </ResponseField>

    <ResponseField name="data_transformation" type="number">
      Time to transform raw data into response format
    </ResponseField>

    <ResponseField name="explanation_generation" type="number">
      Time to generate AI explanation of results
    </ResponseField>

    <ResponseField name="proposal_validation" type="number">
      Time to validate and match proposal references
    </ResponseField>

    <ResponseField name="redis_get" type="number">
      Time to retrieve cached data
    </ResponseField>

    <ResponseField name="redis_set" type="number">
      Time to store data in cache
    </ResponseField>

    <ResponseField name="sort_application" type="number">
      Time to apply sorting and pagination
    </ResponseField>

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

<ResponseExample>
  ```json 200 (Success - Proposal-focused query) theme={null}
  {
    "data": [
      {
        "drepId": "drep1y24xr6m4mkgl7e7886sk3wee7h73mcreysyvhrwzksy5ajqrv0rrv",
        "id": "dc3cfd1e-3308-4223-adf6-da1662a1b4b0",
        "links": [
          "x.com/Crown_Tech1021",
          "crown-tech.co.jp/ctecstakepool",
          "https://www.crown-tech.co.jp/DRep/CTEC-Stake-Pool.jsonld"
        ],
        "metrics": {
          "participationRate": 100,
          "votingPower": 19829102.491109,
          "communityAlignment": 0,
          "proposalsVoted": 12,
          "globalAlignment": 54.19,
          "totalDelegators": 33,
          "totalAllowedProposals": 12,
          "totalProposals": 18
        },
        "motivations": "●目標：Target\n\n・安全で安心できるカルダノネットワークを運営する\n\n　Operate a safe and secure Cardano network.\n\n・カルダノネットワークをより高度な次元へ発展させるために貢献する\n\n　Contribute to the development of the Cardano network to a higher dimension.\n",
        "name": "CTEC-Stake-Pool",
        "objectives": "●ミッション：mission\n\nカルダノネットワークの発展のためにDRepとして活動していきます\n\nI will work as a DRep for the development of the Cardano network.",
        "profilePic": null,
        "qualifications": "●資格：Qualifications\n\n　CTEC Stake Pool Operator（SPO）",
        "registration_date": "2024-11-14T09:54:59+00:00",
        "status": "active",
        "username": "drep1y24xr6m4mkgl7e7886sk3wee7h73mcreysyvhrwzksy5ajqrv0rrv",
        "voting_history": [
          {
            "communityAlignment": "Coming Soon",
            "alignmentStatus": "aligned",
            "date": "2025-03-25",
            "globalAlignment": 54.19,
            "id": "1b75c28f-e77b-4304-b050-9ee894d863f5",
            "isAligned": true,
            "proposalId": "gov_action1nd3t833j7v5sz65k3tp9yyvztw60sjcjgcgjr37682s3m7frwrusqmd2k80",
            "isIncluded": true,
            "proposalTitle": "2025 Net Change Limit",
            "majorityVote": "Yes",
            "proposalUrl": "ipfs://bafkreiaqno22swabd3kcqt2awtgwaucdzaagacoemxwadm3exrchhnfite",
            "rationale": "As agreed with the Cardano Budget Committee, the 2025 Net Change Limit shall begin at the start of Epoch 532 and progress for 72 epochs, concluding in December 2025 at the end of Epoch 604.\n\nThe 2025 Net Change Limit shall be set at 350,000,000,000,000 lovelace (350M ada).\n\nThis figure is derived from our modeling, which projected in October 2024 that the treasury would increase by approximately 351M ada across 2024 (epoch 459-531), including all approved withdrawals (e.g., Catalyst). Based on this analysis, the 2025 Net Change Limit was proposed at 350m ada. From January 5th, 2024, Epoch 459, through December 30th, Epoch 531, the actual total income into the Cardano Treasury was 335,957,093 ada. Since this is within 5% of our proposed number, the 2025 Net Change Limit should stay at 350 million ada.",
            "type": "InfoAction",
            "subtype": null,
            "vote": "Yes",
            "drepVotingAllowed": true
          }
        ],
        "active_since": "2024-11-14T09:54:59",
        "metadata": {
          "drep_id": "drep1y24xr6m4mkgl7e7886sk3wee7h73mcreysyvhrwzksy5ajqrv0rrv",
          "hex": "22aa61eb75dd91ff67c73ea168bb39f5fd1de0792408cb8dc2b4094ec8",
          "url": "https://www.crown-tech.co.jp/DRep/CTEC-Stake-Pool.jsonld",
          "hash": "d679b05cc0de219e47c11333bc1faf0caa6b75d480dbf406b69a60016ef8b551",
          "json_metadata": { /* ... detailed metadata ... */ },
          "bytes": "\\x7b0a20202240636f...",
          "location": null,
          "other_links": [
            "x.com/Crown_Tech1021",
            "crown-tech.co.jp/ctecstakepool"
          ],
          "created_at": "2025-04-09T10:27:41.477642+00:00",
          "updated_at": "2025-05-21T03:14:13.159637+00:00"
        }
      }
    ],
    "meta": {
      "explanation": "Found 112 DReps who voted yes on the Cardano net change proposal and no on the Cardano Treasury DeFi Liquidity Budget, while DRep voting was not allowed for the Plutus V3 Cost Model Parameter Changes. These DReps demonstrate active governance participation with an average participation rate of 84.49% and significant voting power representation.",
      "query": "Find DReps who voted yes on the cardano net change and no on Cardano Treasury DeFi Liquidity Budget",
      "parsedQuery": {
        "queryType": "proposal_first",
        "proposalFilters": {
          "title": {
            "all": [
              "Set a 300 million ADA Net Change Limit for Epochs 563–635",
              "Cardano Treasury DeFi Liquidity Budget"
            ]
          }
        },
        "voteFilters": {
          "vote": {
            "all": [
              {
                "proposalTitle": "Set a 300 million ADA Net Change Limit for Epochs 563–635",
                "value": "yes"
              },
              {
                "proposalTitle": "Cardano Treasury DeFi Liquidity Budget", 
                "value": "no"
              }
            ]
          },
          "voterRole": "DRep"
        },
        "drepFilters": {},
        "orderBy": [
          {
            "column": "participation_data->rate",
            "direction": "desc",
            "nullsPosition": "last",
            "excludeZeros": false
          },
          {
            "column": "basic_info->ada_delegated",
            "direction": "desc", 
            "nullsPosition": "last",
            "excludeZeros": false
          }
        ],
        "explanation": "Query focuses on DReps with specific voting patterns across multiple proposals using AND logic.",
        "pagination": {
          "page": 1,
          "limit": 5,
          "total": 112,
          "pages": 23
        }
      },
      "queryIntent": "proposal_first",
      "matchedProposals": [
        {
          "id": "gov_action1vdlrcftd48qn2zz8egepr6xyfcmxpfz8r69k769gc5mhg662adesq9yy8pl",
          "title": "Set a 300 million ADA Net Change Limit for Epochs 563–635",
          "type": "InfoAction",
          "subtype": null,
          "drepVotingAllowed": true
        },
        {
          "id": "gov_action1fpqwxp2kxvnntr8hpkh9q9djm78ccdww7qlhg5safugh4stmcwzqql5lauu",
          "title": "Cardano Treasury DeFi Liquidity Budget",
          "type": "InfoAction", 
          "subtype": null,
          "drepVotingAllowed": true
        }
      ],
      "resultCount": 1,
      "usedCache": true,
      "redisAvailable": true,
      "sortInfo": {
        "field": "participation",
        "direction": "desc"
      },
      "optimized": true
    },
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 194,
      "pages": 20
    },
    "timings": {
      "intent_determination": 1631,
      "query_parsing": 5060,
      "database_queries": 609,
      "data_transformation": 0,
      "explanation_generation": 2917,
      "proposal_validation": 6649,
      "redis_get": 332,
      "redis_set": 0,
      "sort_application": 1,
      "total": 1120
    }
  }
  ```

  ```json 400 (Bad Request) theme={null}
  {
    "error": "Missing or invalid query",
    "details": "Please provide a valid query string"
  }
  ```

  ```json 401 (Unauthorized) theme={null}
  {
    "error": "Unauthorized",
    "message": "API key is required"
  }
  ```

  ```json 404 (Not Found - No results) theme={null}
  {
    "error": "No DReps found matching your criteria",
    "details": "Could not find proposals with the following title(s): Invalid Proposal Name",
    "suggestions": [
      {
        "id": "gov_action1abc123",
        "title": "Similar Proposal Name",
        "type": "InfoAction"
      }
    ]
  }
  ```

  ```json 404 (Not Found - DRep voting not allowed) theme={null}
  {
    "error": "DReps cannot vote on the specified proposals",
    "details": "DReps are not allowed to vote on the following proposals: Protocol Parameter Change XYZ",
    "disallowedProposals": [
      {
        "id": "gov_action1xyz789",
        "title": "Protocol Parameter Change XYZ", 
        "type": "ParameterChange",
        "subtype": "Technical"
      }
    ]
  }
  ```

  ```json 500 (Internal Server Error) theme={null}
  {
    "error": "Failed to process query",
    "details": "Internal server error occurred while processing the request"
  }
  ```
</ResponseExample>

## Status Codes

| Status Code | Description                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| 200         | Success - DReps found matching the criteria                                  |
| 400         | Bad Request - Invalid query parameters or malformed request                  |
| 401         | Unauthorized - Missing or invalid API key                                    |
| 404         | Not Found - No DReps found matching criteria OR proposal voting restrictions |
| 429         | Too Many Requests - Rate limit exceeded                                      |
| 500         | Internal Server Error - Unexpected server error                              |

## Advanced Features

<Info>
  **Smart Caching**: The API uses intelligent caching to speed up repeated queries. First-time complex queries may take 10-15 seconds, while cached queries return in under 2 seconds.
</Info>

<Warning>
  **Query Performance**: Complex queries involving multiple proposals or detailed vote pattern analysis may take 10-15 seconds on first execution. Subsequent identical queries will be much faster due to caching.
</Warning>