Convo API

API Details

Node API Endpoint (Primary) : https://theconvo.space/api/ (opens in a new tab)
View More Nodes at Node Tests
API Playground : https://playground.theconvo.space/ (opens in a new tab)
OpenAPI 3 Config : https://github.com/anudit/convodocs/tree/main/public/Convo.yaml/ (opens in a new tab)

Use apikey=apikey added as a query parameter or a x-api-key header for all requests. Returns a 401 Unauthorized Error otherwise. Breaking changes might be introduced to the endpoints as Convo is still in Early-access. All such changes will be informed well in advance.

User Authentication

Authenticating a User

Auth Route : /auth

Full Endpoint : https://theconvo.space/api/auth?apikey=apikey

ℹ️

You do not require an auth token for read-only GET requests. Each authentication token is valid for a maximum of 1 day only.

Send a POST request to the endpoint with the following example body,

{
  "signerAddress":"54e94c146f0c3e4321f7deefd8ec5e3d4c715a9e6d805c5e10aeade18dfa30b8",
  "signature":"a9f793d84cb90a03566d1f2ba05a7f3fa43b9d33c5be4ddbb943a3754cb7fd49fa4620d4827349a45948243f660db4547436cb2ad3b6549263ce01fcd63b200f",
  "accountId":"convo.testnet",
  "timestamp":1630751987917,
  "chain":"near"
}

Body Param	Description
`signerAddress`	The address of the account to authenticate.
`signature`	NEAR signature of `data` using the above `signerAddress`
`accountId`	Your NEAR Account Id
`timestamp`	Timestamp of the instant the signature request was fired.
`chain`	`near`

data Format = I allow this site to access my data on The Convo Space using the account <accountId>. Timestamp:<timestamp>

Example, data = 'I allow this site to access my data on The Convo Space using the account convo.testnet. Timestamp:1623254904621'

// Sample signature generation code using near-api-js.js
let accountId = wallet.getAccountId();
const timestamp = Date.now();
const tokenMessage = new TextEncoder().encode(`I allow this site to access my data on The Convo Space using the account ${accountId}. Timestamp:${timestamp}`);
const signatureData = await wallet.account().connection.signer.signMessage(tokenMessage, accountId, 'testnet');
 
let authBody = {
  "signature": Buffer.from(signatureData.signature).toString('hex'),
  "signerAddress": Buffer.from(signatureData.publicKey.data).toString('hex'),
  "accountId": accountId,
  "timestamp": timestamp,
  "chain": "near"
};

Response

{
  "success":true,
  "message":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiMHg3MDdhQzM5MzdBOUIzMUMyMjVEOEMyNDBGNTkxN0JlOTdjYWI5RjIwIiwiaWF0IjoxNjE3NzY1MzEzLCJleHAiOjE2MTc4NTE3MTN9.6sb6lnC5RIy_JWidsYyGYrHE2fGvajBEaVh5ybwsvqE"
}

Response Param	Description
`success`	`Boolean`, status of the request.
`message`	Contains either the JWT auth token if `success==true` or an error message `success==false`

EIP-4361 : Sign In with Ethereum

Auth Route : /authV2

Full Endpoint : https://theconvo.space/api/authV2?apikey=apikey

ℹ️

You do not require an auth token for read-only GET requests. Each authentication token is valid for a maximum of 1 day only.

First, Let's generate the SIWE compatible message,

Quick Links,

SIWE Spec : EIP-4361 (opens in a new tab)
Message Generation Library : @theconvospace/sdk

Eg,

const convoInstance = new Convo("apikey");
// Variable `message` will contain the SIWE compatible message ready for Signing.
let message = convoInstance.auth.getSignatureDataV2('https://theconvo.space/', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 1);

Second, Let's Sign the message.

// Sample signature generation code using ethers.js
const convoInstance = new Convo("apikey");
let signer = await provider.getSigner();
let signerAddress = await signer.getAddress();
 
let message = convoInstance.auth.getSignatureDataV2('https://theconvo.space/', signerAddress, 1);
 
let signature = await provider.send('personal_sign',[ ethers.utils.hexlify(ethers.utils.toUtf8Bytes(message)), signerAddress.toLowerCase() ]);
 
let authV2Body = {
  "message": message,
  "signature": signature,
  "chain": "ethereum"
};

Third, Send a POST request to the endpoint with the following example body,

{
  "message": "theconvo.space wants you to sign in with your Ethereum account:\0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\n\nI allow this site to access my data on The Convo Space.\n\nURI: https://theconvo.space/\nVersion: 1\nChain ID: 0\nNonce: 5BacWphMVDD9EKIPd\nIssued At: 2021-12-20T16:32:00.746Z\nExpiration Time: 2021-12-20T16:32:00.746Z\nResources:\n- https://theconvo.space/privacy-policy",
  "signature": "0xf9c18aaf6fc61620494eda243f2af28d2835132ab97a41e273fbe43eb452e41600c30f0e02ae55e14b2a4ee9b9f4c8bcd9463a03bc517ccb95e4ecd32f37bbcc1c",
  "chain":"ethereum"
}

Body Param	Description
`message`	The Unsigned raw SIWE message
`signature`	Ethereum signature of `message` using the user's address
`chain`	`ethereum`

Response

{
  "success":true,
  "message":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiMHg3MDdhQzM5MzdBOUIzMUMyMjVEOEMyNDBGNTkxN0JlOTdjYWI5RjIwIiwiaWF0IjoxNjE3NzY1MzEzLCJleHAiOjE2MTc4NTE3MTN9.6sb6lnC5RIy_JWidsYyGYrHE2fGvajBEaVh5ybwsvqE"
}

Response Param	Description
`success`	`Boolean`, status of the request.
`message`	Contains either the JWT auth token if `success==true` or an error message `success==false`

Validating Authentication

Auth Route : /validateAuth

Full Endpoint : https://theconvo.space/api/validateAuth?apikey=apikey

Send a POST request to the endpoint with the following example body,

{
  "signerAddress":"convo.testnet",
  "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiY29udm8udGVzdG5ldCIsImNoYWluIjoibmVhciIsImlhdCI6MTYzMTM2NTA3MCwiZXhwIjoxNjMxNDUxNDcwfQ.XFv2IS1ZBrSgJUnY0B334iiTt5gL1pq-vgdYaKh1dk8"
}

Body Param	Description
`signerAddress`	The NEAR accountId of user.
`token`	The JWT Authentication Token to validate.

Response

{
  "success":true,
  "message":"Valid Auth Token"
}

Response Param	Description
`success`	`Boolean`, status of the request.
`message`	If `success==true` then "Valid Auth Token" else returns the error message

Possible Error Messages,

200: Invalid Auth Token.
400: Internal JWT Auth Error Message.
400: signerAddress or token or timestamp is missing/invalid.
500: Internal Error.

Querying Data

ℹ️

URLs passed as query parameters must be URL encoded using encodeURIComponent()

Querying a Comment

By CommentId : /comment?commentId=fJPU8mZiQwVXV6K1xXlw

Querying Comments

By ThreadId : /comments?threadId=fJPU8mZiQwVXV6K1xXlw
By URL : /comments?url=https%3A%2F%2Fgoogle.com%2F
By ThreadId and URL : /comments?threadId=fJPU8mZiQwVXV6K1xXlw&url=https%3A%2F%2Fdeepdao.io%2F
You can filter by author, tag1, tag2, tag3, replyTo also.
You can pagintate by using page and pageSize query params.
You can reorder the comments fetching the latest first using latestFirst query param.
You can generate a list of just address for an airdrop by setting airdrop=true in rhe query params.

Querying Threads

/threads endpoint gets the metadata for any ThreadId. This will soon be the place for adding permissions to conversations like moderators, url & token gating and many more.

All Threads: /threads
By ThreadId : /threads?threadId=fJPU8mZiQwVXV6K1xXlw
By URL : /threads?url=https%3A%2F%2Fgoogle.com%2F

Response Example

{
  "_id": "01f71qnhfzt5zdf17k5xk5cz4m",
  "_mod": 1627106452229067000,
  "author": "0xa97276772e9A8D5408421D60c2749C68c2e2fC3a",
  "createdOn": "1622482263131",
  "downvotes": [],
  "metadata": {},
  "tag1": "",
  "tag2": "",
  "text": "HI",
  "tid": "KIGZUnR4RzXDFheXoOwo",
  "upvotes": [],
  "url": "https://theconvo.space/",
  "authorENS": "name.eth"
},

You can pagintate by using page and pageSize query params.

You can reorder the comments fetching the latest first using latestFirst query param.

Creating a comment

Route : /comments

Full Endpoint : https://theconvo.space/api/comments?apikey=apikey

Send a POST request to the endpoint with the following request schema,

{
  'token': <JWT-Auth-token>,
  'signerAddress': <ethereum-address-of-author>,
  'comment': <plaintext-comment>,
  'threadId': <threadId-of-the-thread>,
  'url': encodeURIComponent(<url-of-the-page>),
}

Response

{
  '_id': <unique-id-of-comment>
  'createdOn': <timestamp>,
  'author': <same-as-signerAddress>,
  'text': <same-as-comment>,
  'url': <same-as-url>,
  'tid': <same-as-threadId>,
}

You can add a replyTo body parameter with a valid comment _id value to set that comment as a reply to any specific comment.

Possible Response Error Messages,

400: Invalid/Incomplete params
503: Invalid Auth
500: Internal Error.

Deleting a comment

Single Comment

Route : /comments

Full Endpoint : https://theconvo.space/api/comments?apikey=apikey

Send a DELETE request to the endpoint with the following request schema,

{
  'token': <JWT-Auth-token>,
  'signerAddress': <address>,
  'commentId': <unique-id-of-comment>
}

Response

{
  'success': true,
}

Possible Response Error Messages,

400: Invalid/Incomplete params
503: Invalid Auth
500: Internal Error.

Nuke all Data

Route : /comments

Full Endpoint : https://theconvo.space/api/comments?apikey=apikey

Send a DELETE request to the endpoint with the following request schema,

{
  'token': <JWT-Auth-token>,
  'signerAddress': <address>,
  'deleteAll': true,
}

Response

{
  'success': true,
}

Possible Response Error Messages,

400: Invalid/Incomplete params
503: Invalid Auth
500: Internal Error.

Updating a comment

Route : /comments

Full Endpoint : https://theconvo.space/api/comments?apikey=apikey

Send a PATCH request to the endpoint with the following request schema,

{
  'token': <JWT-Auth-token>,
  'signerAddress': <address>,
  'commentId': <unique-id-of-comment>,
  'comment': comment>
}

Response

{
  'success': true,
}

Possible Response Error Messages,

400: Invalid/Incomplete params
503: Invalid Auth
500: Internal Error.

Likes and Dislikes

Route : /vote

Full Endpoint : https://theconvo.space/api/vote?apikey=apikey

Send a POST request to the endpoint with the following body schema,

{
  "signerAddress": "<user-address>",
  "token": "<JWT-Auth-Token>",
  "commentId":"<Comment-Id>",
  "type": "<Type-of-Vote>"
}

The type field supports the folowing values,

toggleUpvote
toggleDownvote

Eg,

{
    "signerAddress": "0x707aC3937A9B31C225D8C240F5917Be97cab9F20",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiMHg3MDdhQzM5MzdBOUIzMUMyMjVEOEMyNDBGNTkxN0JlOTdjYWI5RjIwIiwiaWF0IjoxNjI3MTA3NjY5LCJleHAiOjE2MjcxOTQwNjl9.VJEViNmVxfxzY8dYTV_7r5SGrln6OcXUh50R3yePz1M",
    "commentId":"01faymzw18ev9vgrq2qarkg9xb",
    "type": "toggleUpvote"
}

Response

{
  'success': true,
}

Possible Response Error Messages,

400: Invalid/Incomplete params
404: Invalid Request Method
503: Invalid Auth
500: Internal Error.

Comments

Omnid RPC Omnid