API Endpoint Architecture#

Misskey's API departs from REST conventions: all ~450 endpoints use POST by default, are addressed at flat paths under /api/<endpoint-name>, and are centrally registered in a single file. Configuration for auth, rate limiting, permissions, and validation lives in per-endpoint metadata objects rather than middleware or decorators scattered across the codebase.

Registration: endpoint-list.ts#

The single source of truth for all API endpoints is endpoint-list.ts. Every endpoint is registered with a one-liner export * as statement that maps its URL path to its implementation module 1:

export * as 'notes/create' from './endpoints/notes/create.js';
export * as 'admin/roles/list' from './endpoints/admin/roles/list.js';

The file currently has 451 lines and registers ~450 endpoints 2. Adding a new endpoint requires a single new line here — the file's own comment states: "When you add new endpoint, you should add it to this file" 1. This registry also drives API documentation generation and the NestJS EndpointsModule.

endpoints.ts consumes the registry by iterating Object.entries(endpointsObject) to produce the typed IEndpoint[] array that the rest of the server uses 3.

Endpoint File Structure#

Each endpoint module exports exactly two named values plus a default class 4:

The abstract Endpoint base class in endpoint-base.ts compiles the AJV validator at construction time and wraps the executor in a exec() method that handles file-required checks and parameter validation before calling the user-provided callback 5.

IEndpointMeta — The Metadata Object#

Defined in endpoints.ts, IEndpointMeta controls all cross-cutting behavior per endpoint:

TypeScript enforces that requireCredential: true endpoints must also declare kind — and similarly for requireModerator/requireAdmin — via a discriminated union on IEndpointMeta 14.

Request Lifecycle#

ApiServerService registers Fastify routes by iterating over endpoints and calling fastify.all('/' + endpoint.name, ...) for each 15. GET is blocked at the route handler unless meta.allowGet is set 16.

ApiCallService then processes each request in order:

1. Token extraction — from Authorization: Bearer <token> header or i body field 17
2. Authentication — via AuthenticateService 18
3. Rate limiting — applied if meta.limit is set; per-user or per-IP (if enableIpRateLimit); role-based rateLimitFactor modifies the limit 19
4. Credential/role checks — requireCredential, requireModerator, requireAdmin, requiredRolePolicy, prohibitMoved 20
5. OAuth scope check — validates token.permission against meta.kind 21
6. Param coercion — boolean/integer params are coerced from strings for GET/multipart requests 22
7. Handler execution — ep.exec() runs; AJV validates paramDef inside Endpoint.exec before the callback 23

Errors surface as structured JSON with { error: { message, code, id, kind } } 24. Rate-limit errors (HTTP 429) include a Retry-After header 25.

GET Support & Caching#

By default every endpoint rejects GET with HTTP 405. Endpoints opt into GET by setting allowGet: true in meta 10 — for example, emoji sets allowGet: true, cacheSec: 3600 26, enabling a one-hour public cache. When allowGet is enabled and the request is GET, query string parameters are used as the body 27.

Key Files#