API & Resources
Polkassembly API Documentation
This document provides information about the Polkassembly API endpoints that are available for third-party developers. All requests should include the appropriate headers for authentication and network specification.
Base URL
The base URL for the Polkassembly API depends on the network you are targeting:
- Polkadot:
https://polkadot.polkassembly.io/
- Kusama:
https://kusama.polkassembly.io/
- Moonbeam:
https://moonbeam.polkassembly.io/
- Moonriver:
https://moonriver.polkassembly.io/
Required Headers
All API requests require the following headers:
x-network
: The network you are targeting (e.g., “polkadot”, “kusama”, “moonbeam”, “moonriver”)Content-Type
:application/json
For authenticated requests, you may also need:
Authorization
:Bearer <jwt_token>
API Endpoints
Posts
Get On-Chain Post
Retrieves information about an on-chain proposal.
URL: /v1/posts/on-chain-post
Method: GET
Query Parameters:
postId
(required): The ID of the postproposalType
(required): The type of proposal (e.g., “referendums_v2”, “treasury_proposals”, “bounties”)
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/posts/on-chain-post?postId=123&proposalType=referendums_v2",
{
headers: {
"x-network": "polkadot"
}
}
);
Comments
Get Comments by Timeline
Retrieves comments for a post organized by timeline/history.
URL: /v1/posts/comments/getCommentsByTimeline
Method: POST
Request Body:
{
"postId": 123,
"proposalType": "referendums_v2"
}
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/posts/comments/getCommentsByTimeline",
{
method: "POST",
headers: {
"x-network": "polkadot",
"Content-Type": "application/json"
},
body: JSON.stringify({
postId: 123,
proposalType: "referendums_v2"
})
}
);
Votes
Get Total Votes
Retrieves the total votes for a specific proposal.
URL: /v1/votes/total
Method: POST
Request Body:
{
"postId": 123,
"voteType": "referendum"
}
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/votes/total",
{
method: "POST",
headers: {
"x-network": "polkadot",
"Content-Type": "application/json"
},
body: JSON.stringify({
postId: 123,
voteType: "referendum"
})
}
);
Get Aye/Nay Vote Count
Retrieves the counts of aye and nay votes for a proposal.
URL: /v1/votes/ayeNayTotalCount
Method: POST
Request Body:
{
"postId": 123,
"voteType": "referendum"
}
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/votes/ayeNayTotalCount",
{
method: "POST",
headers: {
"x-network": "polkadot",
"Content-Type": "application/json"
},
body: JSON.stringify({
postId: 123,
voteType: "referendum"
})
}
);
Get Votes History
Retrieves voting history for a proposal.
URL: /v1/votes/history
Method: POST
Request Body:
{
"postId": 123,
"voteType": "referendum"
}
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/votes/history",
{
method: "POST",
headers: {
"x-network": "polkadot",
"Content-Type": "application/json"
},
body: JSON.stringify({
postId: 123,
voteType: "referendum"
})
}
);
User Data
Get User Activities
Retrieves activities for a specific user.
URL: /v1/users/user-activities
Method: POST
Request Body:
{
"address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
}
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/users/user-activities",
{
method: "POST",
headers: {
"x-network": "polkadot",
"Content-Type": "application/json"
},
body: JSON.stringify({
address: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
})
}
);
Check Username Existence
Checks if a username is already taken.
URL: /v1/users/username-exist
Method: POST
Request Body:
{
"username": "exampleUser"
}
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/users/username-exist",
{
method: "POST",
headers: {
"x-network": "polkadot",
"Content-Type": "application/json"
},
body: JSON.stringify({
username: "exampleUser"
})
}
);
Delegations
Get Delegation Vote Count and Power
Retrieves information about delegation votes and their voting power.
URL: /v1/votes/delegationVoteCountAndPower
Method: POST
Request Body:
{
"postId": 123,
"voteType": "referendum"
}
Example Request:
const response = await fetch(
"https://polkadot.polkassembly.io/api/v1/votes/delegationVoteCountAndPower",
{
method: "POST",
headers: {
"x-network": "polkadot",
"Content-Type": "application/json"
},
body: JSON.stringify({
postId: 123,
voteType: "referendum"
})
}
);
Response Format
All API responses follow a standard format:
{
"data": {
// The requested data
},
"status": 200, // HTTP status code
"error": "" // Empty string if no error, otherwise contains error message
}
Error Handling
When an error occurs, the API will return a response with an appropriate HTTP status code and an error message:
{
"error": "Error message describing what went wrong"
}
Common error status codes:
400
: Bad Request - The request was malformed or missing required parameters401
: Unauthorized - Authentication is required or the provided credentials are invalid403
: Forbidden - The authenticated user does not have permission to access the requested resource404
: Not Found - The requested resource does not exist500
: Internal Server Error - An unexpected error occurred on the server
API Usage Limitations
Be mindful of rate limits when using the Polkassembly API. Excessive requests may lead to temporary IP blocking. For high-volume applications, please contact the Polkassembly team.
Further Assistance
For further assistance or questions about the API, please contact the Polkassembly team through their official channels.
Updated API Documentation (After 16 March’23) Documentation Link
Resources​
-
Governance Demo - Dr. Gavin Wood presents the initial governance structure for Polkadot. (Video)