Contribute to the API

The HTTP API at api.dicebear.com is built with Fastify. It lives in a separate repository at dicebear/api.

Requirements

• A GitHub account
• Git installed (Learn how to install Git here)
• Node.js (>= 20.10) and Npm installed
• Docker (optional, for container testing)

Project structure

dicebear/api/
├── src/              # Application source code
│   ├── app.ts        # Fastify app setup
│   ├── server.ts     # Server entry point
│   ├── config.ts     # Environment-based configuration
│   ├── types.ts      # Shared TypeScript types
│   ├── handler/      # Request handlers
│   ├── routes/       # Route definitions
│   └── utils/        # Utility functions (query string parsing, etc.)
├── versions/         # DiceBear library version packages (see below)
│   ├── 5.x/
│   ├── 6.x/
│   ├── 7.x/
│   ├── 8.x/
│   └── 9.x/
├── scripts/          # Build scripts (e.g. font extraction)
├── tests/            # Test suite
├── Dockerfile        # Production container definition
├── package.json      # Workspaces: root + versions/*
└── tsconfig.json

Versioning

The API serves multiple DiceBear library versions in parallel. Each version is accessible via a URL prefix, for example /10.x/avataaars/svg.

• Each version lives in versions/<major>.x/ as a separate workspace package (e.g. @dicebear/api-9).
• Each version package depends on the corresponding @dicebear/core and @dicebear/collection versions.
• Which versions are loaded at runtime is controlled by the VERSIONS environment variable (default: 5,6,7,8,9,10).
• When a new major DiceBear version is released, a new versions/<major>.x/ package is added.

INFO

Versions 5–8 will reach End of Life on April 30, 2028 and will be removed from the public API. See the HTTP API documentation for the current support status.

Set up locally

1. Create a fork from the dicebear/api repository.

   WARNING

   Make sure you fork dicebear/api, not the main dicebear/dicebear repository.

2. Clone the project:

   git clone https://github.com/<YOUR_GITHUB_USERNAME>/api.git

   If you've set up SSH, you can do this instead:

   git clone git@github.com:<YOUR_GITHUB_USERNAME>/api.git

3. Install dependencies:

   cd api
   npm install

4. Create a build:

   npm run build

Verifying your changes

You can start the API locally on your computer with the following command to check your changes:

npm run dev

Open http://localhost:3000/ in your browser to see your changes.

You can also run the test suite:

npm test

Branching and committing

Once you are happy with the changes, create a branch so you can commit the changes.

git checkout -b <YOUR_BRANCH>

Afterwards you have to add your changes to the stage and commit them.

git add .
git commit -m "Change: <YOUR_CHANGES>"
git push origin <YOUR_BRANCH>

Creating a Pull Request

Follow these instructions to create a Pull Request against dicebear/api.

Deployment (maintainers only)

INFO

Only maintainers with write access to the repository can deploy the API. This section is documented here for completeness.

The API (api.dicebear.com) is deployed as a Docker container. A GitHub Actions workflow (docker.yml) builds and publishes the image to Docker Hub: dicebear/api.