Skip to content

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 ParamDescription
signerAddressThe address of the account to authenticate.
signatureEthereum signature of data using the above signerAddress
timestampTimestamp of the instant the signature request was fired.
chainethereum

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 ParamDescription
signerAddressThe address of the account to authenticate.
tokenThe 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