Convo API

API Details

Early-access API Endpoint : https://theconvo.space/api

API Playground : https://playground.theconvo.space

OpenAPI 3 Config : https://github.com/anudit/convodocs/tree/main/public/Convo.yaml

ℹī¸

Use apikey=CONVO added as a query parameter 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.

Step 1 - User Authentication

Authenticating a User

Auth Route : /auth

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

ℹī¸

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":"0x707aC3937A9B31C225D8C240F5917Be97cab9F20",
"signature":"0x76138b631abf63e1cced43cd19c4b8f417977b7fb929b15b38f2db8f70243a3d00739746911104e4244bcc12369cf34ab91ef21481a36fdd5e027ffd0ad145c11b",
"timestamp": 1623254904621,
"chain":"ethereum"
}
Body Param Description
signerAddress The address of the account to authenticate.
signature Ethereum signature of data using the above signerAddress
timestamp Timestamp of the instant the signature request was fired.
chain ethereum

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

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

// Sample signature generation code using ethers.js
let timestamp = Date.now();
let signer = await provider.getSigner();
let signerAddress = await signer.getAddress();
let data = `I allow this site to access my data on The Convo Space using the account ${signerAddress}. Timestamp:${timestamp}`;
let signature = await provider.send('personal_sign',[ ethers.utils.hexlify(ethers.utils.toUtf8Bytes(data)), signerAddress.toLowerCase() ]);
let authBody = {
"signature": signature,
"signerAddress": signerAddress,
"timestamp": timestamp,
"chain": "ethereum"
};

Response

{
"success":true,
"message":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiMHg3MDdhQzM5MzdBOUIzMUMyMjVEOEMyNDBGNTkxN0JlOTdjYWI5RjIwIiwiaWF0IjoxNjE3NzY1MzEzLCJleHAiOjE2MTc4NTE3MTN9.6sb6lnC5RIy_JWidsYyGYrHE2fGvajBEaVh5ybwsvqE"
}
Response ParamDescription
successBoolean, status of the request.
messageContains 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=CONVO

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

{
"signerAddress":"0x707aC3937A9B31C225D8C240F5917Be97cab9F20",
"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiMHg3MDdhQzM5MzdBOUIzMUMyMjVEOEMyNDBGNTkxN0JlOTdjYWI5RjIwIiwiaWF0IjoxNjE3NzY1MzEzLCJleHAiOjE2MTc4NTE3MTN9.6sb6lnC5RIy_JWidsYyGYrHE2fGvajBEaVh5ybwsvqE"
}
Body Param Description
signerAddress The address of the account to authenticate.
token The JWT Authentication Token to validate.

Response

{
"success":true,
"message":"Valid Auth Token"
}
Response ParamDescription
successBoolean, status of the request.
messageIf 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.

Step 2 - 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

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.

Step 3 - Creating a comment

Route : /comments

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

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.

Step 4 - Deleting a comment

Route : /comments

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

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

{
'token': <JWT-Auth-token>,
'commentId': <unique-id-of-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=CONVO

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