API Request Endpoints¶
Warning
This documentation page is not finished and due to Hiven being not stable yet, changes will and can occur
Endpoints¶
Important
The possible return codes and exceptions only contain unique exceptions, meaning generic ones are not added to avoid making the docs messy!
For generic exceptions go here
User Endpoints¶
/users/@me¶
Default user endpoint for accessing the user assigned to the passed token.
Fetches your own user data.
Required header:
{
"Authorization": "*************", // enter your own token
}
200
Authorisation was successful and the body contains the requested data
Expected Response:
{
"success": true,
"data": {
"id": str,
"name": str,
"username": str,
"icon": str | None,
"header": str | None,
"flags": int,
"bot": bool | None,
"location": str,
"website": str,
"bio": str,
"email": str,
"email_verified": bool,
"mfa_enabled": bool
}
}
400
Authorisation Token is not set or faulty! Check your header if the token was entered correctly!
Expected Response:
{
"success": false,
"error": {
"code": "no_auth",
"message": "Authorization is required for this route"
}
}
Edits your user accounts data
Required body:
| Name | Type | Description | Required |
|---|---|---|---|
location |
str |
Location field of the user | No* |
username |
str |
Display Username | No* |
website |
str |
Display website link | No* |
bio |
str |
Bio of the user | No* |
header |
str (base64 encoded img) |
Header image of the user | No* |
icon |
str (base64 encoded img) |
Icon image of the user | No* |
*At least one value must be passed!
Required header:
{
"Authorization": "*************", // enter your own token
}
200
Patch was successful and the data was changed! The response will containt the updated data of the User
{
"success": True,
"data": {
"id": str,
"name": str,
"username": str,
"icon": str | None,
"header": str | None,
"flags": int,
"bot": bool | None,
"location": str,
"website": str,
"bio": str,
"email": str,
"email_verified": bool,
"mfa_enabled": bool
}
}
Warning
If you enter an unknown or mistyped variable, it will not be correctly recognised, and the Hiven API Server will change no value. Still the result will be 200 and the user-data will be sent without any changes!
/users/:username¶
Endpoint for a specific user.
Fetches the user and returns the data.
No Required header
Example
GET /users/testname
200
Authorisation was successful and the body contains the requested data
Expected Response:
{
"success": true,
"data": {
"id": str,
"name": str,
"username": str,
"icon": str | None,
"header": str | None,
"flags": int,
"bot": bool | None,
"location": str,
"website": str,
"bio": str,
"email": str,
"email_verified": bool,
"mfa_enabled": bool
}
}
400
Possible Exceptions:
User with that id was not found
Error
{
"success": false,
"error": {
"code": "user_not_found",
"message": "That user does not exist"
}
}
/users/:id¶
Endpoint for a specific user based on their id.
Fetches the user and returns the data.
No Required header
Example
GET /users/123456789123456789
200
Authorisation was successful and the body contains the requested data
!!! Expected Response:
```json
{
"success": true,
"data": {
"id": str,
"name": str,
"username": str,
"icon": str | None,
"header": str | None,
"flags": int,
"bot": bool | None,
"location": str,
"website": str,
"bio": str,
"email": str,
"email_verified": bool,
"mfa_enabled": bool
}
}
```
400
Possible Exceptions:
User with that id was not found
Error
{
"success": false,
"error": {
"code": "user_not_found",
"message": "That user does not exist"
}
}
/streams/@me/mentions¶
Endpoint for fetching your mentions in the Houses and rooms of your scope.
Fetches the mentions in your scope.
Required header:
{
"Authorization": "*************", // enter your own token
}
200
Returns a list with all mentions wrapped in a message Hiven object
Expected Response:
{
"success": true,
"data": [
{
"room_id": str,
"bucket": int,
"id": str,
"attachment": unknown,
"author_id": str,
"content": str,
"device_id": str,
"edited_at": str,
"embed": {},
"exploding": bool,
"exploding_age": unknown,
"mentions": [
{
// User object
"icon": str | None,
"id": str,
"username": str,
"name": str,
"header": str | None,
"flags": str | int | None,
"bot": bool | None
}
// All mentions in the message
],
"metadata": unknown,
"timestamp": str,
"type": int,
"author": {
// User object
"icon": str | None,
"id": str,
"username": str,
"name": str,
"header": str | None,
"flags": str | int | None,
"bot": bool | None
}
},
...
]
}
/users/@me/rooms¶
Endpoint for private rooms that are not related to any House.
Creates a new private room or private group room.
Required body:
| Name | Type | Description | Required |
|---|---|---|---|
recipient |
str (user id) |
Recipient that should be added to the DM room | No* |
recipients |
List[str] (user ids) |
Recipients that should be added to the DM room (Group Channel) | No* |
*At least one is required for the correct execution of the request
Required header:
{
"Authorization": "*************", // enter your own token
"Content-Type": "application/json"
}
200
In work
400
In work
/users/@me/rooms/:id¶
Endpoint for a specific private room based on the id.
Leaves a private group room.
Required header:
{
"Authorization": "*************", // enter your own token
}
204
Successfully left the private group room.
400
Possible Exceptions:
This method is not allowed on a private room, but only private group rooms.
{
"success": false,
"error": {
"code": "method_not_allowed_on_room_type",
"message": "This endpoint can only be called on private group rooms (room type 2"
}
}
/users/@me/houses/:id¶
Endpoint for a specific House where you are member in.
Leaves a house.
Required header:
{
"Authorization": "*************", // enter your own token
}
204
Successfully left the house
400
Possible Exceptions:
The House is out of scope! You can not leave a house you are not in.
{
"success": false,
"error": {
"code": "out_of_scope",
"message": "you are not part of this house, so you can't leave it"
}
}
/relationships/@me/friends/:id¶
Endpoint for a user you are friends with.
Unfriends someone.
Required header:
{
"Authorization": "*************", // enter your own token
}
204
Succesfully unfriended the user.
400
In work
House Endpoints¶
/houses¶
Endpoint for the general house collection. Only used for house creation at the moment.
Creates a new House with the passed data.
Required body:
| Name | Type | Description | Required |
|---|---|---|---|
name |
str |
Name of the House | Yes |
icon |
str (base64 encoded img) |
Icon image of the House | No |
Required header:
{
"Authorization": "*************", // enter your own token
"Content-Type": "application/json"
}
200
House Creation was successful and the newly created House is now returned.
{
"success": true,
"data": {
"id": str,
"name": str,
"description": str | None,
"owner_id": str,
"rooms": [
{
"id": str,
"house_id": str,
"name": str,
"position": int,
"type": int
}
],
"type": int
}
}
400
Possible Exceptions:
The field name is missing (Required)
{
"success": false,
"error": {
"code": "invalid_schema",
"message": "Required fields (name) not met"
}
}
/houses/:id¶
Endpoint for a specific house based on its id.
Edits the house if the permissions are sufficient.
Required body:
| Name | Type | Description | Required |
|---|---|---|---|
name |
str |
Name of the House | No* |
icon |
str (base64 encoded img) |
Icon image of the House | No* |
*At least one is required for the correct execution of the request
Required header:
{
"Authorization": "*************", // enter your own token
"Content-Type": "application/json"
}
200
Patch was successful and the data was changed! The response will containt the updated value of the House
{
"success": true,
"data": {
"name": "test2",
"house_id": "289393198252424847"
}
}
400
Possible Exceptions:
The field name is missing (Required)
{
"success": false,
"error": {
"code": "invalid_schema",
"message": "Required fields (name) not met"
}
}
The passed image base64 string was not in the correct format.
{
"success": false,
"error": {
"code": "invalid_icon_file_format",
"message": "Your icon must be an image"
}
}
500
Possible Exceptions:
Possibly caused by a faulty base64 string, which could not be processed.
{
"success": false,
"error": {
"code": "invalid_schema",
"message": "Required fields (name) not met"
}
}
Deletes the house if the permissions are sufficient.
Required header:
{
"Authorization": "*************", // enter your own token
}
204
House Deletion was successful.
400
Possible Exceptions:
You do not have the permissions to delete this House.
{
"success": false,
"error": {
"code": "no_permission",
"message": "You do not have permission to do this"
}
}