| description |
|---|
Description of endpoints used to get data related to users and profiles on the DeSo blockchain |
Please make sure you've read . so you are familiar with the following types referenced in this documentation:
- #profileentryresponse
- #postentryresponse
- #balanceentryresponse
- #nftentryresponse
- #nftcollectionresponse
POST /api/v0/get-users-stateless
Get information about multiple users. This endpoint is used for retrieving data about a user after they log in, so the UI can adjust to the attributes of the user.
Request contains a list of public keys of users to fetch.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Get Users Stateless
- Use GetUsersStateless to retrieve data about users upon login
- Use GetUsersStateless to retrieve profiles for the Bithunt community projects leaderboard
| Name | Type | Description |
|---|---|---|
| PublicKeysBase58Check* | String[] | list of public keys |
| SkipForLeaderBoard | Boolean | Skips fetching all attributes other than the ProfileEntryResponse and PublicKeyBase58Check |
| GetUnminedBalance | Boolean | If true, get all UTXOs to compute the user's unmined balance. This is slower and not recommended. |
{% tabs %} {% tab title="200: OK Successfully return all user objects requested, param updater public keys, and the default fee" %} {% tabs %} {% tab title="Sample Response" %}
{
UserList: [
{
PublicKeyBase58Check: "BC1YLg3FS19Syz9h6fqErZEtsKkRxBfkzqp75PiGwMUXJ1fLrytRVVk",
ProfileEntryResponse: <ProfileEntryResponse>,
Utxos: [], // Deprecated
BalanceNanos: 100, // User's balance. If SkipForLeaderboard, 0 is always returned.
UnminedBalanceNanos: 5, // User's balance in nanos that has not been mined into a block yet. If SkipForLeaderboard, 0 is always returned.
PublicKeysBase58CheckFollowedByUser: ["BC1YLianxEsskKYNyL959k6b6UPYtRXfZs4MF3GkbWofdoFQzZCkJRB"], // List of public keys followed by this user. If SkipForLeaderboard, an empty array is always returned.
UsersYouHODL: [<BalanceEntryResponse>, <BalanceEntryResponse>], // Array of Balance entry responses representing this user's creator coin holdings. If SkipForLeaderboard, an empty array is always returned.
UsersWhoHODLYou: 2, // Count of the number of unique public keys that own this user's creator coin. If SkipForLeaderboard, 0 is always returned.
HasPhoneNumber: false, // If true, this user has verified their phone number for free DeSo. If SkipForLeaderboard, 0 is always returned.
CanCreateProfile: true, // If true, this user is able to create a profile. Either they have enough DeSo to cover the create profile fee OR they've verified their phone number OR verified through the Jumio flow. If SkipForLeaderboard, false is always returned.
BlockedPubKeys: { // BlockedPubKeys is a map with keys representing Public Keys this user has blocked. Values are empty object with no significance. A map is used to improve look up performance. If SkipForLeaderboard, an empty object is always returned.
"BC1YLiUt3iQG4QY8KHLPXP8LznyFp3k9vFTg2mhhu76d1Uu2WMw9RVY": {},
},
HasEmail: true, // If true, the user has provided an email. If SkipForLeaderboard, false is always returned.
EmailVerified: true, // If true, the user has verified their email address by clicking on a link sent to them. If SkipForLeaderboard, false is always returned.
JumioStartTime: 1908230921, // The time at which this user began the Jumio flow. If SkipForLeaderboard, 0 is always returned.
JumioFinishedTime: 1908230949, // The time at which the user finished the Jumio flow. If SkipForLeaderboard, 0 is always returned.
JumioVerified: true, // If true, the user successfully completed the Jumio flow and Jumio verified their identity. If SkipForLeaderboard, false is always returned.
JumioReturned: true, // If true, Jumio's callback after scanning ID has been received. If SkipForLeaderboard, false is always returned.
IsAdmin: true, // If true, this user is an admin on this node. If SkipForLeaderboard, false is always returned.
IsSuperAdmin: true, // If true, this user is a superadmin on this node. If SkipForLeaderboard, false is always returned.
IsBlacklisted: false, // If true, this user is blacklisted on this node. If SkipForLeaderboard, false is always returned.
IsGraylisted: false, // If true, this user is graylisted on this node. If SkipForLeaderboard, false is always returned.
TutorialStatus: "TutorialStarted", // Indicates where in the tutorial the user currently is. If SkipForLeaderboard, the empty string is always returned.
CreatorPurchasedInTutorialUsername: "LazyNina", // Username of the creator the user purchased during the tutorial flow. If SkipForLeaderboard, the empty string is always returned.
CreatorCoinPurchasedInTutorial: 1823789, // The amount of Lazy Nina creator coins purchased in the tutorial. If SkipForLeaderboard, 0 is always returned.false
MustCompleteTutorial: true, // If true, the user must finish the tutorial before they are able to perform basic transfers on this node. If SkipForLeaderboard, false is always returned.
},
],
DefaultFeeRateNanosPerKB: 100, // The minimum network fee rate in Nanos Per KB.
ParamUpdaters: { // Map of Public key to Param Updaters.
BC1YLfoSyJWKjHGnj5ZqbSokC3LPDNBMDwHX3ehZDCA3HVkFNiPY5cQ: true,
BC1YLfz4GH3Gfj6dCtBi8bNdNTbTdcibk8iCZS75toUn4UKZaTJnz9y: true,
BC1YLg3oh6Boj8e2boCo1vQCYHLk1rjsHF6jthBdvSw79bixQvKK6Qa: true,
BC1YLgD1f7yw7Ue8qQiW7QMBSm6J7fsieK5rRtyxmWqL2Ypra2BAToc: true,
BC1YLgGLKjuHUFZZQcNYrdWRrHsDKUofd9MSxDq4NY53x7vGt4H32oZ: true,
BC1YLiXwGTte8oXEEVzm4zqtDpGRx44Y4rqbeFeAs5MnzsmqT5RcqkW: true,
BC1YLj8UkNMbCsmTUTx5Z2bhtp8q86csDthRmK6zbYstjjbS5eHoGkr: true,
}
}5{% endtab %}
{% tab title="Response Field Descriptions" %} ...coming soon! See comments in sample response for descriptions for now. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/get-profiles
Get user profiles for searching by name or for the creator leaderboard.
Default number of returned profiles is 20.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Get Profiles
- Use GetProfiles to search for users by username
- Use GetProfiles to get profiles for the creator leaderboard
| Name | Type | Description |
|---|---|---|
| PublicKeyBase58Check | String | When provided, find the profile that contains the public key. The page of results returned by this endpoint will start at the profile that is next in the ordered list. |
| Username | String | When provided, find the profile that contains this username. The page of results returned by this endpoint will start at the profile that is next in the ordered list. |
| UsernamePrefix | String | username prefix. When provided, only return profiles with usernames that match this prefix |
| Descripton | String | Deprecated |
| OrderBy | String | Ordering method to be used on the result set </p> </p> Must be one of
,
, or
|
| NumToFetch | uint32 | Number of profiles to fetch. Defaults to 20. </p> </p> Must be less than 100 |
| ReaderPublicKeyBase58Check | String | Reader public key |
| ModerationType | String | empty string, If |
| FetchUsersThatHODL | Boolean | If single profile is requested, return a list of HODLers |
| AddGlobalFeedBool | Boolean | If set to true posts in response will contain boolean if they are in global feed |
{% tabs %} {% tab title="200: OK List of profiles requested and a NextPublicKey to use to get the next page of results " %} {% tabs %} {% tab title="Sample Response" %}
{
ProfilesFound: [<ProfileEntryResponse>, <ProfileEntryResponse>], // Array of ProfileEntryResponse Objects.
NextPublicKey: "BC1YLianxEsskKYNyL959k6b6UPYtRXfZs4MF3GkbWofdoFQzZCkJRB", // This is the PublicKeyBase58Check needed to fetch the next page of results.
}{% endtab %}
{% tab title="Response Field Descriptions" %} ...coming soon! See comments in sample response for descriptions for now. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/get-single-profile
Get information about single profile.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Get Single Profile
- Use GetSingleProfile to get information to display on a user's profile page
- Use GetSingleProfile to search for a profile by public key
| Name | Type | Description |
|---|---|---|
| PublicKeyBase58Check | String | public key of the profile to fetch </p> </p> required if Username is not provided |
| Username | String | username of the profile to fetch </p> </p> required if PublicKeyBase58Check is not provided |
| NoErrorOnMissing | Boolean | If true, do not throw a 404 error if there is no profile found. Instead, nil will be return for the Profile in the response body. |
{% tabs %} {% tab title="200: OK " %} {% tabs %} {% tab title="Sample Response" %}
{
Profile: <ProfileEntryResponse>, // ProfileEntryResponse for the username or public key provided.
IsBlacklisted: false, // If true, this user is blacklisted on this node.
IsGraylisted: false, // If true, this user is graylisted on this node.
}{% endtab %}
{% tab title="Response Field Descriptions" %} ...coming soon! See comments in sample response for descriptions for now. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %}
{% tab title="404: Not Found No profile found for the provided username or public key" %}
{
// Response
}{% endtab %} {% endtabs %}
GET /api/v0/get-single-profile-picture/{PublicKeyBase58Check}
Returns the profile picture of the given public key
Endpoint implementation in backend.
Example usage in frontend:
- Construct the Get Single Profile Picture URL
- Use GetSingleProfilePictureURL to get the profile picture for a user
| Name | Type | Description |
|---|---|---|
| PublicKeyBase58Check* | String | Public key of the user for whom we are fetching a profile picture |
| Name | Type | Description |
|---|---|---|
| fallback | String | URL of the image to be used in the event that there is no profile picture for the public key provided |
{% tabs %} {% tab title="200: OK Profile picture found" %} Image file of the profile picture is returned {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %}
{% tab title="404: Not Found No profile picture found for public key provided" %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/get-user-global-metadata
Get user metadata such as email and phone.
This endpoint requires a JWT, which can be retrieved from Identity.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Get User Global Metadata
- Use GetUserGlobalMetadata to fetch email address to display on settings page
Note: this data is not stored on-chain.
| Name | Type | Description |
|---|---|---|
| UserPublicKeyBase58Check* | String | user public key |
| JWT* | String | JSON web token authenticating user |
{% tabs %} {% tab title="200: OK Successfully retrieved user" %} {% tabs %} {% tab title="Sample Response" %}
{
Email: "[email protected]",
PhoneNumber: "123346789"
}{% endtab %}
{% tab title="Response Field Descriptions" %} ...coming soon! See comments in sample response for descriptions for now. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/update-user-global-metadata
Update user's email address and the state of messages that have been read.
This endpoint requires a JWT, which can be retrieved from Identity.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Update User Global Metadata
- Use UpdateUserGlobalMetadata to update email address
| Name | Type | Description |
|---|---|---|
| UserPublicKeyBase58Check* | String | user public key |
| JWT* | String | JSON web token authenticating user |
| String | new email address. If provided, an email will be sent to verify this email address | |
| MessageReadStateUpdatesByContact | Object with string keys and int values | A map with keys that represent public keys that have messaged this user. The values represent the index of the message read in the conversation between the two users. |
{% tabs %} {% tab title="200: OK Successfully updated user global metadata" %} No response body {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %} {% endtabs %}
GET /api/v0/get-user-metadata/{PublicKeyBase58Check}
Get user metadata. Typically, this endpoint is used when reaching node.deso.org to get user metadata that should be merged with user metadata from one's local node.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Get User Metadata
- Use GetUserMetadata to get additional data about a user to merge in with user metadata fetch from local node
| Name | Type | Description |
|---|---|---|
| PublicKeyBase58Check* | String | Public key of the user for whom we are fetching user metadata |
{% tabs %} {% tab title="200: OK Successfully retrieved user metadata from this node" %} {% tabs %} {% tab title="Sample Response" %}
{
"HasPhoneNumber": false, // Whether the user verified a phone number. Used to know whether to allow user to launch identity to get free DeSo for verifying their phone number
"CanCreateProfile": true, // Whether or not this user is capable of creating a profile. Even if a user does not have enough DeSo to create a profile, they may be able to create a profile since it will be comped by the node to which this request was made. Usually profile creation will be comped if a user verified either their phone number or went through the Jumio flow.
"BlockedPubKeys": { // Map of public keys that are blocked by the user.
"BC1YLhtBTFXAsKZgoaoYNW8mWAJWdfQjycheAeYjaX46azVrnZfJ94s": {},
},
"HasEmail": false, // Whether the user provided an email to the node to which this request was made.
"EmailVerified": false, // Whether the user verified their email address.
"JumioFinishedTime": 1629943843752943900, // Time user finished the jumio flow
"JumioVerified": true, // Whether the user was verified by Jumio
"JumioReturned": true // Whether Jumio returned a callback for this user.
}{% endtab %}
{% tab title="Response Field Descriptions" %} ...coming soon! See comments in sample response for descriptions for now. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %}
{% tab title="404: Not Found Node does not expose its global state so you are unable to get user metadata from the requested node" %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/delete-pii
Deletes email address and phone number associated with this user from the node's global state.
This endpoint requires a JWT, which can be retrieved from Identity.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Delete PII
- Use DeletePII to remove user's personal information at the user's request
| Name | Type | Description |
|---|---|---|
| PublicKeyBase58Check* | String | user public key that wants to delete their PII |
| JWT* | String | JSON web token authenticating user |
{% tabs %} {% tab title="200: OK Successfully deleted personal identifiable information including phone number and email address" %} No response body {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/block-public-key
Block another user. Blocking a user hides that user from everything you see and the blocked user's comments on your posts will be hidden for all other users.
Note: Blocks are not currently stored on chain and thus a block only applies to the node on which a user is blocked.
This endpoint requires a JWT, which can be retrieved from Identity.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Block Public Key
- Use BlockPublicKey to block a user as described above
- Use BlockPublicKey to unblock a user
| Name | Type | Description |
|---|---|---|
| PublicKeyBase58Check* | String | user public key |
| JWT* | String | JSON web token authenticating user |
| BlockPublicKeyBase58Check* | String | blocked user public key |
| Unblock | Boolean | false if block, true if unblock |
{% tabs %} {% tab title="200: OK Successfully blocked public key and return all public keys currently blocked by this user" %} {% tabs %} {% tab title="Sample Response" %}
{
BlockedPublicKeys: {
"BC1YLhqEhWvNnwW9TBqXURFqwkdpUYKrMVgTHQzopF5rRBDcD1LLSUp": {}, // Every key in the map is a blocked pulic key.
}
}{% endtab %}
{% tab title="Response Field Descriptions" %} ...coming soon! See comments in sample response for descriptions for now. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/get-user-derived-keys
Get a map of derived public keys to metadata about that derived key for a given master public key.
Endpoint implementation in backend.
| Name | Type | Description |
|---|---|---|
| PublicKeyBase58Check* | String | Public key for which we want to query derived keys |
{% tabs %} {% tab title="200: OK Successfully retrieved derived keys for user" %} {% tabs %} {% tab title="Sample Response" %}
{
DerivedKeys: {
BC1YLhqEhWvNnwW9TBqXURFqwkdpUYKrMVgTHQzopF5rRBDcD1LLSUp: { // Key is a derived key
OwnerPublicKeyBase58Check: "BC1YLfuD5AGm2guj3q5wF7WGi3jTUzNhHUHc84GtVsk9kHyxbnk5V1H", // Owner of the derived key.
DerivedPublicKeyBase58Check: "BC1YLhqEhWvNnwW9TBqXURFqwkdpUYKrMVgTHQzopF5rRBDcD1LLSUp", // The derived key itself.
ExpirationBlock: 1000000, // THe block height at which the derived key expires.
IsValid: true // If true, this derived key can still perform actions on behalf of the owner.
}
}
}{% endtab %}
{% tab title="Response Field Descriptions" %} ...coming soon! See comments in sample response for descriptions for now. {% endtab %} {% endtabs %} {% endtab %}
{% tab title="400: Bad Request " %}
{
// Response
}{% endtab %} {% endtabs %}
POST /api/v0/delete-identities
Temporary route to wipe seedinfo cookies. This endpoint relies on identity api.
Endpoint implementation in backend.
Example usages in frontend:
- Make request to Delete Identities
- Use DeleteIdentities to clean up legacy seedinfo storage
{% tabs %} {% tab title="200: OK Successfully deleted cookies" %}
{
// Response
}{% endtab %} {% endtabs %}