{ "openapi": "3.1.0", "info": { "title": "PubFi DeGov Gateway API", "version": "2026-05-22", "summary": "OpenAPI specification for accessing DeGov through the PubFi gateway.", "description": "This specification describes the PubFi gateway routes for DeGov. Clients authenticate with a PubFi API key, while PubFi injects the upstream x-degov-api-token server-side. The DeGov network segment is fixed to `global`." }, "servers": [ { "url": "https://pubfi.ai", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local development" } ], "security": [ { "bearerAuth": [] }, { "pubfiApiKeyHeader": [] } ], "paths": { "/api/gateway/degov/global/health": { "get": { "operationId": "degovHealth", "summary": "Health check", "description": "Returns the upstream DeGov health status through the PubFi gateway.", "tags": [ "DeGov" ], "responses": { "200": { "description": "Gateway success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewaySuccessHealth" } } } }, "default": { "$ref": "#/components/responses/GatewayError" } } } }, "/api/gateway/degov/global/v1/meta/pricing": { "get": { "operationId": "degovPricing", "summary": "Read DeGov pricing metadata", "description": "Returns DeGov x402 pricing metadata through the PubFi gateway.", "tags": [ "DeGov" ], "responses": { "200": { "description": "Gateway success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewaySuccessPricing" } } } }, "default": { "$ref": "#/components/responses/GatewayError" } } } }, "/api/gateway/degov/global/v1/daos": { "get": { "operationId": "degovListDaos", "summary": "List covered DAOs", "description": "Lists covered DAOs and freshness metadata.", "tags": [ "DeGov" ], "responses": { "200": { "description": "Gateway success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewaySuccessDaoList" } } } }, "default": { "$ref": "#/components/responses/GatewayError" } } } }, "/api/gateway/degov/global/v1/activity": { "get": { "operationId": "degovActivity", "summary": "Read recent activity", "description": "Returns recent cross-DAO or single-DAO activity, including proposals and forum topics.", "tags": [ "DeGov" ], "parameters": [ { "name": "daoId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional DAO identifier to scope activity to one DAO." }, { "name": "governanceOnly", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Whether to filter for governance-related items only." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Lookback window in hours." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Maximum number of items to return." }, { "name": "kinds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated item kinds, for example `proposal,forum_topic`." } ], "responses": { "200": { "description": "Gateway success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewaySuccessActivity" } } } }, "default": { "$ref": "#/components/responses/GatewayError" } } } }, "/api/gateway/degov/global/v1/system/freshness": { "get": { "operationId": "degovSystemFreshness", "summary": "Read system freshness", "description": "Returns overall ingestion freshness and system-level dataset counts.", "tags": [ "DeGov" ], "responses": { "200": { "description": "Gateway success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewaySuccessSystemFreshness" } } } }, "default": { "$ref": "#/components/responses/GatewayError" } } } }, "/api/gateway/degov/global/v1/daos/{daoId}/brief": { "get": { "operationId": "degovDaoBrief", "summary": "Read DAO brief", "description": "Returns a compact DAO summary with sync status and recent highlights.", "tags": [ "DeGov" ], "parameters": [ { "name": "daoId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DAO identifier, for example `aavedao-eth`." }, { "name": "activityLimit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Maximum number of highlighted activity items to return." } ], "responses": { "200": { "description": "Gateway success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewaySuccessDaoBrief" } } } }, "default": { "$ref": "#/components/responses/GatewayError" } } } }, "/api/gateway/degov/global/v1/items/{kind}/{externalId}": { "get": { "operationId": "degovItemDetail", "summary": "Read item detail", "description": "Returns detailed information for one proposal or forum topic.", "tags": [ "DeGov" ], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "proposal", "forum_topic" ] }, "description": "Item kind." }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Upstream item identifier." } ], "responses": { "200": { "description": "Gateway success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewaySuccessItemDetail" } } } }, "default": { "$ref": "#/components/responses/GatewayError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "PubFi API Key", "description": "Send `Authorization: Bearer pf_sk_live_...`." }, "pubfiApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-PubFi-Api-Key", "description": "Alternative to bearer auth." } }, "responses": { "GatewayError": { "description": "Gateway error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorEnvelope" } } } } }, "schemas": { "GatewayMeta": { "type": "object", "additionalProperties": false, "required": [ "requestId", "provider", "network", "endpoint", "method", "timestamp", "upstream" ], "properties": { "requestId": { "type": "string" }, "provider": { "type": "string", "const": "degov" }, "network": { "type": "string", "const": "global" }, "endpoint": { "type": "string" }, "method": { "type": "string", "enum": [ "GET" ] }, "timestamp": { "type": "string", "format": "date-time" }, "upstream": { "$ref": "#/components/schemas/UpstreamMeta" } } }, "UpstreamMeta": { "type": "object", "additionalProperties": false, "required": [ "status", "latencyMs", "rateLimit" ], "properties": { "status": { "type": "integer" }, "latencyMs": { "type": "integer" }, "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } }, "RateLimit": { "type": "object", "additionalProperties": false, "required": [ "limit", "remaining", "reset", "retryAfter" ], "properties": { "limit": { "type": [ "string", "null" ] }, "remaining": { "type": [ "string", "null" ] }, "reset": { "type": [ "string", "null" ] }, "retryAfter": { "type": [ "string", "null" ] } } }, "GatewayErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "ok", "error", "meta" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "$ref": "#/components/schemas/GatewayError" }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "GatewayError": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "details", "docsUrl" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "docsUrl": { "type": [ "string", "null" ] } } }, "DeGovRequestFreshness": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "dataAsOf", "cacheStatus" ], "properties": { "generatedAt": { "type": "integer" }, "dataAsOf": { "type": "integer" }, "cacheStatus": { "type": "string" } } }, "DaoReference": { "type": "object", "additionalProperties": false, "required": [ "daoId", "daoName" ], "properties": { "daoId": { "type": "string" }, "daoName": { "type": "string" } } }, "EvidenceReference": { "type": "object", "additionalProperties": false, "required": [ "kind", "externalId" ], "properties": { "kind": { "type": "string" }, "externalId": { "type": "string" } } }, "ActivityTimestamps": { "type": "object", "additionalProperties": false, "required": [ "createdAt", "updatedAt", "startAt", "endAt", "lastSeenAt" ], "properties": { "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" }, "startAt": { "type": [ "integer", "null" ] }, "endAt": { "type": [ "integer", "null" ] }, "lastSeenAt": { "type": "integer" } } }, "ActivityItem": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "dao", "title", "summary", "whyRelevant", "sourceUrl", "discussionUrl", "status", "isGovernanceRelated", "timestamps", "evidenceRef" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "dao": { "$ref": "#/components/schemas/DaoReference" }, "title": { "type": "string" }, "summary": { "type": "string" }, "whyRelevant": { "type": "string" }, "sourceUrl": { "type": "string" }, "discussionUrl": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "isGovernanceRelated": { "type": "boolean" }, "timestamps": { "$ref": "#/components/schemas/ActivityTimestamps" }, "evidenceRef": { "$ref": "#/components/schemas/EvidenceReference" } } }, "GatewaySuccessHealth": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "ok", "service" ], "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "GatewaySuccessPricing": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/PricingPayload" }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "PricingPayload": { "type": "object", "additionalProperties": false, "required": [ "request", "pricing" ], "properties": { "request": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string" } } }, "pricing": { "type": "object", "additionalProperties": false, "required": [ "token", "network", "entries" ], "properties": { "token": { "type": "string" }, "network": { "type": "string" }, "entries": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PricingEntry" } } } } } }, "PricingEntry": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "method", "path", "price", "token", "network", "paid" ], "properties": { "endpoint": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "price": { "type": [ "string", "null" ] }, "token": { "type": "string" }, "network": { "type": "string" }, "paid": { "type": "boolean" } } }, "GatewaySuccessDaoList": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/DaoListPayload" }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "DaoListPayload": { "type": "object", "additionalProperties": false, "required": [ "request", "freshness", "data" ], "properties": { "request": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string" } } }, "freshness": { "$ref": "#/components/schemas/DeGovRequestFreshness" }, "data": { "type": "object", "additionalProperties": false, "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DaoListItem" } }, "total": { "type": "integer" } } } } }, "DaoListItem": { "type": "object", "additionalProperties": false, "required": [ "daoId", "daoName", "sourceType", "sourceRef", "sourceEndpoint", "forumUrl", "hasForum", "freshness" ], "properties": { "daoId": { "type": "string" }, "daoName": { "type": "string" }, "sourceType": { "type": "string" }, "sourceRef": { "type": "string" }, "sourceEndpoint": { "type": "string" }, "forumUrl": { "type": [ "string", "null" ] }, "hasForum": { "type": "boolean" }, "freshness": { "type": "object", "additionalProperties": false, "required": [ "governanceLastSuccessAt", "forumLastSuccessAt" ], "properties": { "governanceLastSuccessAt": { "type": [ "integer", "null" ] }, "forumLastSuccessAt": { "type": [ "integer", "null" ] } } } } }, "GatewaySuccessActivity": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/ActivityPayload" }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "ActivityPayload": { "type": "object", "additionalProperties": false, "required": [ "request", "freshness", "data" ], "properties": { "request": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "daoId", "governanceOnly", "hours", "limit", "kinds" ], "properties": { "endpoint": { "type": "string" }, "daoId": { "type": [ "string", "null" ] }, "governanceOnly": { "type": "boolean" }, "hours": { "type": "integer" }, "limit": { "type": "integer" }, "kinds": { "type": "array", "items": { "type": "string" } } } }, "freshness": { "$ref": "#/components/schemas/DeGovRequestFreshness" }, "data": { "type": "object", "additionalProperties": false, "required": [ "items", "total", "windowHours" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } }, "total": { "type": "integer" }, "windowHours": { "type": "integer" } } } } }, "GatewaySuccessSystemFreshness": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/SystemFreshnessPayload" }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "SystemFreshnessPayload": { "type": "object", "additionalProperties": false, "required": [ "request", "freshness", "data" ], "properties": { "request": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string" } } }, "freshness": { "$ref": "#/components/schemas/DeGovRequestFreshness" }, "data": { "type": "object", "additionalProperties": false, "required": [ "summary", "sources" ], "properties": { "summary": { "type": "object", "additionalProperties": false, "required": [ "daoCount", "proposalCount", "forumTopicCount", "governanceTopicCount", "failedSyncCount" ], "properties": { "daoCount": { "type": "integer" }, "proposalCount": { "type": "integer" }, "forumTopicCount": { "type": "integer" }, "governanceTopicCount": { "type": "integer" }, "failedSyncCount": { "type": "integer" } } }, "sources": { "type": "object", "additionalProperties": false, "required": [ "governance", "discourse" ], "properties": { "governance": { "type": "object", "additionalProperties": false, "required": [ "latestSuccessfulSyncAt" ], "properties": { "latestSuccessfulSyncAt": { "type": "integer" } } }, "discourse": { "type": "object", "additionalProperties": false, "required": [ "latestSuccessfulSyncAt" ], "properties": { "latestSuccessfulSyncAt": { "type": "integer" } } } } } } } } }, "GatewaySuccessDaoBrief": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/DaoBriefPayload" }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "DaoBriefPayload": { "type": "object", "additionalProperties": false, "required": [ "request", "freshness", "data" ], "properties": { "request": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "daoId", "activityLimit" ], "properties": { "endpoint": { "type": "string" }, "daoId": { "type": "string" }, "activityLimit": { "type": "integer" } } }, "freshness": { "$ref": "#/components/schemas/DeGovRequestFreshness" }, "data": { "type": "object", "additionalProperties": false, "required": [ "dao", "overview", "sync", "highlights" ], "properties": { "dao": { "type": "object", "additionalProperties": false, "required": [ "daoId", "daoName", "sourceType", "sourceRef", "sourceEndpoint", "forumUrl", "hasForum" ], "properties": { "daoId": { "type": "string" }, "daoName": { "type": "string" }, "sourceType": { "type": "string" }, "sourceRef": { "type": "string" }, "sourceEndpoint": { "type": "string" }, "forumUrl": { "type": [ "string", "null" ] }, "hasForum": { "type": "boolean" } } }, "overview": { "type": "object", "additionalProperties": false, "required": [ "proposalCount", "forumTopicCount" ], "properties": { "proposalCount": { "type": "integer" }, "forumTopicCount": { "type": "integer" } } }, "sync": { "type": "object", "additionalProperties": false, "required": [ "governanceLastSuccessAt", "forumLastSuccessAt", "overallStatus", "lastErrorMessage" ], "properties": { "governanceLastSuccessAt": { "type": [ "integer", "null" ] }, "forumLastSuccessAt": { "type": [ "integer", "null" ] }, "overallStatus": { "type": "string" }, "lastErrorMessage": { "type": [ "string", "null" ] } } }, "highlights": { "type": "object", "additionalProperties": false, "required": [ "proposals", "discussions" ], "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } }, "discussions": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } } } } } } } }, "GatewaySuccessItemDetail": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/ItemDetailPayload" }, "meta": { "$ref": "#/components/schemas/GatewayMeta" } } }, "ItemDetailPayload": { "type": "object", "additionalProperties": false, "required": [ "request", "freshness", "data" ], "properties": { "request": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "kind", "externalId" ], "properties": { "endpoint": { "type": "string" }, "kind": { "type": "string" }, "externalId": { "type": "string" } } }, "freshness": { "$ref": "#/components/schemas/DeGovRequestFreshness" }, "data": { "type": "object", "additionalProperties": false, "required": [ "item" ], "properties": { "item": { "type": "object", "additionalProperties": false, "required": [ "kind", "externalId", "dao", "title", "summary", "whyRelevant", "sourceUrl", "discussionUrl", "status", "timestamps", "cacheStatus", "live" ], "properties": { "kind": { "type": "string" }, "externalId": { "type": "string" }, "dao": { "$ref": "#/components/schemas/DaoReference" }, "title": { "type": "string" }, "summary": { "type": "string" }, "whyRelevant": { "type": "string" }, "sourceUrl": { "type": "string" }, "discussionUrl": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "timestamps": { "$ref": "#/components/schemas/ActivityTimestamps" }, "cacheStatus": { "type": "string" }, "live": { "type": "object", "additionalProperties": false, "required": [ "source", "daoId", "externalId", "title", "state", "created", "start", "end", "discussion", "link", "registryUrl" ], "properties": { "source": { "type": "string" }, "daoId": { "type": "string" }, "externalId": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" }, "created": { "type": "integer" }, "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] }, "discussion": { "type": [ "string", "null" ] }, "link": { "type": "string" }, "registryUrl": { "type": "string" } } } } } } } } } } } }