Hanas Backend API

An API description of the backend API for Hanas, a tool and community for constructed languages.

Authentication is done through the same methods as Kratos. You should either submit an API key with authenticated requests in the X-Session-Token header, or in a cookie set by logging in with Kratos. Authenticated operations are marked with a badge icon.

Responses are contained in a wrapper of the form:

{
  error: false,
  data: {
    ...
  }
}

Pagination in Hanas is done using a cursor with a prefix. On any paginated endpoint, the response will look like this:

{
  error: false,
  data: [
    { ... },
    { ... },
    ...
  ],
  cursor: {
    next: "next__cjld2cyuq0000t3rmniod1foy",
    previous: null
  }
}

The client can then pass a query parameter with cursor set to the value from cursor.next or cursor.previous in order to find the page before or after. The client can also specify the maximum number of records to receive in one request using the take query parameter. This must be an integer value greater than 0 and lower than the instance's HANAS_RESULTS_MAX_PAGE_SIZE.

For example, if a client wanted to get the next page of the example response above, and receive up to 6 objects, they would resend their GET request to https://hanas.instance/endpoint?cursor=next__cjld2cyuq0000t3rmniod1foy&take=6.

Paginated responses are marked with a "duplicate" icon.

Note that while these docs work without Javascript, some enhancements may be unavailable. The menu also requires Javascript when the viewport is at a mobile size.

Models

`User`

username string (/^([a-z0-9](-|_)?)+[a-z0-9]/, between 2 and 30 characters)

The username for this user.

displayName string (between 2 and 30 characters)

The display name for this user.

If you're displaying users, you should use this rather than the username, if it's available.

Be wary of weird display names. You should fully expect people to use all sorts of unicode hell here.

The min/max length given here is after cleaning.

description string (up to 1000 characters)

A short description of the user.

gender string (/^([a-fA-F0-9]{3}){1,2}$/)

Hex color representing the gender of the user.

Please don't ruin the fun by just giving users a pink/blue selector. It's way funnier if you just give them a free color selection thing.

pronouns string (between 2 and 15 characters)

A free text field, intended to store pronouns in the format of nominative/accusative or nominative/accusative/possessive. In reality it's a short free text field since I can't predict everything users might have.

The length may end up being raised, but it should generally only be large enough for something like "she/they/it" or whatever.

The min/max length given here is after cleaning.

profilePicture string (uri)

Link to profile picture. Currently unused.

banner string (uri)

Link to birdsite-esque profile picture. Currently unused.

created string (datetime)

When this user was created.

updated string (datetime)

When this user was last updated.

Example
{
    username: "alice",
    displayName: "Alice Iwakura",
    description: "I love languages!",
    gender: "76428a",
    pronouns: "she/her",
    profilePicture: "https://cdn.hanas.app/users/pfp/alice.png",
    banner: "https://cdn.hanas.app/users/banner/alice.png",
    created: "2021-09-27T22:07:22.757Z",
    updated: "2021-09-27T00:23:03.327Z"
}

`Lang`

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

created string (datetime)

When this language was created.

updated string (datetime)

When this language was last updated.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!",
    created: "2021-09-27T06:34:23.434Z",
    updated: "2021-09-27T11:52:08.318Z"
}

`LangPermission`

created string (datetime)

When this set of permissions was created; aka when the invite for this language was accepted, or in the case of the owner, when the language was created.

updated string (datetime)

When this set of permissions was last updated.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

Whether this user can update the permissions for this language, including permissions of other users or removing their permissions. They cannot edit the permissions of other users with this permission, or those of the owner.

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    created: "2021-09-27T07:24:28.385Z",
    updated: "2021-09-27T05:03:46.349Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

`LangInvite`

active boolean

If this is true, then the invite can be accepted.

created string (datetime)

When this invite was sent.

accepted string (datetime)

When this invite was accepted, if it has been.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    active: false,
    created: "2021-09-27T03:20:56.822Z",
    accepted: "2021-09-27T14:07:04.901Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

`WordClass`

name string

A name for this word class.

abbreviation string

An abbreviation for this word class, generally only a couple characters long.

created string (datetime)

When this word class was created.

updated string (datetime)

When this word class was last updated.

Example
{
    name: "",
    abbreviation: "",
    created: "2021-09-27T18:34:41.014Z",
    updated: "2021-09-27T23:26:31.414Z"
}

`Word`

word string

The word, in the language.

definition string

A definition for the word.

ipa string

The pronunciation of the word in the International Phonetic Alphabet. May later be automatically generated by an SCE ruleset - currently manual.

notes string

Longer-form notes about the word.

created string (datetime)

When this word was created.

updated string (datetime)

When this word was last updated.

Example
{
    word: "",
    definition: "",
    ipa: "",
    notes: "",
    created: "2021-09-27T12:27:29.491Z",
    updated: "2021-09-27T03:34:06.931Z"
}

Routes

`/`

GET

GET `/`

Response 200

error boolean

data

Example
{
    error: false,
    data: (TODO: implement model properties)
}

`/users`

GET

GET `/users`

Response 200

username string (/^([a-z0-9](-|_)?)+[a-z0-9]/, between 2 and 30 characters)

The username for this user.

displayName string (between 2 and 30 characters)

The display name for this user.

If you're displaying users, you should use this rather than the username, if it's available.

Be wary of weird display names. You should fully expect people to use all sorts of unicode hell here.

The min/max length given here is after cleaning.

description string (up to 1000 characters)

A short description of the user.

gender string (/^([a-fA-F0-9]{3}){1,2}$/)

Hex color representing the gender of the user.

Please don't ruin the fun by just giving users a pink/blue selector. It's way funnier if you just give them a free color selection thing.

pronouns string (between 2 and 15 characters)

The length may end up being raised, but it should generally only be large enough for something like "she/they/it" or whatever.

The min/max length given here is after cleaning.

profilePicture string (uri)

Link to profile picture. Currently unused.

banner string (uri)

Link to birdsite-esque profile picture. Currently unused.

created string (datetime)

When this user was created.

updated string (datetime)

When this user was last updated.

Example
{
    username: "alice",
    displayName: "Alice Iwakura",
    description: "I love languages!",
    gender: "76428a",
    pronouns: "she/her",
    profilePicture: "https://cdn.hanas.app/users/pfp/alice.png",
    banner: "https://cdn.hanas.app/users/banner/alice.png",
    created: "2021-09-27T05:58:21.984Z",
    updated: "2021-09-27T06:33:55.525Z"
}

`/langs`

GET POST

GET `/langs`

Response 200

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

created string (datetime)

When this language was created.

updated string (datetime)

When this language was last updated.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!",
    created: "2021-09-27T17:56:52.842Z",
    updated: "2021-09-27T12:31:14.021Z"
}

POST `/langs`

Request

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!"
}

Response 201

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

created string (datetime)

When this language was created.

updated string (datetime)

When this language was last updated.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!",
    created: "2021-09-27T03:17:59.521Z",
    updated: "2021-09-27T17:13:29.765Z"
}

Response 400

This error is a validation error; it will contain errors reported by Zod.

Example
{
    error: true,
    data: {
        status: 400,
        message: "Input validation error; see issues for details",
        issues: [
          ... (zod errors)
        ]
    }
}

Response 400

Example
{
    error: true,
    data: {
        status: 400,
        message: "A lang with that code already exists."
    }
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

`/invites`

GET

GET `/invites`

Somewhat WIP. This endpoint is likely to change.

Request

Query Parameters

sent boolean

True if you want invites sent by you, false otherwise.

Example
{
    
}

Response 200

active boolean

If this is true, then the invite can be accepted.

created string (datetime)

When this invite was sent.

accepted string (datetime)

When this invite was accepted, if it has been.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

Example
{
    active: false,
    created: "2021-09-27T12:41:47.128Z",
    accepted: "2021-09-27T06:24:44.230Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false,
    code: "elv"
}

Response 200

active boolean

If this is true, then the invite can be accepted.

created string (datetime)

When this invite was sent.

accepted string (datetime)

When this invite was accepted, if it has been.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    active: false,
    created: "2021-09-27T09:57:42.657Z",
    accepted: "2021-09-27T15:12:14.424Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

`/users/:username`

GET PATCH DELETE

GET `/users/:username`

Response 200

username string (/^([a-z0-9](-|_)?)+[a-z0-9]/, between 2 and 30 characters)

The username for this user.

displayName string (between 2 and 30 characters)

The display name for this user.

If you're displaying users, you should use this rather than the username, if it's available.

Be wary of weird display names. You should fully expect people to use all sorts of unicode hell here.

The min/max length given here is after cleaning.

description string (up to 1000 characters)

A short description of the user.

gender string (/^([a-fA-F0-9]{3}){1,2}$/)

Hex color representing the gender of the user.

Please don't ruin the fun by just giving users a pink/blue selector. It's way funnier if you just give them a free color selection thing.

pronouns string (between 2 and 15 characters)

The length may end up being raised, but it should generally only be large enough for something like "she/they/it" or whatever.

The min/max length given here is after cleaning.

profilePicture string (uri)

Link to profile picture. Currently unused.

banner string (uri)

Link to birdsite-esque profile picture. Currently unused.

created string (datetime)

When this user was created.

updated string (datetime)

When this user was last updated.

Example
{
    username: "alice",
    displayName: "Alice Iwakura",
    description: "I love languages!",
    gender: "76428a",
    pronouns: "she/her",
    profilePicture: "https://cdn.hanas.app/users/pfp/alice.png",
    banner: "https://cdn.hanas.app/users/banner/alice.png",
    created: "2021-09-27T16:47:20.417Z",
    updated: "2021-09-27T04:43:21.285Z"
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No user was found with that username."
    }
}

PATCH `/users/:username`

Request

username string (/^([a-z0-9](-|_)?)+[a-z0-9]/, between 2 and 30 characters)

The username for this user.

displayName string (between 2 and 30 characters)

The display name for this user.

If you're displaying users, you should use this rather than the username, if it's available.

Be wary of weird display names. You should fully expect people to use all sorts of unicode hell here.

The min/max length given here is after cleaning.

description string (up to 1000 characters)

A short description of the user.

gender string (/^([a-fA-F0-9]{3}){1,2}$/)

Hex color representing the gender of the user.

Please don't ruin the fun by just giving users a pink/blue selector. It's way funnier if you just give them a free color selection thing.

pronouns string (between 2 and 15 characters)

The length may end up being raised, but it should generally only be large enough for something like "she/they/it" or whatever.

The min/max length given here is after cleaning.

Example
{
    username: "alice",
    displayName: "Alice Iwakura",
    description: "I love languages!",
    gender: "76428a",
    pronouns: "she/her"
}

Response 200

username string (/^([a-z0-9](-|_)?)+[a-z0-9]/, between 2 and 30 characters)

The username for this user.

displayName string (between 2 and 30 characters)

The display name for this user.

If you're displaying users, you should use this rather than the username, if it's available.

Be wary of weird display names. You should fully expect people to use all sorts of unicode hell here.

The min/max length given here is after cleaning.

description string (up to 1000 characters)

A short description of the user.

gender string (/^([a-fA-F0-9]{3}){1,2}$/)

Hex color representing the gender of the user.

Please don't ruin the fun by just giving users a pink/blue selector. It's way funnier if you just give them a free color selection thing.

pronouns string (between 2 and 15 characters)

The length may end up being raised, but it should generally only be large enough for something like "she/they/it" or whatever.

The min/max length given here is after cleaning.

profilePicture string (uri)

Link to profile picture. Currently unused.

banner string (uri)

Link to birdsite-esque profile picture. Currently unused.

created string (datetime)

When this user was created.

updated string (datetime)

When this user was last updated.

Example
{
    username: "alice",
    displayName: "Alice Iwakura",
    description: "I love languages!",
    gender: "76428a",
    pronouns: "she/her",
    profilePicture: "https://cdn.hanas.app/users/pfp/alice.png",
    banner: "https://cdn.hanas.app/users/banner/alice.png",
    created: "2021-09-27T19:07:15.511Z",
    updated: "2021-09-27T12:12:22.900Z"
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to edit another user."
    }
}

DELETE `/users/:username`

Response 204

(no content)

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

`/users/:username/langs`

GET

GET `/users/:username/langs`

Response 200

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

created string (datetime)

When this language was created.

updated string (datetime)

When this language was last updated.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!",
    created: "2021-09-27T00:22:24.966Z",
    updated: "2021-09-27T20:15:53.016Z"
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No languages were found by that username."
    }
}

`/langs/:id`

GET PATCH

GET `/langs/:id`

Response 200

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

created string (datetime)

When this language was created.

updated string (datetime)

When this language was last updated.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!",
    created: "2021-09-27T05:44:58.395Z",
    updated: "2021-09-27T03:45:44.956Z"
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No language was found by that code."
    }
}

PATCH `/langs/:id`

Request

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

created string (datetime)

When this language was created.

updated string (datetime)

When this language was last updated.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!",
    created: "2021-09-27T02:16:04.414Z",
    updated: "2021-09-27T12:50:20.976Z"
}

Response 200

code string (/[a-z]/, between 3 and 5 characters)

Language code, primary identifier for languages.

name string (between 2 and 30 characters)

Name of the language.

description string (up to 2500 characters)

A short description of the language.

created string (datetime)

When this language was created.

updated string (datetime)

When this language was last updated.

Example
{
    code: "elv",
    name: "Elvish",
    description: "A language spoken by elves in my conworld!",
    created: "2021-09-27T09:15:26.146Z",
    updated: "2021-09-27T17:47:29.434Z"
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to make this edit."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No language was found by that code."
    }
}

`/langs/:id/words`

`/langs/:id/perms`

GET

GET `/langs/:id/perms`

Response 200

created string (datetime)

When this set of permissions was created; aka when the invite for this language was accepted, or in the case of the owner, when the language was created.

updated string (datetime)

When this set of permissions was last updated.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    created: "2021-09-27T15:30:57.336Z",
    updated: "2021-09-27T14:38:28.672Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to see the permissions of this language."
    }
}

`/langs/:id/words/:lemma`

`/langs/:id/words/:lemma/:form`

`/langs/:id/perms/:username`

PATCH

PATCH `/langs/:id/perms/:username`

Request

created string (datetime)

When this set of permissions was created; aka when the invite for this language was accepted, or in the case of the owner, when the language was created.

updated string (datetime)

When this set of permissions was last updated.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    created: "2021-09-27T13:56:35.551Z",
    updated: "2021-09-27T01:46:19.851Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

Response 200

created string (datetime)

When this set of permissions was created; aka when the invite for this language was accepted, or in the case of the owner, when the language was created.

updated string (datetime)

When this set of permissions was last updated.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    created: "2021-09-27T20:00:53.935Z",
    updated: "2021-09-27T12:25:15.807Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to edit the permissions of this language."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No user with permissions for this language was found by that username."
    }
}

`/invites/:code`

DELETE GET POST

DELETE `/invites/:code`

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

GET `/invites/:code`

This will return all invites for the language.

Response 200

active boolean

If this is true, then the invite can be accepted.

created string (datetime)

When this invite was sent.

accepted string (datetime)

When this invite was accepted, if it has been.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    active: false,
    created: "2021-09-27T22:41:08.321Z",
    accepted: "2021-09-27T04:45:59.902Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to see the permissions of this language."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No language was found by this code."
    }
}

POST `/invites/:code`

Request

accept boolean

If this invite should be accepted. Given the limitations of this docs generator, there's only one request possible per endpoint, but this one technically has two: one with only { accept: boolean }, and one with the rest of the properties. To send an invite, you use the latter, while to accept one, you use the former.

username string

The user to send the invite to.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    accept: false,
    username: "amelie",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

Response 204

(no content)

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

`/invites/:code/:username`

GET

GET `/invites/:code/:username`

Response 200

active boolean

If this is true, then the invite can be accepted.

created string (datetime)

When this invite was sent.

accepted string (datetime)

When this invite was accepted, if it has been.

owner boolean

Whether this user owns the language. Overrides all other permissions.

changePermissions boolean

changeId boolean

Whether this user can update the ID (or code) of the language.

changeInfo boolean

Whether this user can update the other information of the language, including the name and description.

changeWords boolean

Whether this user can add/edit/remove words in this language.

Example
{
    active: false,
    created: "2021-09-27T04:26:35.931Z",
    accepted: "2021-09-27T22:31:09.285Z",
    owner: false,
    changePermissions: false,
    changeId: false,
    changeInfo: false,
    changeWords: false
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to see an invite for this user for this language."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No language was found by this code."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No invite has been sent to this user for this language."
    }
}

`/invites/:code/:username/receiver`

GET

GET `/invites/:code/:username/receiver`

Response 200

username string (/^([a-z0-9](-|_)?)+[a-z0-9]/, between 2 and 30 characters)

The username for this user.

displayName string (between 2 and 30 characters)

The display name for this user.

If you're displaying users, you should use this rather than the username, if it's available.

Be wary of weird display names. You should fully expect people to use all sorts of unicode hell here.

The min/max length given here is after cleaning.

description string (up to 1000 characters)

A short description of the user.

gender string (/^([a-fA-F0-9]{3}){1,2}$/)

Hex color representing the gender of the user.

Please don't ruin the fun by just giving users a pink/blue selector. It's way funnier if you just give them a free color selection thing.

pronouns string (between 2 and 15 characters)

The length may end up being raised, but it should generally only be large enough for something like "she/they/it" or whatever.

The min/max length given here is after cleaning.

profilePicture string (uri)

Link to profile picture. Currently unused.

banner string (uri)

Link to birdsite-esque profile picture. Currently unused.

created string (datetime)

When this user was created.

updated string (datetime)

When this user was last updated.

Example
{
    username: "alice",
    displayName: "Alice Iwakura",
    description: "I love languages!",
    gender: "76428a",
    pronouns: "she/her",
    profilePicture: "https://cdn.hanas.app/users/pfp/alice.png",
    banner: "https://cdn.hanas.app/users/banner/alice.png",
    created: "2021-09-27T19:25:17.449Z",
    updated: "2021-09-27T20:55:53.867Z"
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to see an invite for this user for this language."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "The receiver was not found for this invite. (Maybe their account was deleted?)"
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No language was found by this code."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No invite has been sent to this user for this language."
    }
}

`/invites/:code/:username/sender`

GET

GET `/invites/:code/:username/sender`

Response 200

username string (/^([a-z0-9](-|_)?)+[a-z0-9]/, between 2 and 30 characters)

The username for this user.

displayName string (between 2 and 30 characters)

The display name for this user.

If you're displaying users, you should use this rather than the username, if it's available.

Be wary of weird display names. You should fully expect people to use all sorts of unicode hell here.

The min/max length given here is after cleaning.

description string (up to 1000 characters)

A short description of the user.

gender string (/^([a-fA-F0-9]{3}){1,2}$/)

Hex color representing the gender of the user.

Please don't ruin the fun by just giving users a pink/blue selector. It's way funnier if you just give them a free color selection thing.

pronouns string (between 2 and 15 characters)

The length may end up being raised, but it should generally only be large enough for something like "she/they/it" or whatever.

The min/max length given here is after cleaning.

profilePicture string (uri)

Link to profile picture. Currently unused.

banner string (uri)

Link to birdsite-esque profile picture. Currently unused.

created string (datetime)

When this user was created.

updated string (datetime)

When this user was last updated.

Example
{
    username: "alice",
    displayName: "Alice Iwakura",
    description: "I love languages!",
    gender: "76428a",
    pronouns: "she/her",
    profilePicture: "https://cdn.hanas.app/users/pfp/alice.png",
    banner: "https://cdn.hanas.app/users/banner/alice.png",
    created: "2021-09-27T02:19:20.304Z",
    updated: "2021-09-27T03:54:13.215Z"
}

Response 401

Example
{
    error: true,
    data: {
        status: 401,
        message: "You must be authenticated to access this endpoint."
    }
}

Response 403

Example
{
    error: true,
    data: {
        status: 403,
        message: "You do not have permission to see an invite for this user for this language."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "The sender was not found for this invite. (Maybe their account was deleted?)"
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No language was found by this code."
    }
}

Response 404

Example
{
    error: true,
    data: {
        status: 404,
        message: "No invite has been sent to this user for this language."
    }
}

Models

User

Lang

LangPermission

LangInvite

WordClass

Word

Routes

GET /

Response 200

GET /users

Response 200

GET /langs

Response 200

POST /langs

Request

Response 201

Response 400

Response 400

Response 401

GET /invites

Request

Query Parameters

Response 200

Response 200

Response 401

GET /users/:username

Response 200

Response 404

PATCH /users/:username

Request

Response 200

Response 401

Response 403

DELETE /users/:username

Response 204

Response 401

GET /users/:username/langs

Response 200

Response 404

GET /langs/:id

Response 200

Response 404

PATCH /langs/:id

Request

Response 200

Response 403

Response 404

GET /langs/:id/perms

Response 200

Response 401

Response 403

PATCH /langs/:id/perms/:username

Request

Response 200

Response 401

Response 403

Response 404

DELETE /invites/:code

Response 401

GET /invites/:code

Response 200

Response 401

Response 403

Response 404

POST /invites/:code

Request

Response 204

Response 401

GET /invites/:code/:username

Response 200

Response 401

Response 403

Response 404

Response 404

GET /invites/:code/:username/receiver

Response 200

Response 401

Response 403

Response 404

`User`

`Lang`

`LangPermission`

`LangInvite`

`WordClass`

`Word`

GET `/`

GET `/users`

GET `/langs`

POST `/langs`

GET `/invites`

GET `/users/:username`

PATCH `/users/:username`

DELETE `/users/:username`

GET `/users/:username/langs`

GET `/langs/:id`

PATCH `/langs/:id`

GET `/langs/:id/perms`

PATCH `/langs/:id/perms/:username`

DELETE `/invites/:code`

GET `/invites/:code`

POST `/invites/:code`

GET `/invites/:code/:username`

GET `/invites/:code/:username/receiver`

GET `/invites/:code/:username/sender`