Skip to main content

​
Get Collection

Retrieve a single collection by its ID. 
GET /v3/collection/{id}

​
Path Parameters

​
id
string
required
The collection ID (base62 encoded)

​
Response

​
id
string
The collection’s unique ID
​
user
string
ID of the user who created the collection
​
name
string
The collection’s name
​
description
string
The collection’s description
​
created
string
ISO 8601 timestamp of creation
​
updated
string
ISO 8601 timestamp of last update
​
icon_url
string
URL to the collection icon
​
color
integer
Primary color extracted from icon
​
status
string
Collection status: listed, unlisted, rejected, or private
​
projects
array
Array of project IDs in this collection

​
Example Request

curl https://api.modrinth.com/v3/collection/AANobbMI

​
Example Response

{
  "id": "AANobbMI",
  "user": "9dU94F4T",
  "name": "Performance Mods",
  "description": "Best performance optimization mods for Minecraft",
  "created": "2023-01-15T10:00:00Z",
  "updated": "2024-01-15T10:30:00Z",
  "icon_url": "https://cdn.modrinth.com/data/collections/AANobbMI/icon.png",
  "color": 4287168,
  "status": "listed",
  "projects": [
    "AANobbMI",
    "gvQqBUqZ",
    "H8CaAYZC"
  ]
}

​
Get Multiple Collections

Retrieve multiple collections by their IDs. 
GET /v3/collections?ids=["id1","id2"]

​
Query Parameters

​
ids
string
required
JSON array of collection IDs as a string

​
Example Request

curl 'https://api.modrinth.com/v3/collections?ids=["AANobbMI","BBxxyyzz"]'

​
Create Collection

Create a new collection. Requires authentication and COLLECTION_CREATE scope. 
POST /v3/collection

​
Request Body

​
name
string
required
Collection name (3-64 characters)
​
description
string
Collection description (3-255 characters)
​
projects
array
Initial list of project IDs or slugs (max 1024)

​
Example Request

curl -X POST https://api.modrinth.com/v3/collection \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Favorite Mods",
    "description": "A curated list of essential mods",
    "projects": ["sodium", "lithium", "phosphor"]
  }'

​
Example Response

{
  "id": "NewCollID",
  "user": "YourUserID",
  "name": "My Favorite Mods",
  "description": "A curated list of essential mods",
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-15T10:30:00Z",
  "icon_url": null,
  "color": null,
  "status": "listed",
  "projects": [
    "AANobbMI",
    "gvQqBUqZ",
    "H8CaAYZC"
  ]
}

​
Update Collection

Update a collection’s metadata. Requires authentication and COLLECTION_WRITE scope. 
PATCH /v3/collection/{id}

​
Path Parameters

​
id
string
required
The collection ID

​
Request Body

​
name
string
New collection name (3-64 characters)
​
description
string
New collection description (3-256 characters, or null to clear)
​
status
string
New status (moderators can set any status; users can only set listed or unlisted)
​
new_projects
array
Complete new list of project IDs/slugs to replace existing projects (max 1024)

​
Example Request

curl -X PATCH https://api.modrinth.com/v3/collection/AANobbMI \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Collection Name",
    "description": "Updated description",
    "new_projects": ["sodium", "lithium", "phosphor", "ferritecore"]
  }'

​
Delete Collection

Delete a collection. Requires authentication and COLLECTION_DELETE scope. 
DELETE /v3/collection/{id}

​
Path Parameters

​
id
string
required
The collection ID

​
Example Request

curl -X DELETE https://api.modrinth.com/v3/collection/AANobbMI \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Update Collection Icon

Upload a new icon for a collection. Requires authentication and COLLECTION_WRITE scope. 
PATCH /v3/collection/{id}/icon?ext=png

​
Path Parameters

​
id
string
required
The collection ID

​
Query Parameters

​
ext
string
required
Image file extension (png, jpg, etc.)

​
Request Body

Raw image data (must be smaller than 256 KiB).

​
Example Request

curl -X PATCH 'https://api.modrinth.com/v3/collection/AANobbMI/icon?ext=png' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary '@collection-icon.png'

​
Delete Collection Icon

Delete a collection’s icon. Requires authentication and COLLECTION_WRITE scope. 
DELETE /v3/collection/{id}/icon

​
Path Parameters

​
id
string
required
The collection ID

​
Example Request

curl -X DELETE https://api.modrinth.com/v3/collection/AANobbMI/icon \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get User’s Collections

Get all collections created by a specific user. 
GET /v3/user/{user_id}/collections

​
Path Parameters

​
user_id
string
required
User ID or username

​
Response

Returns an array of collections visible to the requester.

​
Example Request

curl https://api.modrinth.com/v3/user/jellysquid/collections

​
Common Use Cases

Creating a Curated Modpack List
  1. Create a collection with POST /v3/collection
  2. Add an icon with PATCH /v3/collection/{id}/icon
  3. Update the project list as needed with PATCH /v3/collection/{id}
  4. Share the collection URL with others
Managing Collection Visibility Collections support four status levels:
  • listed - Public and discoverable
  • unlisted - Public but not in search results
  • private - Only visible to the creator
  • rejected - Rejected by moderators (moderator action only)
Collection Limits Users have limits on how many collections they can create. The limit depends on their account type and is enforced when creating new collections. Project Management When updating the project list:
  • Use new_projects to completely replace the existing list
  • Projects are referenced by ID or slug
  • Non-existent projects will cause an error
  • Maximum 1024 projects per collection
  • The collection’s updated timestamp is automatically set
Best Practices
  1. Descriptive Names: Use clear, descriptive names that explain the collection’s purpose
  2. Good Descriptions: Write helpful descriptions that explain what users will find
  3. Quality Over Quantity: Curate carefully rather than adding every related project
  4. Keep Updated: Remove deprecated projects and add new relevant ones
  5. Use Icons: Add custom icons to make collections visually distinctive
  6. Appropriate Status: Use listed for public collections, unlisted for works-in-progress
Permissions
  • Only the collection creator can edit or delete their collections
  • Moderators can edit any collection’s status
  • Anyone can view listed collections
  • Only the creator can view private collections
  • Anyone with the link can view unlisted collections