Skip to main content

API Reference

This section contains the full API reference for Waifu.im, auto-generated from the OpenAPI specification [https://api.waifu.im/openapi/v1.json].

Base URL​

https://api.waifu.im

Interactive Documentation​

An interactive API explorer powered by Scalar is available directly on the API at https://api.waifu.im/scalar/v1. You can use it to test endpoints and view request/response examples.

Authentication​

The API supports two authentication methods:

  • JWT Token -- Obtained via Discord OAuth2 (POST /auth/discord). Passed as Authorization: Bearer <token>.
  • API Key -- Passed in the X-Api-Key header.

Some endpoints require authentication. Check the endpoint details below or the Authentication page for more information.

Response Format​

All responses are JSON. Paginated endpoints return:

{
  "items": [],
  "pageNumber": 1,
  "totalPages": 10,
  "totalCount": 100,
  "hasPreviousPage": false,
  "hasNextPage": true,
  "maxPageSize": -1,
  "defaultPageSize": 30
}
  • maxPageSize: The maximum allowed page size for this endpoint. A value of -1 means unlimited.
  • defaultPageSize: The default page size used when no PageSize parameter is provided.

Error Handling​

Errors follow the RFC 9457 Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "fieldName": ["Error message"]
  }
}