Skip to content
✨ Learn more about Convo Space & Omnid →
  • Docs
  • Convo API
  • API Docs

Convo API

API Details

ℹ️

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 ParamDescription
signerAddressThe address of the account to authenticate.
signatureNEAR signature of data using the above signerAddress
accountIdYour NEAR Account Id
timestampTimestamp of the instant the signature request was fired.
chainnear

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 ParamDescription
successBoolean, status of the request.
messageContains 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,

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 ParamDescription
messageThe Unsigned raw SIWE message
signatureEthereum signature of message using the user's address
chainethereum

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=apikey

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

{
  "signerAddress":"convo.testnet",
  "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiY29udm8udGVzdG5ldCIsImNoYWluIjoibmVhciIsImlhdCI6MTYzMTM2NTA3MCwiZXhwIjoxNjMxNDUxNDcwfQ.XFv2IS1ZBrSgJUnY0B334iiTt5gL1pq-vgdYaKh1dk8"
}
Body ParamDescription
signerAddressThe NEAR accountId of user.
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.

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

Last updated on September 8, 2022