Proposed Agent API v2 — not yet available

This is the proposed v2 contract. The v2 endpoints are not live yet. This page will be replaced by an interactive OpenAPI reference generated from the live contract when v2 ships.

Agent API v2 Reference

Base URL: https://agent-api.degov.ai

Machine-readable contract: /openapi/agent-v2.json (when available).
Envelope, pagination, readiness, errors, timestamps: see Concepts.
Tiers: free (no auth), standard and plus (x402 or partner token).

Common envelope

Successful response:

{
  "data": { },
  "meta": {
    "requestId": "req-01J...",
    "generatedAt": "2026-08-05T07:30:00.000Z",
    "dataAsOf": "2026-08-05T07:29:30.000Z",
    "readiness": { "status": "ready" },
    "page": { "limit": 25, "hasMore": false }
  }
}

Error response:

{
  "error": { "code": "NOT_FOUND", "message": "Proposal was not found", "details": {} },
  "meta": { "requestId": "req-01J..." }
}

Metadata

`GET /v2/meta/pricing` — free

Live prices for every route. Input: none.

{
  "data": {
    "token": "USDC",
    "network": "eip155:8453",
    "routes": [
      { "routeId": "v2.proposals.list", "method": "GET", "path": "/v2/proposals", "tier": "standard", "paid": true, "price": "0.005" }
    ]
  }
}

`GET /v2/meta/data-status` — free

Global or per-DAO pipeline state. Input: daoId?.

{
  "data": {
    "scope": "dao",
    "daoId": "ens-dao",
    "latestSuccessfulSync": { "governanceAt": "2026-08-05T07:29:00.000Z", "forumAt": "2026-08-05T07:10:00.000Z" },
    "coverageStatus": "complete",
    "voteCoverageStatus": "ready"
  }
}

Unknown daoId → 404 NOT_FOUND.

DAOs

`GET /v2/daos` — free

Discover covered DAOs and their coverage. Query: hasVoteData?, hasForumData?, coverageStatus?, cursor?, limit (1–100, default 50).

{
  "data": [
    {
      "daoId": "ens-dao",
      "name": "ENS",
      "hasVoteData": true,
      "hasForumData": true,
      "coverageStatus": "complete",
      "voteCoverageStatus": "ready",
      "proposalCounts": { "total": 412, "active": 3 },
      "latestActivity": { "proposalAt": "2026-08-05T07:20:00.000Z", "voteAt": "2026-08-04T18:00:00.000Z", "forumAt": null }
    }
  ]
}

`GET /v2/daos/:daoId` — free

One DAO's governance scale, outcomes, and participation. Input: path daoId.

{
  "data": {
    "daoId": "ens-dao",
    "name": "ENS",
    "coverageStatus": "complete",
    "voteCoverageStatus": "ready",
    "proposalCounts": { "total": 412, "active": 3, "pending": 5, "closed": 404 },
    "outcomes": { "passed": 300, "failed": 60, "executed": 180, "canceled": 20, "unknown": 24 },
    "participation": { "uniqueVoters": "12000", "totalVotes": "180000", "totalVotingPower": "987654321.123456789012345678" },
    "sourceTypes": ["snapshot", "forum"]
  }
}

Unknown daoId → 404 NOT_FOUND.

`GET /v2/daos/:daoId/timeline` — plus

Monthly proposal/vote trends. Query: metric (proposals_created | votes_cast, required), fromMonth?, toMonth? (YYYY-MM, max 240 months).

{
  "data": {
    "daoId": "ens-dao",
    "metric": "votes_cast",
    "buckets": [ { "month": "2026-07", "value": "345" } ]
  }
}

Proposals

`GET /v2/proposals` — standard

Filterable proposal directory. Query: daoId?, provider?, proposerId?, lifecycleStatus? (CSV), outcome? (CSV), timeField (createdAt|startAt|endAt|updatedAt), from?/to? (max 365 days), sort (updatedDesc|createdDesc|endingSoon), cursor?, limit (1–100, default 25).

{
  "data": [
    {
      "proposalKey": "p1_eyJkYW9JZCI6ImVucy1kYW8iLCJwcm92aWRlciI6InNuYXBzaG90IiwiZXh0ZXJuYWxJZCI6ImFiYzEyMyJ9",
      "identity": { "daoId": "ens-dao", "provider": "snapshot", "externalId": "abc123" },
      "title": "Increase Protocol Budget",
      "sourceUrl": "https://...",
      "lifecycleStatus": "active",
      "outcome": "unknown",
      "endAt": "2026-08-07T12:00:00.000Z",
      "coverageStatus": "complete"
    }
  ]
}

No bodies, no votes, no evidence in list items.

`GET /v2/proposals/resolve` — standard

Resolve an external URL/title/external id to canonical keys. Query: exactly one of url | title | externalId, optional daoId/provider disambiguation, limit (1–20, default 5).

{
  "data": {
    "candidates": [
      {
        "proposalKey": "p1_...",
        "identity": { "daoId": "ens-dao", "provider": "snapshot", "externalId": "abc123" },
        "title": "Increase Protocol Budget",
        "match": { "type": "url_exact", "matchedFields": ["sourceUrl"] }
      }
    ]
  }
}

match.type ∈ url_exact | external_id_exact | title_exact | title_contains. No fabricated confidence scores. No matches → empty candidates (200).

`GET /v2/proposals/:proposalKey` — plus

Normalized proposal detail and body. Input: path proposalKey only.

{
  "data": {
    "proposalKey": "p1_...",
    "identity": { "daoId": "ens-dao", "provider": "snapshot", "externalId": "abc123" },
    "title": "Increase Protocol Budget",
    "bodyText": "Full normalized proposal body...",
    "proposerId": "0x...",
    "sourceUrl": "https://...",
    "discussionUrl": "https://...",
    "lifecycleStatus": "active",
    "outcome": "unknown",
    "choices": [ { "key": "1", "label": "For" } ],
    "quorumRaw": "100K",
    "startAt": "2026-08-01T12:00:00.000Z",
    "endAt": "2026-08-07T12:00:00.000Z",
    "related": {
      "voteSummary": "/v2/proposals/p1_.../votes/summary",
      "votes": "/v2/proposals/p1_.../votes",
      "evidence": "/v2/proposals/p1_.../evidence"
    }
  }
}

Malformed key → 400 VALIDATION_ERROR; unknown proposal → 404 NOT_FOUND.

`GET /v2/proposals/:proposalKey/votes/summary` — plus

Vote result, choice totals, quorum. Input: path proposalKey only.

{
  "data": {
    "proposal": { "proposalKey": "p1_...", "title": "...", "outcome": "passed" },
    "totals": { "votes": "81234", "uniqueVoters": "4521", "votingPower": "1234567.890123456789012345" },
    "quorum": { "raw": "100K", "progress": "0.7342", "reached": true },
    "choices": [ { "key": "1", "label": "For", "votes": "60123", "votingPower": "812345.67" } ],
    "coverageStatus": "complete"
  }
}

Readiness not ready → totals/quorum null, empty choices (200, not 404).

`GET /v2/proposals/:proposalKey/votes` — plus

Per-voter ballot rows, latest ballot only. Query: order (power|time, default power), cursor?, limit (1–500, default 100).

{
  "data": [
    {
      "voteId": "123456",
      "voterIdentity": "0xabc...",
      "voterAddress": "0xabc...",
      "choiceKey": "1",
      "choice": { "label": "For" },
      "votingPower": "12.340000000000000000",
      "votedAt": "2026-08-03T10:00:00.000Z",
      "transactionHash": "0x..."
    }
  ]
}

Recast (superseded) ballots are never exposed.

`GET /v2/proposals/:proposalKey/evidence` — plus

Citation/audit evidence: provenance, intelligence, quality flags, warnings. Input: path proposalKey only. Not a duplicate of detail; use it for research/audit answers.

{
  "data": {
    "proposal": { "proposalKey": "p1_...", "title": "Increase Protocol Budget", "sourceUrl": "https://..." },
    "provenance": [
      { "field": "title", "source": "serving.proposals", "provider": "snapshot", "observedAt": "2026-08-05T07:20:00.000Z" }
    ],
    "intelligence": { "status": "available", "artifactVersion": "proposal_dossier_v1", "generatedAt": "...", "dossier": {}, "sourceRefs": [], "warnings": [] },
    "qualityFlags": ["registry_body_available"],
    "warnings": []
  }
}

Forum

`GET /v2/forum-topics` — standard

Filterable forum topic directory. Query: daoId?, provider?, governanceRelated?, updatedFrom?/updatedTo?, minReplies?, sort (updatedDesc|createdDesc|repliesDesc), cursor?, limit (1–100, default 25).

{
  "data": [
    {
      "topicKey": "t1_eyJkYW9JZCI6ImVuc...",
      "identity": { "daoId": "ens-dao", "provider": "discourse", "externalId": "1234" },
      "title": "Discussion: treasury diversification",
      "summary": "Community thread on treasury allocation...",
      "url": "https://forum.ens.domains/t/...",
      "author": "0x...",
      "category": "Treasury",
      "tags": ["treasury"],
      "relevanceScore": 87,
      "replies": "34",
      "posts": "41",
      "likes": "120",
      "views": "3200",
      "createdAt": "2026-07-20T09:00:00.000Z",
      "updatedAt": "2026-08-04T18:00:00.000Z"
    }
  ]
}

`GET /v2/forum-topics/:topicKey` — plus

One forum topic's normalized detail. Input: path topicKey only.

Feeds

`GET /v2/events` — standard

Raw governance lifecycle event timeline. Query: daoId?, from/to (required, max 90 days), eventType? (CSV), timeBasis? (eventTime|discoveredTime), importanceMin?, cursor?, limit (1–200, default 100).

{
  "data": [
    {
      "eventId": "evt-...",
      "eventType": "proposal_created",
      "eventTimeMs": "2026-08-05T07:00:00.000Z",
      "eventTimeConfidence": "exact",
      "daoId": "ens-dao",
      "daoName": "ENS",
      "itemType": "proposal",
      "proposalKey": "p1_...",
      "title": "Increase Protocol Budget",
      "url": "https://...",
      "importanceScore": 70
    }
  ]
}

`GET /v2/signals` — standard

Curated, deduplicated, scored signals. Query: daoId?, from/to (required, max 90 days), signalType?, priorityMin?, surface (agent|atlas_latest|atlas_priority|telegram_realtime), sort?, cursor?, limit (1–100, default 50).

{
  "data": [
    {
      "signalId": "sig-...",
      "signalType": "proposal_deadline_reminder",
      "priority": { "score": 92, "band": "high" },
      "actionability": "deadline",
      "daoId": "ens-dao",
      "title": "Increase Protocol Budget",
      "summary": "Voting ends in under 48 hours",
      "sourceUrl": "https://...",
      "deadlineAtMs": "2026-08-07T12:00:00.000Z",
      "severity": "high",
      "proposalKey": "p1_...",
      "evidence": { }
    }
  ]
}

Events vs Signals

	`/v2/events`	`/v2/signals`
Answers	"What happened in this window?"	"What should I pay attention to?"
Shape	Raw event timeline, `eventType` per row	Deduplicated, scored, surface-specific
Uses	Timeline analysis, deadline math, "today" summaries	Alerting, digests, priority triage

Voters

`GET /v2/daos/:daoId/voters` — plus

DAO voting-power ranking. Query: cursor?, limit (1–100, default 25).

{
  "data": [
    {
      "rank": 1,
      "voterIdentity": "0xabc...",
      "voterAddress": "0xabc...",
      "totalVotingPower": "12345.67",
      "voteCount": "89",
      "proposalCount": "40"
    }
  ]
}

`GET /v2/voters/:voterIdentity` — plus

Cross-DAO voter profile. Input: path voterIdentity. 0x identities are lower-case normalized.

{
  "data": {
    "voterIdentity": "0xabc...",
    "voterAddress": "0xabc...",
    "daoCount": "3",
    "voteCount": "145",
    "proposalCount": "77",
    "totalVotingPower": "54321.10",
    "daos": [
      { "daoId": "ens-dao", "voteCount": "89", "proposalCount": "40", "totalVotingPower": "12345.67", "firstVoteAt": "2024-01-10T00:00:00.000Z", "lastVoteAt": "2026-08-03T10:00:00.000Z" }
    ]
  }
}

Unknown identity → 404 NOT_FOUND.

`GET /v2/voters/:voterIdentity/votes` — plus

Voter vote history. Query: daoId?, from?/to?, cursor?, limit (1–100, default 50).

{
  "data": [
    {
      "proposal": { "proposalKey": "p1_...", "title": "Increase Protocol Budget" },
      "choiceKey": "1",
      "votingPower": "12.34",
      "votedAt": "2026-08-03T10:00:00.000Z",
      "transactionHash": "0x..."
    }
  ]
}

v2 does not provide

No /v2/brief, /v2/activity, or generic /v2/items — compose the fine-grained endpoints instead.
No includeVotes / includeLive / includeIntelligence flags — use the dedicated endpoints.
No internal or ops endpoints are part of the public contract.

Last update: August 5, 2026
Created: August 5, 2026

Agent API v2 Reference

Common envelope

Metadata

GET /v2/meta/pricing — free

GET /v2/meta/data-status — free

DAOs

GET /v2/daos — free

GET /v2/daos/:daoId — free

GET /v2/daos/:daoId/timeline — plus

Proposals

GET /v2/proposals — standard

GET /v2/proposals/resolve — standard

GET /v2/proposals/:proposalKey — plus

GET /v2/proposals/:proposalKey/votes/summary — plus

GET /v2/proposals/:proposalKey/votes — plus

GET /v2/proposals/:proposalKey/evidence — plus