API Documentation is under construction!

Global API Ratelimits

Cloudflare has a strict 250 requests per-IP per-endpoint per 10-minute window on all public API endpoints. Exceeding this will result in a 24 hour Cloudflare IP ban on that endpoint.

Our soft-limit for API requests is 200 requests per-IP per-endpoint per 10-minute window, as a mitigation to Cloudflare bans.

Fetching user data

GET /api/:userId

Description

Retrieves a users information based on their unique ID.

This endpoint returns data in application/json format.

Authentication

This is a public endpoint - no authentication required.

URL Parameters

Parameter Type Required Description Constraints Default Value
userId integer Yes The unique ID of the target user Must be valid userId N/A (null)

Request Example

    GET /api/123 HTTP/1.1
    Host: yourdomain.com

Response Examples

Success (HTTP 200)

    {
        "user": {
            "id": 123,
            "username": "exampleUser",
            "pfp": "/avatars/profile123.jpg",
            "discriminator": "0001",
            "biography": "This user has not written their Bio"
        }
    }

Error Responses

Status Code Error Description
400 Invalid userId When userId is not a valid number
404 User not found When no user exists with the specified ID
500 Database error When there's a server-side database issue
1015 Cloudflare ratelimit ban Exceeded 250 requests per 10 minute window

Ratelimiting and Caching

Global Ratelimits apply to all public API Endpoints.

Responses include caching headers:

  • Cache-Control: public, max-age=300 (5 minutes)

Use Cases

  1. Showing preview content when hovering over user mentions
  2. Syndicating user content to external sites

Client-Side Implementation Example

In JavaScript:

    async function getUserInfo(userId) {
        try {
            const response = await fetch(`/api/${userId}`, { headers: { 'Accept': 'application/json' } });
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            return await response.json();
        } catch (error) {
            console.error('Failed to fetch user info:', error);
            return null;
        }
    }

    // Usage:
    getUserInfo(123).then(data => {
        console.log('User info:', data);
    });

Using cURL:

    curl https://yourdomain.com/api/1

Notes

  • The response format only includes user metadata
GET /api/:userId/posts/:limit?

Description

Retrieves a list of posts for a specific user by their unique ID. The number of posts returned can be optionally limited.

This endpoint returns data in application/json format.

Authentication

This is a public endpoint - no authentication required.

URL Parameters

Parameter Type Required Description Constraints Default Value
userId integer Yes The unique ID of the target user Must be valid userId N/A (null)
limit integer No Maximum number of posts to return 1-50 10

Request Example

    GET /api/123/posts/5 HTTP/1.1
    Host: yourdomain.com

Response Examples

Success (HTTP 200)

    {
        "user": {
            "id": 123,
            "username": "exampleUser",
            "pfp": "/avatars/profile123.jpg",
            "discriminator": "0001"
        },
        "posts": [
            {
                "id": 456,
                "title": "My Awesome Post",
                "created_at": "2023-06-15T14:30:00.000Z",
                "updated_at": "2023-06-15T14:30:00.000Z",
                "filename": "post456.jpg",
                "url": "/uploads/post456.jpg"
            },
            ...
        ]
    }

Error Responses

Status Code Error Description
204 No Content When userId has no posts
400 Invalid userId When userId is not a valid number
404 User not found When no user exists with the specified ID
500 Database error When there's a server-side database issue
1015 Cloudflare ratelimit ban Exceeded 250 requests per 10 minute window

Ratelimiting and Caching

Global Ratelimits apply to all public API Endpoints.

Responses include caching headers:

  • Cache-Control: public, max-age=300 (5 minutes)

Use Cases

  1. Showing preview content when hovering over user mentions
  2. Syndicating user content to external sites

Client-Side Implementation Example

In JavaScript:

    async function getUserPosts(userId, limit = 10) {
        try {
            const response = await fetch(`/api/${userId}/posts/${limit}`, { headers: { 'Accept': 'application/json' } });
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            return await response.json();
        } catch (error) {
            console.error('Failed to fetch posts:', error);
            return null;
        }
    }

    // Usage:
    getUserPosts(123, 5).then(data => {
        console.log('User posts:', data);
    });

Using cURL:

    curl https://yourdomain.com/api/123/posts/5

Notes

  1. The response format includes both user metadata and an array of posts in reverse chronological order
  2. Posts are always returned in reverse chronological order (newest first)
  3. File url fields are relative, meaning you have to specify the root domain
  4. Timestamps are ISO 8601 strings in UTC
  5. If the optional limit parameter is not specified, up to 10 posts are returned by default