Welcome

Welcome to the official, one–and–only api documentation for Ayaka.

Connecting

When connecting you will want to use the following link for the REST API:

https://hatsu.vincentrps.xyz

When connecting to the Gateway you will want to use the following link:

wss://gateway.vincentrps.xyz

User Agents

As-Of current, Ayaka does not track the User-Agent header, but it is still recommended you put it there.

Format: Library Name (https://github.com/user/library) language: version http-client: version

Note

The http-client is optional.

Example: ayaka.py (https://github.com/Ayakapy/Ayaka.py) python: 3.10 aiohttp: 3.8.1

Snowflakes

Ayaka uses snowflakes as it’s one-time id unique generation platform, these are based off the twitter snowflake.

A Ayaka snowflake normally are made with:

  • The Epoch: 1577836801, The first second of 2020.

  • Worker ID: Generated from the Current Thread Process.

  • Datacenter ID: 0.

  • TimeStamp: The Current Epoch.

  • Sequence: The Current Sequence + 1.

and thats it. This could be seen as too much but it helps make id’s which are small and unique.

Index

Users

This covers the current user-api of Ayaka.

A session_id is, in lamens terms, just a stringized snowflake.

Note

Session ID’s will only be seeable once you connect to the Gateway, the READY events d payload witholds your user data, of which includes the session_ids object.

User

The following Represents a Ayaka user.

name

type

id

integer

username

string

separator

integer

bio

string

avatar_url

string

banner_url

string

flags

list of strings

verified

boolean

email

string

password

string(hashed)

system

boolean

email_verified

boolean

session_ids

list strings

users/@me

POST /users/@me

Creates a User

Arguments:

name

type

username

string

separator

integer

bio?

string

email

string

password

string
Status Codes
PATCH /users/@me

Edits a User

name

type

username

string

separator

integer

bio?

string

email?

string

password?

string
Status Codes
GET /users/@me

Gives a user object of your currently identified account.

Request Headers
Status Codes

Guilds

Warning

The Guild API is currently still in the design process, this means this is subject to heavy change.

Guild

name

type

id

int

name

string

description

string

banner

string

invite_banner

string

vanity_url

string

verified

boolean

partnered

boolean

official

boolean (always false normally)

owner

int

emojis

List of Emoji Objects

roles

List of Role Objects

Role Object

name

type

id

int

name

string

position

int

color

string

permissions

list of strings which denote the permissions

Member Object

name

type

user

User Object

nick

string

avatar_url

string, null

banner_url

string, null

joined_at

ISO8601 timestamp

deaf

boolean

mute

boolean

owner

boolean

roles

List of role id’s

Routes

POST /guilds

Create’s a Guild

name

type

name

string

description?

string

Returns a Guild object, if sucessful.

Request Headers
Status Codes
GET /guilds/guild-id

Gets a Guild

Returns a Guild object, if sucessful

Request Headers
Status Codes
PATCH /guilds/guild-id

Edits the Guild

Returns the Edited objects, if sucessful

Request Headers
Status Codes
DELETE /guilds/guild-id

Deletes a Guild

Request Headers
Status Codes
GET /guilds/guild-id/preview

Returns a Partial Guild Object, of the Guild

Status Codes
POST /invites/invite-code

Joins a Guild

Returns a Member Object, if sucessful

Request Headers
Status Codes

Channels

Channels are Ayaka’s one-way communication type for both messages and voice.

Category

name

type

id

int

name

string

description

string

inside_of

int (always 0)

type

int (always 1)

position

int

Text Channel

name

type

id

int

name

string

description

string

inside_of

int

type

int

position

int

Gateway

The Gateway is Ayaka’s way of implementing a easy–affordable and non-blocking event system.

Gaining the Port

Ayaka separates client connections using addresses

to get an available one just do:

import requests

r = requests.get('https://gateway.vincentrps.xyz/available')
print(r.json())
Available Domains

production-1: wss://gateway-prod-1.vincentrps.xyz

Identifying

Once you have done the initial connection with the gateway you will want to send your identification payload.

name

type

optional?

session_id

string

No

encoding

string

Yes

The encoding should be one of:

  • json

  • zlib

It is recommended to use the json encoding, as it doesn’t require decompressing and is more tested because of it’s ease-of-use.

This is a code example of a gateway connection:

import json
import asyncio
import requests
from websockets import client

r = requests.get('https://gateway.vincentrps.xyz/available')
d = r.text

async def connection():
    ws = await client.connect(f'wss://gateway.vincentrps.xyz:{d["port"]}', ping_timeout=20)
    await ws.send(json.dumps({'session_id': 'my_session_id'}))
    while True:
        recv = await ws.recv()
        print(recv)

asyncio.run(connection())

Keeping Alive

The only thing you need to do to keep the connection alive, is to ping the gateway before the timeout runs out.

  • PING_TIMEOUT: 20 seconds.

  • PING_INTERVAL: 20 seconds.

Note

Most WebSocket Wrappers should already do this automatically.

Event Payload

A event payload goes as so:

{
"t": "EVENT_NAME",
"d": {
    "key": "VaLuE12345"
    }
}

PRESENCE_UPDATE Payload:

{
"t": "PRESENCE_UPDATE",
"id": 123456,
"d": {
    "type": 1/2/3/4,
    "description": "string",
    "emoji": emoji_id,
    "embed": {
        "name": "string",
        "description": "string",
        "banner_url": "string",
        "text": {
            "top": "string",
            "bottom": "string",
            }
        }
    }
}

NOTIFICATION Payload:

{
"t": "NOTIFICATION",
"type": "MESSAGE, GUILD, EVERYONE, HERE",
"excerpt": {
        ...
    }
}

Event Reference

  • GUILD_CREATE Called when you create a Guild.

  • GUILD_JOIN Called when you join a Guild.

  • GUILD_INIT Called after you get the READY event.

Given one time for each guild, The new channels field will be added to the guild object.

  • GUILD_UPDATE Called when a Guild is updated.

  • GUILD_DELETE Called when a Guild is deleted.

  • INVITE_CREATE Called when a user creates an invite.

  • CHANNEL_CREATE Called when a channel is created.

  • PRESENCE_UPDATE Called when a user updates there presence.

  • NOTIFICATION Called when you get a notification

RateLimiting

Ayaka implements ratelimits in a straight forward–and easy matter.

Note

The current ratelimit implementation on the backend is still a bit iffy and is due to change.

X-RateLimit-Bucket: 'LIMITER/ip_address/ROUTE_NAME/limit/time/per'
X-RateLimit-Limit: '10'
X-RateLimit-Remaining: '3'
X-RateLimit-Reset: '1645970050'
X-RateLimit-Retry-After: '0'